Table of Contents Previous Chapter Chapter 4: Using BURT From a UNIX Prompt

Chapter 4: Using BURT From a UNIX Prompt

BURT can be executed in two ways; from a UNIX prompt passing it arguments on the command line or from its Graphic User Interface (GUI). In this chapter we describe how to run BURT from the UNIX prompt, or command line.

We make two assumptions here. First, that the reader is already familiar with all of BURT's terminology explained above. Second, that the reader is familiar with executing commands at the UNIX prompt that accept arguments on the command line in the form of switches.

1. burtrb

This is BURT's back up tool. It takes as input one or more request files and produces a single Absolute snapshot file.

The user must always specify at least one request file. Request files are specified using the -f (for file) option. As with all of BURT's programs, the user may mix SDDS and non-SDDS files freely in a single execution. To specify the two request files req1 and req2, the user would enter the command:

>  burtrb -f req1 req2
The snapshot file is written to the UNIX file stdout. In most cases this means that the snapshot file is written to the screen. The user can instruct BURT to write the snapshot file to a file, rather than the screen, by using -o (for output) option. Extending the example above to writing the snapshot to a file called snap, the user would enter the command:

>  burtrb -f req1 req2 -o snap
Options can appear in any order. In other words, the above command is equivalent to the following command:

>  burtrb -o snap -f req1 req2
This ability to specify options in any order on the command line is true for all of BURT's programs.

The format of the snapshot files can be either SDDS compliant or not. By default, burtrb will set the snapshot file format based on the format of the request files. Therefore, if all the request files have the same format, burtrb will generate a snapshot file of the same format, otherwise it will generate an SDDS snapshot file. The user always has the option of explicitly specifying the format of the generated snapshot file by specifying either -sdds or -nosdds.

To explicitly instruct burtrb to generate an SDDS snapshot file in our example the user would use the following command:

>  burtrb -f req1 req2 -o out -sdds
Whenever creating a snapshot file, the user may augment the snapshot file with comments and/or keywords. These comments and keywords appear in the header portion of the snapshot file. This is done with the -c (for comments) and -k (for keywords) options. To add the comment ``took this on a good day'' with the keywords ``linac best tune'' the user would use the following command:

>  burtrb -f req1 req2 -o out -sdds -c took this on a good day -k linac best tune
The command line can get very long. Occasionally, it is so long that it cannot fit on one line. This is not a problem for BURT. The user must always wait until the entire command line has been typed before hitting the carriage return. Hitting the carriage return sends the command to BURT and hitting the carriage return prematurely will only send the information typed in so far.

By default, burtrb writes the terse version of the log file to UNIX's stderr, which is typically the screen. The user can instruct burtrb to increase the information in the log file by reporting everything it is doing by specifying the -v (for verbose) option. Additionally, the user can also instruct burtrb to place the log file into a file rather than the screen with the -l (for log file) option. Here is an example of requesting a verbose log file sent to the file log (omitting the comments and keywords above).

>  burtrb -f req1 req2 -o out -sdds -v -l log
All the programs in BURT communicate with the IOCs using a facility called channel access [3]. In doing so, it asks channel access to find the values of the process variables on the IOCs. Occasionally, the medium over which channel access communicates becomes saturated with heavy use. This slows down response times and channel access is sometimes fooled into thinking that it cannot find a value because it has taken too long. This rarely happens, but if it does, the user can instruct channel access to try a few more times before giving up. This is done with the -r (for retry) option. Specifying retry levels does not slow burtrb down, it stops as soon as it finds the value. By default, burtrb instructs channel access to try once. The -r option instructs it how many more times to try. Here is an example of calling burtrb asking channel access to try two more times:

>  burtrb -f req1 req2 -o out -sdds -v -l log -r 2
Finally, as a diagnostic aid there is a debugging option. All non-SDDS request files are processed by the C pre-processor to interpret any #define or #include directives that might appear in those files. This is done before burtrb gets the files. Each non-SDDS request file is processed by the C pre-processor which generates a new temporary file. This new temporary file reflects the effects of all the #define and #include statements and it is actually these files that are used as input to burtrb.

By default, burtrb removes these files at the end of its execution. However, the user can instruct burtrb not to remove these files, presumably for later inspection, by specifying the -d (for debug) option. When doing so, the user assumes the responsibility of removing the files. Extending our example, the command would be:

>  burtrb -f req1 req2 -o out -sdds -v -l log -r 2 -d
It is up to the EPICS system administrator that installs BURT to decide where these files are generated. It is typically the /tmp directory. The files are named by the loginid of the user calling burtrb and the time at which burtrb was executed.

loginid_YYMMDD_HHmmSS_I

where

loginid - loginid of user executing BURT

YY - year

MM - month

DD - day

HH - hour

mm - minute

SS - second

I - integer index [0-9]

If they are not in /tmp, contact the EPICS system administrator and have he/she look at the #define macro PUBLICDIRECTORY in burtcommon.h.

As with all of BURT's programs, simply typing in the name of the program without any arguments places a quick reference usage message onto the screen.

>  burtrb

usage: burtrb -f req1 {req2 ...} {-l logfile} {-o outfile} {-d} {-v} {-c ... comments ...} {-k keyword1 ... keywordn} {-r retry_count} {-sdds or -nosdds}

where

-f req1 {req2 ...} - Request file names. This is the only switch that is not optional. You must specify at least one request file.

-l logfile - Log file name. The name of the file where all logging messages (e.g. error messages, reports of process variables that were not found) go. The default is stderr.

-o outfile - Snapshot file name. The name of the file where the snapshot information goes. The default is stdout.

-d - Debug. Save the files created by processing the request files with the C preprocessor. The default is to delete these files.

-v - Verbose. This increases the amount of information displayed in the logfile.

-c ...comments ... - Comments. Adds comments to the header of the snapshot file.

-k keyword1 ... keywordn - Keywords. Adds keywords to the header of the snapshot file.

-r retry_count - Number of additional attempts to wait for connections. The program will attempt to find all the process variables. If it is unsuccessful, it will try this many more times to establish connections. The default value is 0.

-sdds or -nosdds - SDDS/non-SDDS snapshot file. Explicitly specifying that the generated snapshot file will be SDDS/non-SDDS compliant. The default is to adopt the SDDS type from the input(s). If there is a heterogenous set of inputs (some SDDS and some non-SDDS), the default is to produce and SDDS compliant snapshot file.

2. burtwb

This is BURT's restore tool. It takes as input one or more snapshot files and zero or more dependency files. Depending on the contents of the snapshot files, it will produce a single Nowrite snapshot file.

The user must always specify at least one snapshot file. Snapshot files are specified using the f (for file) option. As with all of BURT's tools, the user may mix SDDS and non-SDDS files freely in a single execution. To specify the two snapshot files snap1 and snap2, the user would enter the command:

>  burtwb -f snap1 snap2
Burtwb takes the contents of the snapshot files and changes the values on the IOCs accordingly. Some of the values in the snapshot files are tagged as RO (Read Only) or RON (Read Only Notify). These values are not restored to the IOCs.

Snapshot files always have a type: Absolute, Relative, or Nowrite. The type of snapshot file instructs burtwb how to restore the values in the file to the IOCs. By default, the values in an Absolute snapshot file replace the values on the IOCs and the values in a Relative snapshot file are added to the values on the IOCs. The values in Nowrite snapshot files do not affect the values on the IOCs.

The user can instruct burtwb to treat Absolute snapshot files as Relative and vice versa. In other words, the user can instruct burtwb to treat the values in an Absolute snapshot file as though they appeared in a Relative snapshot file, thus adding the values rather than replacing the values, by specifying the -add (for add) option. The user can also instruct burtwb to treat the values in a Relative snapshot file as though they appeared in an Absolute snapshot file, thus replacing the values rather than adding them, by specifying the -replace (for replace) option.

The -add option is applied to all the Absolute snapshot files found in the command line, and likewise the -replace option is applied to all the Relative snapshot files found in the command line.

These are independent options, meaning the user can specify neither, both, or one of them. To specify the -add option only:

>  burtwb -f snap1 snap2 -add
Options can appear in any order. In other words, the above command is equivalent to the following command:

>  burtwb -add -f snap1 snap2
To specify the -replace option only:

>  burtwb -f snap1 snap2 -replace
To specify both:

>  burtwb -f snap1 snap2 -add -replace
Burtwb produces a single Nowrite snapshot file when it encounters RON values in its set of input snapshot files, otherwise it produces no output file.

The snapshot file is written to the UNIX file stdout. In most cases this means that the snapshot file is written to the screen. The user can instruct burtwb to write the snapshot file to the a file, rather than the screen, by using -o (for output) option. For example, extending the example above, and omitting the -add and -replace options, writing the snapshot to a file called nowrite.snap, the user would enter the command:

>  burtwb -f snap1 snap2 -o nowrite.snap
If there are no RON values in snap1 or snap2, then nowrite.snap will not be created.

The format of the snapshot files can be either SDDS compliant or not. By default, burtwb will set the snapshot file format based on the format of the request files. By default, if all the request files have the same format, burtwb will generate a snapshot file of the same format, otherwise it will generate an SDDS snapshot file. The user always has the option of explicitly specifying the format of the generated snapshot file by specifying either -sdds or -nosdds.

To explicitly instruct burtwb to generate an SDDS snapshot file in our example the user would use the following command:

>  burtwb -f snap1 snap2 -o nowrite.snap -sdds
Whenever creating a snapshot file, the user has the option of augmenting the snapshot file with comments and/or keywords. These comments and keywords appear in the header portion of the snapshot file. Using the -c (for comments) and -k (for keywords) options. Adding the comments `'restored again'' with the keywords `'restoring linac best tune'' the user would use the following command:

>  burtwb -f snap1 snap2 -o nowrite.snap -sdds -c restored again -k restoring linac best 
tune
Once again, we see that the command line can get very long. Sometimes it is so long that it cannot fit on one line. This is not a problem for BURT. It is important to remember to wait until you have typed in the entire command line before hitting the carriage return. Hitting the carriage return sends the command to BURT and hitting the carriage return prematurely will only send the information you have typed in so far.

By default, burtwb writes the terse version of the log file to UNIX's stderr, which is typically the screen. The user can instruct burtwb to increase the information in the log file by reporting everything it is doing by specifying the -v (for verbose) option. The user can also instruct burtwb to place the log file into a file rather than the screen with the -l (for log file) option. Here is an example of requesting a verbose log file sent to the file log (omitting the comments and keywords above).

>  burtwb -f snap1 snap2 -o nowrite.snap -sdds -v -l log
Recall that all the programs in BURT communicate with the IOCs using a facility called channel access. In doing so, it asks channel access to find the values of the process variables from the IOCs. Occasionally, the medium over which channel access communicates becomes saturated with heavy use. This slows down response times and channel access is sometimes fooled into thinking that it cannot find a value because it has taken too long. This rarely happens, but if it does, the user can instruct channel access to try a few more times before giving up. This is done with the -r (for retry) option. Specifying retry levels does not slow burtwb down, it stops as soon as it finds the value. By default, burtwb instructs channel access to try once. The -r option tells it how many more times to try. Here is an example of calling burtwb asking channel access to try two more times:

>  burtwb -f snap1 snap2 -o nowrite.snap -sdds -v -l log -r 2
In addition to the snapshot files, the user can specify a set of zero or more dependency files as input to burtwb with the -p (for predicates) option. These files specify conditions that are tested before burtwb restores the snapshots to the IOCs. Extending our example to include dependency files dep1, dep2, and dep3, the call to burtwb would look like this:

>  burtwb -f snap1 snap2 -o nowrite.snap -sdds -v -l log -r 2 -p dep1 dep2 dep3
Finally, as a diagnostic aid there is a debugging option. Burtwb processes dependency files by writing, compiling, and executing a C program on the fly from the conditions specified in the dependency files. Before writing the C program, each dependency file is processed through the C pre-processor to interpret any #define or #include directives that might appear. Each dependency file is processed this way and each one generates a new temporary file that reflects the effects of all the #define and #include statements. It is actually these files that burtwb uses to write its C program.

By default, burtwb removes these temporary files as well as the C source code and the executable program at the end of its execution. However, the user can instruct burtwb not to remove these files, presumably for later inspection, by specifying the -d (for debug) option. When doing so, the user assumes the responsibility of removing the files. Extending our example to include the debug option, the call to burtwb would look like this:

>  burtwb -f snap1 snap2 -o nowrite.snap -sdds -v -l log -r 2 -p dep1 dep2 dep3 -d
It is up to the EPICS system administrator that installs BURT to decide where these files are generated. It is typically the /tmp directory. The files are named by the loginid of the user calling burtwb and the time at which burtwb was executed.

loginid_YYMMDD_HHmmSS_I

where

loginid - loginid of user who executed BURT

YY - year

MM - month

DD - day

HH - hour

mm - minute

SS - second

I - integer index [0-9]

If they are not in /tmp, contact the EPICS system administrator and have he/she look at the #define macro PUBLICDIRECTORY in burtcommon.h.

As with all of BURT's programs, simply typing in the name of the program without any arguments places a quick reference usage message onto the screen.

>  burtwb
usage: burtwb -f snap1 {snap2 ...} {-l logfile} {-o outfile} {-c ... comments ...} {-k keyword1 ... keywordn} {-d} {-v} {-p dep1 ... depn} {-r retry count} {-add} {-replace} {-sdds or -nosdds}

where

-f snap1 {snap2 ...} - Snapshot file names. This is the only switch that is not optional. You must specify at least one snapshot file.

-l logfile - Log file name. The name of the file where all logging messages (e.g. error messages, reports of process variables that were not found) go. The default is stderr.

-o outfile - Snapshot file name. If any of the snapshot files read only notify values, this file is created and those values are placed there. If none of the snapshot files have read only notify values, then no file is created. The default is stdout.

-c ... comments ... - Comments. Adds comments to the header of the snapshot file.

-k keyword1 ... keywordn - Keywords. Adds keywords to the header of the snapshot file.

-d - Debug. Save the files created by processing the dependency files with the C preprocessor. The default is to delete these files.

-v - Verbose. This increases the amount of information displayed in the logfile.

-p dep1 ... depn - Dependency file names. The names of the dependency files containing predicates to be evaluated before writing the values from the snapshot files.

-r retry count - Number of additional attempts to wait for connections. The program will attempt to find all the process variables. If it is unsuccessful, it will try this many more times to establish connections. The default value is 0.

-add - Absolute snapshots written as adds. All the absolute snapshots, i.e., those taken directly off IOCs, will be written as additions to the values found on the IOCs. The default is to write the absolute snapshots as replacement values on the IOCs.

-replace - Relative snapshots written as replacements. All the relative snapshots, i.e., those generated by adding or subtracting two snapshots, will be written to replace the values on the IOCs. The default is to write the relative snapshots as additions to the values on the IOCs.

-sdds or -nosdds - SDDS/non-SDDS snapshot file. Explicitly specifying that the generated snapshot file will be SDDS/non-SDDS compliant. The default is to adopt the SDDS type from the input(s). If there is a heterogenous set of inputs (some SDDS and some non-SDDS), the default is to produce and SDDS compliant snapshot file.

3. burtmath

This is BURT's arithmetic tool. It allows the user to add or subtract the contents of two snapshot files producing a Relative snapshot file. It also can multiply the contents of a single snapshot file by a scalar constant producing a snapshot file of the same type. In this case, the output snapshot file inherits its type (Absolute, Relative, or Nowrite) from the input snapshot file.

When adding or subtracting snapshot files, only like terms will be added and subtracted. This means that only those process variables with the same name and same number of elements that appear in both input snapshot files will appear in the output snapshot file. For devices, only those that have the same device name and same lineage that appear in both input snapshot files will appear in the output snapshot file.

When supplying two snapshot files, the default operation is subtraction. Determining the difference of two snapshot files snap1-snap2 can be done:

>  burtmath snap1 snap2
or 

>  burtmath snap1 snap2 -sub
Determining the sum of two snapshot files snap1+snap2 can be done:

>  burtmath snap1 snap2 -add
When supplying one snapshot file, the user must use the -mult (for multiplication) option. By default burtmath will multiply the values in the snapshot file by the scalar constant 1. Here is an example:

>  burtmath snap1 -mult
which is equivalent to 

>  burtmath snap1 -mult 1
which, in turn, is equivalent to 

>  burtmath snap1 -mult 1.0
Optionally, the user can the -mult option and supply a scalar constant other than 1. Here is an example multiplying the values in snap1 by the scalar constant 2.4:

>  burtmath snap1 -mult 2.4
The snapshot file is written to the UNIX file stdout. In most cases this means that the snapshot file is written to the screen. The user can instruct BURT to write the snapshot file to the a file, rather than the screen, by using -o (for output) option. For example, extending the example above to write the snapshot to a file called snap.sum, the user would enter the command:

>  burtmath snap1 snap2 -add -o snap.sum
Options can appear in any order. In other words, the above command is equivalent to the following command:

>  burtmath snap1 snap2 -o snap.sum -add
Note when using burtmath the filenames must always appear after the word burtmath. The filenames are not options here. Everything else on the command line is an option and may appear in any order. This ability to specify options in any order on the command line is true for all of BURT's programs.

The format of the snapshot files can be either SDDS compliant or not. By default, burtmath will set the snapshot file format based on the format of the input snapshot file(s). By default, if all the snapshot files have the same format, burtmath will generate a snapshot file of the same format, otherwise it will generate an SDDS snapshot file. The user always has the option of explicitly specifying the format of the generated snapshot file by specifying either -sdds or nosdds.

To explicitly instruct burtmath to generate an SDDS snapshot file in our example we would use the following command:

>  burtmath snap1 snap2 -add -o snap.sum -sdds
Whenever creating a snapshot file, the user has the option of augmenting the snapshot file with comments and/or keywords. These comments and keywords appear in the header portion of the snapshot file. This is done by using the -c (for comments) and the -k (for keywords) options. Adding the comment `'trying something goofy'' with the keywords `'linac sum'' the user would use the following command:

>  burtmath snap1 snap2 -add -o snap.sum -sdds -c trying something goofy -k linac sum
Once again, we see that the command line can get very long. Sometimes it is so long that it cannot fit on one line. This is not a problem for BURT. It is important to remember to wait until you have typed in the entire command line before hitting the carriage return. Hitting the carriage return sends the command to BURT and hitting the carriage return prematurely will only send the information you have typed in so far.

By default, burtmath writes the terse version of the log file to UNIX's stderr, which is typically the screen. The user can instruct burtmath to increase the information in the log file by reporting everything it is doing by specifying the -v (for verbose) option. The user can also instruct burtmath to place the log file into a file rather than the screen with the -l (for log file) option. Here is an example of requesting a verbose log file sent to the file log (omitting the comments and keywords above).

>  burtmath snap1 snap2 -add -o snap.sum -sdds -v -l log
As with all of BURT's programs, simply typing in the name of the program without any arguments places a quick reference usage message onto the screen.

>  burtmath
usage: burtmath (snap1 snap2 {-add or -sub}) or (snap1 -mult m) {-l logfile} {-o outfile} {-v} {-c ... comments ...} {-k keyword1 ... keywordn} {-sdds or -nosdds}

where

snap1 snap2 {-add or -sub} - Adding/subtracting snapshots. Here you wish to either add or subtract exactly two snapshot files. You must specify exactly two snapshot files when performing either addition or subtraction. The default operation is sub (subtraction).

snap1 -mult m - Multiplying snapshots. Here you wish to multiply all the values in snap1 by multiplication factor m.

-l logfile - Log file name. The name of the file where all logging messages (e.g. error messages, reports of process variables that were not found) go. The default is stderr.

-o outfile - Result file name. The name of the file where the resulting information goes. The default is stdout.

-v - Verbose. This increases the amount of information displayed in the logfile.

-c ... comments ... - Comments. Adds comments to the header of the result file.

-k keyword1 ... keywordn - Keywords. Adds keywords to the header of the result file.

-sdds or -nosdds - SDDS/non-SDDS snapshot file. Explicitly specifying that the generated snapshot file will be SDDS/non-SDDS compliant. The default is to adopt the SDDS type from the input(s). If there is a heterogenous set of inputs (some SDDS and some non-SDDS), the default is to produce and SDDS compliant snapshot file.

4. burtset

This is BURT's set operation program. It performs set operations (union, intersection, and difference) on a pair of request files and outputs a request file.

The user must specify exactly two request files. This is done with the -f (for file) option. As with all of BURT's programs, the user may mix SDDS and non-SDDS files freely in a single execution. To specify the two request files req1 and req2, the user would enter the command:

>  burtset -f req1 req2
The default set operation is to perform a union of the two files. That is, produce a request file that has those process variables and devices that appear in either input request file. The above command is therefore equivalent to the command:

>  burtset -f req1 req2 -union
Options can appear in any order. In other words, the above command is equivalent to the following command:

>  burtset -union -f req1 req2
The result of a union operation is that all the names that appear in both of the input files appear in the output file. If a process variable or device appears in exactly one file, it will appear in the output file. If a process variable or device appears in both files, it will appear once in the output file. In this case it will be tagged RON if it is RON in either source file. If it is not RON in either file, it will be tagged RO if it is RO in either source file. Otherwise it will not be tagged at all. If the process variable or device appears in both files with a different number of elements in both, burtset arbitrarily chooses one of the number of element requests and propagates that to the output file.

The user may request an intersection be taken. That is, produce a request file that has those process variables and devices found in both input request files. To request an intersection of the request files req1 and req2:

>  burtset -f req1 req2 -inter
This intersection match is done on name only, it ignores any tagging or number of requested elements. It propagates tagging based on maximizing severity. In other words, if there is a match then the tag of the output will be RON if either source is RON. If neither is RON, then the tag of the output will be RO if either is RO. Otherwise, the output will not be tagged. Additionally, in the case of the match, burtset arbitrarily chooses the number of requested for the output.

The user may request a difference be taken. That is, produce a request file that has those process variables and devices found in req1 but not req2. To request a difference req1-req2: 

>  burtset -f req1 req2 -diff
Matching is done with respect to name only, i.e.,ignoring tagging or number of requested. As the operation implies, the output file will be a subset of the first request file.

Independent of the chosen set operation, the resulting request file is written to the UNIX file stdout. In most cases this means that the request file is written to the screen. The user can instruct BURT to write the request file to the a file, rather than the screen, by using -o (for output) option. Extending the example above to write the request to a file called union.req, the user would enter the command:

>  burtset -f req1 req2 -union -o union.req
The format of the output request file can be either SDDS compliant or not. By default, burtset will set the output request file format based on the format of the input request files. By default, if all the input request files have the same format, burtset will generate a request file of the same format, otherwise it will generate an SDDS request file. The user always has the option of explicitly specifying the format of the generated request file by specifying either -sdds or nosdds.

To explicitly instruct burtset to generate an SDDS request file in our example the user would use the following command:

>  burtset -f req1 req2 -union -o union.req -sdds
By default, burtset writes the terse version of the log file to UNIX's stderr, which is typically the screen. The user can instruct burtset to increase the information in the log file by reporting everything it is doing by specifying the -v (for verbose) option. Additionally, the user can also instruct burtrb to place the log file into a file rather than the screen with the -l (for log file) option. Here is an example of requesting a verbose log file sent to the file log.

>  burtset -f req1 req2 -union -o union.req -sdds -v -l log
Finally, as a diagnostic aid there is a debugging option. All non-SDDS request files are processed by the C pre-processor to interpret any #define or #include directives that might appear in those files. This is done before burtset gets the files. Each non-SDDS request file is processed by the C pre-processor which generates a new temporary file. This new temporary file reflects the effects of all the #define and #include statements and it is actually these files that are used as input to burtset.

By default, burtset removes these files at the end of its execution. However, the user can instruct burtset not to remove these files, presumably for later inspection, by specifying the -d (for debug) option. When doing so, the user assumes the responsibility of removing the files. Extending our example, the command would be:

>  burtset -f req1 req2 -union -o union.req -sdds -v -l log -d
It is up to the EPICS system administrator that installs BURT to decide where these files are generated. It is typically the /tmp directory. The files are named by the loginid of the user calling burtset and the time at which burtset was executed.

loginid_YYMMDD_HHmmSS_I

where

loginid - loginid of user who executed BURT

YY - year

MM - month

DD - day

HH - hour

mm - minute

SS - second

I - integer index [0-9]

If they are not in /tmp, contact the EPICS system administrator and have he/she look at the #define macro PUBLICDIRECTORY in burtcommon.h.

As with all of BURT's programs, simply typing in the name of the program without any arguments places a quick reference usage message onto the screen.

>  burtset
usage: burtset -f req1 req2 {-union or -inter or -diff} {-l logfile} {-o outfile} {-d} {-v} {-sdds or -nosdds}

where

-f req1 req2 - Request filenames. This is the only switch that is not optional. You must specify at least two request files.

-union or -inter or -diff - Set operation. The set operation (union, intersection, or difference) to be performed on the two request files. The default is union.

-l logfile - Log file name. The name of the file where all logging messages (e.g. error messages) go. The default is stderr.

-o outfile - Request file name. The name of the file where the result of the set operation goes. The default is stdout.

-d - Debug. Save the files created by processing the request files with the C preprocessor. The default is to delete these files.

-v - Verbose. This increases the amount of information displayed in the logfile.

-sdds or -nosdds - SDDS/non-SDDS snapshot file. Explicitly specifying that the generated snapshot file will be SDDS/non-SDDS compliant. The default is to adopt the SDDS type from the inputs. If there is a heterogenous set of inputs (one SDDS and the other non-SDDS), the default is to produce and SDDS compliant snapshot file.

5. burtconvertsnap

This is BURT's snapshot conversion tool. It takes as input one snapshot file and produces a single snapshot file. Its purpose is to convert SDDS snapshot files to non-SDDS snapshot files and vice versa.

Converting snapshot files in this way can alter the informational contents (not just the syntax) of the files. Recall that SDDS snapshot files may have devices in them while non-SDDS snapshot files cannot. This poses a problem for burtconvertsnap when it is asked to convert an SDDS snapshot file containing devices to a non-SDDS snapshot file. Burtconvertsnap solves this problem by translating all the devices in the SDDS snapshot file into their process variable constituents. It then places the process variable name along with its associated value, as opposed to the device name and its value, into the output non-SDDS snapshot file. Additionally, the lineage of those devices found in the SDDS snapshot file is lost as well.

The informational difference between input and output snapshot files only occurs when converting SDDS snapshot files containing devices to non-SDDS snapshot files. Converting non-SDDS snapshot files or SDDS snapshot files without devices always produces informationally equivalent files.

The user must always specify exactly one snapshot file as input. To specify the snapshot file snap.source the user would enter the following command:

>  burtconvertsnap snap.source
By default, burtconvertsnap will produce a snapshot file with a different format than the input file. The user has the option of explicitly specifying the type of snapshot file should be produced by using either the -sdds or -nosdds option. Extending the example above to instruct burtconvertsnap to produce an SDDS snapshot file, the user would enter the command:

>  burtconvertsnap snap.source -sdds
The converted snapshot file is written to the UNIX file stdout. In most cases this means that the snapshot file is written to the screen. The user can instruct BURT to write the snapshot file to a file, rather than the screen, by using the -o (for output) option. Extending the example above, writing the snapshot to a file called snap.converted the user would enter the command:

>  burtconvertsnap snap.source -sdds -o snap.converted
Options can appear in any order. In other words, the above command is equivalent to the following command:

>  burtconvertsnap snap.source -o snap.converted -sdds
Note that the specification of the input snapshot file is not an option. Only those command line arguments that begin with ``-'' are considered options. For that reason, the name of the input snapshot file must always appear immediately after the command burtconvertsnap.

By default, burtconvertsnap writes the terse version of the log file to UNIX's stderr, which is typically the screen. The user can instruct burtconvertsnap to increase the information in the log file by reporting everything it is doing by specifying the -v (for verbose) option. Additionally, the user can also instruct burtconvertsnap to place the log file into a file rather than the screen with the -l (for log file) option. Here is an example requesting a verbose log file sent to the file log.

>  burtconvertsnap snap.source -o snap.converted -sdds -v -l log
As with all of BURT's programs, simply typing in the name of the program without any arguments places a quick reference usage message onto the screen.

>  burtconvertsnap
usage: burtconvertsnap snap {-l logfile} {-o outfile} {-v} {-sdds or -nosdds}

where

snap - Snapshot filename. This is the only switch that is not optional. You must specify exactly one snapshot file. This is the snapshot file that will be converted.

-l logfile - Log filename. The name of the file where all logging messages (e.g. error messages) go. The default is stderr.

-o outfile - Output snapshot filename. This is where the newly generated converted snapshot file will be placed. The default is stdout.

-v - Verbose. This increases the amount of information displayed in the logfile.

-sdds or -nosdds - SDDS/non-SDDS snapshot file. Explicitly specifying that the generated snapshot file will be SDDS/non-SDDS compliant. The default is to produce whatever the input snapshot file is not.
Table of Contents Next Chapter