EPICS
caSaveRestore Users Guide

John Winans
Mar 25 1996

ASCII File Format

The supported ASCII file format has been designed to account for future feature enhancements. In its purest form, the ASCII file format used by caSave and caRestore is made up of widgets that may contain attributes that may contain attributes that may conatin... The idea is that there is little that can not be stored in an arbitrairly deep heirarchy --> especially if it comes from EPICS databases.

File format overview

The birdseye view of the ASCII format is quite simple. It is made of an enviroment section that contains things like who made the file and when they made it, a macro sections that define macros that can appear in the names of the process variables, and a data section that contains a list of process variables along with information that specifies options that are employed by the caSave and caRestore commands.

An example of a minimal request file is shown below. It includes nothing but the list of process variables that are to be saved by a caSave command. 

data{
  SYS:variable1.VAL
  SYS:variable1.HOPR
  SYS:variable1.LOPR
  SYS:waveform.VAL
  SYS:waveform.EGU
  SYS:variable6
}
An example of a snapshot file that might be generated by a caSave that runs on the above file is: 
env{
  Logonid{"winans (John R. Winans)"}
  SnapType{Absolute}
  LocalTime{"Tue Mar  5 13:47:01 CST 1996"}
  LocalDTime{134701}
  LocalJDate{96065}
  GmtDTime{194701}
  GmtJDate{96065}
}
data{
  SYS:variable1.VAL{value{data{357}} sevr{NO_ALARM}}
  SYS:variable1.HOPR{value{data{500}} sevr{NO_ALARM}}
  SYS:variable1.LOPR{value{data{10}} sevr{NO_ALARM}}
  SYS:waveform.VAL{value{dim{16} data{1.825e+01 1.825e+01
     1.825e+01 1.825e+01 1.825e+01 1.825e+01 1.825e+01 1.825e+01 1.825e+01
     1.825e+01 1.825e+01 1.825e+01 1.825e+01 1.825e+01 1.825e+01 1.825e+01}}
     sevr{NO_ALARM}}
  SYS:waveform.EGU{value{data{Volts}} sevr{NO_ALARM}}
  SYS:variable6{value{data{1234}} sevr{NO_ALARM}}
}

Note that the physical arrangement of the information in the file is not too important. Most of the while space is ignored. So you could (if you really wanted to) make a request or snapshot file that looks like this: 

data { SYS:variable1.VAL SYS:variable1.HOPR SYS:variable1.LOPR 
SYS:variable4.VAL SYS:variable5.VAL SYS:variable6 }
An important rule is that if any one widget contains something other than a string of letters, numbers, or the '.' or a ':', then it must be expressed with quotes around it. For example, the environment's Logonid or LocalTime field normally include blank characters in them... thus they are expressed as quoted strings. Quoted strings MUST be expressed on a single line.

Specifics on the above format and how to use macros are given in the following sections.

Environment Section

The enviroment section is labeled with the name env. It is written into snapshot files by caSave. It is not required to be present in request files. Its specific format is: 
env                                         <-- marks the environment section
{                                           <-- start of attribute section
  Logonid{"winans (John R. Winans)"}        <-- who created this file
  SnapType{Absolute}                        <-- type of file (Absolute, Relative, or Nowrite)
  LocalTime{"Tue Mar  5 13:47:01 CST 1996"} <-- time this file was created
  LocalDTime{134701}                        <-- local time of day HHMMSS
  LocalJDate{96065}                         <-- local julian date
  GmtDTime{194701}                          <-- GMT time of day HHMMSS
  GmtJDate{96065}                           <-- GMT julian date
}                                           <-- end of attribute section
The environment is completely ignored by caSave. The SnapType attribute, however, is checked by caRestore and is used to indicate the default action of the restore operation for this snapshot file. It can either write the absolute values of the listed process variables to the database(s), it can add the values of the listed process values to the database(s), or it can simply be told not to write the given values to any database(s).

Data Section

The data section contains the process variable names and any attributes that they have. The attributes of a process variable are all optional and are described below. 
writeonly                            <-- don't let caSave read or change the specified value data
readonly                             <-- don't let caRestore write to this variable
{                                    <-- start of additional information
  notify                             <-- tell caSave to warn that this variable has been ignored
}                                    <-- end of additional information
value                                <-- value information is included
{                                    <-- start of value information
  dim                                <-- value data is a vector
  {                                  <-- start of value data vector info
    integer number                   <-- number of elements in the value data
  }                                  <-- end of of value data vector info
  data                               <-- value data
  {                                  <-- start of value data information
    value of process variable        <-- actual value data
  }                                  <-- end of the value data
  sevr                               <-- alarm severity
  {                                  <-- start of alarm severity information
    an alarm severity                <-- enumeration of alarm severity
  }                                  <-- end of alarm severity info
  stat                               <-- alarm status information
  {                                  <-- start of alarm status information
    an alarm status                  <-- enumeration of alarm status
  }                                  <-- end of alarm status info
}                                    <-- end of value information
An (silly) example of a data section that contains a single process variable with all of the above optional attributes is: 
data{
  SomePvName.VAL{writeonly readonly{notify} value{dim{4} data{1 2 3 4}} sevr{INVALID} stat{UDF}}
}
A detailed discussion of each of the attributes of a process variable is included below.
writeonly
This attribute is intended to be used if you have included value information for this process variable and you do not want it to be replaced if this file is used as a request file to caSave. For example you might use this on some type of trigger that you want fired off when ever someone restores a backup that was made with this file.

readonly
This attribute is intended to be used if you want to manually restore a process variables value instead of having caRestore do it. This attribute instructs caSave to go ahead and perform the save operation, but for caRestore to ignore this specific process variable. The idea being that you might wish to keep record of what the variable's value would have been restored to.

notify
This attribuite is intended to instruct caRestore to issue a notification message to the user that a readonly variable has been encountered and ignored.

value

dim

data

sevr

stat

Macros

There are three types of macro sections supported in request and snapshot files as well as a macro specification that can be used on the command line of both caSave and caRestore. Macros may only be used in the process variable name fields of the data section.

Macros that are specified on the command line take precidence over any macros with the same name that may be specified in the request and snapshot files. Macros that are not overridden on the command line may be redefined in the snapshot and request files by defining another macro with the same name in another macro section.

Comments

Comments can start anywhere and continue to the end of the line. A comment starts with either a pound sign '#' or a double slash '//'.

Complaints??

You don't like it? Add your own! Have a gander at the source file common.c and look at the whopping 3 interface functions that are used to read/write the data of the internal format and go for it! If you decide to do so, let me know so that I can incorporate your changes for others to use, doc it, etc... The best way to learn how to get data into the internal format is to observe the ascii format support code the interesting part is in the yacc file.