Table of ContentsTable of Contents 
Previous Chapter
It is not possible to distinguish between atomic and composite devices in request files. However, it is important to know that RO and RON tags as well as BackupMsg and RestoreMsg messages are inherited by all the elements in a composite device.
When the restore program burtwb is supplied that snapshot file as input, those items that were tagged RO or RON do not have their values written back to the IOCs. Further, if there are any RON tags in the snapshot file, burtwb creates a Nowrite snapshot file (snapshot files and their types are described in Section 2) and places all the RON values into that file. The values of those items that were not tagged are restored to the IOCs.
BURT ignores blank lines and lines that begin with % in non-SDDS files. This allows the user to augment non-SDDS files with comment lines that begin with %.
Additionally, BURT processes these files with the C preprocessor. This allows the user to take advantage of the #define and #include directives provided by the C programming language. This is illustrated in the example at the end of this section.
The rest of the file are lines that have the following format:
{RO or RON} pvarname {nelements}
where
RO or RON - Optional. Read Only or Read Only Notify. This tags the process variable as either Read Only or Read Only Notify. It instructs burtrb to backup the process variable and place its value into the snapshot file. However, when the snapshot file is used as input to BURT's restore program burtwb, this value is not restored to the IOC.
pvarname - The record name and field name of the process variable to read. The default field name is VAL.
nelements - Optional. Number of elements. For those process variables that contain more that one data value, e.g., vectors, nelements can be used to backup the first n elements. The default is to backup the all the data values of the process variable.
% % Example request file: req1 % #define PREFIX LINAC #include "req2" PREFIX:rec1
% % Example request file: req2 % RO PREFIX:rec2
% % Example request file: req3 % PREFIX:rec3 LINAC:rec4 5 RON LINAC:rec5Here we examine how burtrb and burtset would process these files to construct a single list of process variables if they were only explicitly given req1 and req3 as input.
The request files are processed in the order in which they are specified. Assume that req1 was specified first (the syntax for BURT commands is in Chapter 4). It is processed by the C preprocessor which notes the #define for PREFIX and then includes the second request file req2. That request file is also processed through the C preprocessor, but does not find any #define or #include directives. Processing continues and the first process variable request is encountered, RO PREFIX:rec2 (from req2). The #define from req1 is used and the request is changed to RO LINAC:rec2. This completes the processing of req2 and the processing of req1 continues. The next request is translated and becomes LINAC:rec1. Note that the #define found in request file req1 was applied to the request file req2 because it appeared before the #include that brought req2 int o req1. This concludes the processing of req1.
Now the second request file, req3 is processed. It is also processed by the C preprocessor without any effect. Note the #define for PREFIX worked in req1 and req2, but not req3. The final list after processing the req1 and req3 is:
RO LINAC:rec2 LINAC:rec1 PREFIX:rec3 LINAC:rec4 5 RON LINAC:rec5This is the list of process variables that burtrb will attempt to backup.
BURT requires two columns in SDDS request files (ControlName and ControlType) and looks for four other optional columns. BURT ignores all other information (columns and parameters) in the SDDS file. In short, what makes an SDDS file a valid request file is the presence of the two required SDDS_STRING columns, ControlName and ControlType. This point is illustrated further in Section 2.3 where we discuss SDDS Snapshot Files. The table below describes the information BURT is interested in when processing SDDS request files.
---------------------------------------------------------------------------------------
Column name SDDS Type Required/ Contents Default Default
Optional Value Meaning
---------------------------------------------------------------------------------------
ControlName SDDS_STRING required PV or Device Name
ControlType SDDS_STRING required ``pv'' or ``dev''
BackupMsg SDDS_STRING optional Dev read msg. ``-'' ``read''
must be ``-'' for pv
RestoreMsg SDDS_STRING optional Dev write msg. ``-'' ``set''
must be ``-'' for pv
Count SDDS_LONG optional number of ele 0 native count
ments. must be 0 for
devices
ControlMode SDDS_STRING optional ``-'', ``RO'', or ``-'' Restore value to
``RON'' IOC
---------------------------------------------------------------------------------------
The columns BackupMsg and RestoreMsg are used for devices only while the column Count is used for process variables only.If an optional column is missing, the default value is used and is interpreted according to the default meaning. If an optional column is supplied, the user may supply the default value. For example, the user is required to supply the default value "-" when supplying the BackupMsg column for a row specifying a process variable (ControlType = "pv"). In either case, whether the default value is implied by the omission of an optional column or it is explicitly provided, BURT interprets each default value accordingly. For example, the default value for the column BackupMsg is "-". That value is interpreted by BURT to mean the message "read".
SDDS1 &column name="ControlName", type=string &end &column name="ControlType", type=string &end &data mode=ascii, no_row_counts=1 &end LINAC:dev1 dev LINAC:rec1 pvReq4 is an SDDS request file with only the required columns. It specifies one process variable and one device. Neither are tagged RO or RON, and in both cases the native count will be backed up. Consider req5, a more robust request file.
SDDS1 &column name="ControlName", type=string &end &column name="ControlType", type=string &end &column name="Count", type=long &end &column name="ControlMode", type=string &end &column name="BackupMsg", type=string &end &column name="RestoreMsg", type=string &end &data mode=ascii, no_row_counts=1 &end LINAC:rec1 pv 0 RO - - SR:dev1 dev 0 - - - LINAC:rec2 pv 5 - - - SR:dev2 dev 0 RO read set SR:dev3 dev 0 RON get putHere we have two process variables and three devices. The first process variable, LINAC:rec1, is tagged RO and requests the native count. The second process variable, LINAC:rec2, is not tagged and requests the first five elements of its value, presumably a vector. Note that both of the process variables specify ``-'' as their BackupMsg and RestoreMsg. In SDDS request files that have these columns, all process variables must specify ``-'' in those columns.
Following the process variables are devices. Note that the three devices all have a Count of 0. Like BackupMsg and RestoreMsg for process variables, all devices must specify a Count of 0. The first device, SR:dev1, is not tagged and implicitly specifies the default BackupMsg ``read'' and RestoreMsg ``write''. The second device, SR:dev2, is tagged RO and explicitly specifies the default BackupMsg ``read'' and RestoreMsg ``set''. The third device, SR:dev3, is tagged RON and specifies its own BackupMsg and RestoreMsg, ``get'' and ``put'', respectively.
Typically, snapshot files are generated as output of BURT programs, e.g., burtrb, burtwb, and burtmath. As such, those BURT programs that accept them as input (burtwb, burtmath, and burtconvertsnap) expect and insist that they conform to a very rigid format. For this reason, users should never edit snapshot files. Those who do, do so at their own risk. In Chapter 6 we describe the advanced features of BURT. There we describe that rigid format so that users can create their own snapshot files from their own programs.
BURT recognizes snapshot files in two formats, non-SDDS and SDDS. All of the BURT programs that accept snapshot files as input allow the user to intermix the formats freely in any single execution. Like non-SDDS and SDDS request files, the two formats of the snapshot files are not equivalent. Aside from their syntactic differences, SDDS snapshot files may contain devices as well as process variables while non-SDDS snapshot files may only contain process variables. This is not to say that if a request file has devices it cannot produce a non-SDDS snapshot file. If the user requests that a non-SDDS snapshot be produced, BURT resolves all device names to their process variable constituent(s) and places the process variable names into the non-SDDS snapshot file. For SDDS snapshot files composite devices are reduced to their atomic device constituents and they are placed into the snapshot file.
Snapshot files are ASCII files that start with a header section and conclude with the snapshot data. The contents found in the header section of both non-SDDS and SDDS snapshot files are identical. They only differ syntactically. The header identifies who generated the snapshot and when. It also contains any keywords and/or comments the user saw fit to add at the time the snapshot was generated. Finally the header identifies what type of snapshot file it is; Absolute, Relative, or Nowrite.
When the values in an Absolute snapshot file are applied to the IOCs, they replace the values that exist on the IOCs by default. When the values of a Relative snapshot file are restored, they are added to the values on the IOCs by default. Burtwb's treatment of each of these types of files can be changed at the user's discretion, i.e., Absolute written as Relative and vice versa.
The third type of snapshot file is Nowrite. It is a special type of snapshot file typically generated as output from burtwb. When the values of a Nowrite snapshot file are applied to the IOCs, it has no effect on them.
------------------------------------------------------------------ Parameter Name SDDS Type Value ------------------------------------------------------------------ TimeStamp string when snapshot was taken LoginId string loginid of user who took snapshot EffectiveUID string effective UID of user who took snapshot GroupID string group ID of user who took snapshot BurtKeywords string user supplied keywords BurtComments string user supplied comments SnapType string type of snapshot ------------------------------------------------------------------Following the header information is the data. The data appears in columns. The following table describes the columns of the data portion.
----------------------------------------------------------------------------------------- Column Name SDDS Type Contents ----------------------------------------------------------------------------------------- ControlName SDDS_STRING PV or Device name ControlType SDDS_STRING type of entity, ``pv'' or ``dev'' Lineage SDDS_STRING lineage of composite devices, for devices only, ``-'' for pvars BackupMsg SDDS_STRING device read message, for devices only, ``-'' for pvars RestoreMsg SDDS_STRING device write message, for devices only, ``-'' for pvars ControlMode SDDS_STRING read only tag, ``-'', ``RO'', or ``RON'' Count SDDS_LONG number of elements, 0 for devices ValueString SDDS_STRING value -----------------------------------------------------------------------------------------There are two things of interest to note about the data columns. The first is that all snapshot files have the two columns required by request files: ControlName and ControlType. This means that snapshot files are valid request files, i.e., snapshot files can be used as request files. In doing so, BURT uses the columns ControlName and ControlType, the columns required in all request files, as well as the columns BackupMsg, RestoreMsg, ControlMode, and Count. BURT ignores the columns Lineage and ValueString as well as all the parameters found in the header.
The second thing to note about the data columns is that the column ValueString is a character string. This is an explicit example of something that is true throughout all of BURT, for the purposes of back up and restore, BURT views all data values as character strings. Only in BURT's arithmetic operation program, burtmath, does it ever consider values as numeric. This will typically not cause any trouble to the user who simply backs up and restores values, but is something that users should be made aware of if they are going to use snapshot files with tools other than BURT, e.g., Mathematica, PV Wave, or applications they have written themselves.
Currently, conditional restoration is only available with the command line version of BURT and not available through its Graphic User Interface. All non-blank and non-comment lines in a dependency file have the following format:
{HALT or CONT} condition
where
HALT or CONT - Optional. Failure directive. This directs burtwb in the event that this condition is false or cannot be evaluated (see ca_get() and ss_get() below). HALT notifies the user that the condition failed and stops processing all together. This means that no more conditions are evaluated and none of the snapshots are restored to the IOCs. CONT also notifies the user that the condition failed, but continues processing. If HALT or CONT are omitted, burtwb notifies the user that the condition has failed and prompts the user whether or not to continue.
condition - Condition. The condition to be evaluated. BURT conditions follow the same syntax as Boolean expressions (expressions that are either true or false, like in an if statement) in the C language. Some of the relational operators are == (equal), != (not equal), <, <=, >, >=. etc. Some of the Boolean operators and connectors are ! for ``not'' (negation), && for ``and'' (conjunction), and || for ``or'' (disjunction). When comparing character strings the function strcmp() should be used.
Note, dependency files may only refer to process variables, not devices.The conditions in the dependency files can refer to the values of process variables on the IOCs as well as values in snapshot files. They do this by making calls to the ca_get() and ss_get() families of functions, respectively.
ca_get(pvarname)
On the other hand, the user may wish to retrieve the data as a type other than the value's native type. If so, the user may make any of the following calls:
ca_get_string(pvarname)
ca_get_int(pvarname)
ca_get_short(pvarname)
ca_get_float(pvarname)
ca_get_enum(pvarname)
ca_get_char(pvarname)
ca_get_long(pvarname)
ca_get_double(pvarname)
However, in using any of the calls in the ca_get() family, the user is restricted in that these function calls return only the first data element of the named process variable. In other words, it works fine for all scalar values but will only retrieve the first value in any vector.
If the process variable cannot be found, the entire condition in which the ca_get() call was made is not evaluated. In that case, burtwb treats the entire condition as being false and follows the failure directive of the condition as described above.
ss_get(pvarname)
ss_get_string(pvarname)
ss_get() retrieves the value as it appears in the snapshot file. ss_get_string() also retrieves the value as it appears in the snapshot file, and surrounds it with double quotation marks thus turning it into a character string constant with respect to the C language.
These calls will only work on those snapshot values that represent a single data element. If the process variable name is not found in the snapshot files, the entire condition in which the ss_get() call was made is not evaluated. In that case, burtwb treats the entire condition as being false and follows the failure directive of the condition as described above.
Consider the following example. Recall the request files req1-req3 from Section 1.3 above. They were used to generate the following list of process variables.
RO LINAC:rec2 LINAC:rec1 PREFIX:rec3 LINAC:rec4 5 RON LINAC:rec5Recall that the third process variable, PREFIX:rec3, found in req3 did not get the benefit of the #define found in req1 and therefore was not transformed into a process variable name found on the IOCs. Assume that these request files were processed by burtrb and the generated non-SDDS snapshot file (omitting the header) looks as follows.
RO LINAC:rec2 1 222 LINAC:rec1 1 111 LINAC:rec4 5 3 444 555 666 RON LINAC:rec5 1 555Note that PREFIX:rec3 from req3 does not appear in the snapshot file. It was not found on the IOCs and was reported as such in the log file (log files explained in section 4). Note also that, although five values were requested for LINAC:rec4 in req3, only three were read.
Consider the following dependency file, dep.
% contradiction CONT 1 == 2 % both should fail because not_there % is not in the database nor is it in the snapshot CONT ca_get(not_there) < 5 CONT ss_get(not_there) < 5 % should fail because asking for a snapshot % of a process variable that is NOT a single value CONT ss_get(LINAC:rec4) != 6 (ss_get(LINAC:rec1)-ca_get(LINAC:rec1)) < 1000We will assume that over time, all the values of all our process variables have changed to 0 on the IOCs. An execution of burtwb with the snapshot file and dependency file above, in conjunction with the values on the IOCs as described, would proceed as follows.
The first thing burtwb does is read in all the snapshot files. In this case there is only one. The dependency file is then processed by the C preprocessor. Because dep does not have #define or #include directives, this will have no effect. Burtwb processes the conditions by automatically writing and compiling a C program based on the conditions and the failure directives. Burtwb then executes that program.
In our example, the first condition fails because it is a contradiction. The user is notified that the condition failed in the log file and processing continues as a result of the failure directive CONT. If HALT had been specified instead, the user would have been notified that the condition failed, processing would have terminated here, no other conditions would have been evaluated and nothing would have been written to the IOCs. If no failure directive had been specified, the user would have been notified that the condition failed and prompted whether or not to continue.
The second condition is not even evaluated because the process variable not_there is not on any of the IOCs. The user is notified of this in the log file and, again, because the failure directive is CONT, processing continues.
The third condition is also not evaluated because the process variable not_there is not in the snapshot file. Again, the user is notified and processing continues.
The fourth condition is not evaluated because, although the process variable LINAC:rec4 is in the snapshot file, it does not represent a single atomic value. As we mentioned earlier, ss_get() only works when the value in the snapshot file is a single atomic value. The user is notified and processing continues.
The last condition is the only one that is evaluated, because all the values can be obtained. The condition (111-0)<1000 is true, so processing simply continues.
The dependency file has been successfully processed, meaning no condition stopped execution. burtwb continues by restoring the values in the snapshot file.
The user can control where BURT puts the log file and how much information BURT places into the log file. All of the programs allow users to instruct BURT to place the log file information into a file rather than onto the screen. They also allow the user to increase the amount of information so that BURT tells the everything it is doing. By default, BURT gives a general overview about the execution of the program and it prints it on the screen. A full description of how to specify where and how much information appears in the log file is in Chapter 4.
Next Chapter