From cf209e1411763cd6172595ae5fc172fa51f94002 Mon Sep 17 00:00:00 2001 From: "Janet B. Anderson" Date: Thu, 7 Dec 1995 20:53:06 +0000 Subject: [PATCH] Moved from base/man. base/man is now a created directory. --- src/dbtools/dbLoadRecords.3 | 116 +++++++++++++++++++++++++++++++++++ src/dbtools/dbLoadTemplate.1 | 56 +++++++++++++++++ src/dbtools/dbLoadTemplate.3 | 2 + src/dbtools/dbfile.5 | 69 +++++++++++++++++++++ src/dbtools/subtool.1 | 51 +++++++++++++++ src/dbtools/templatefile.5 | 116 +++++++++++++++++++++++++++++++++++ 6 files changed, 410 insertions(+) create mode 100644 src/dbtools/dbLoadRecords.3 create mode 100644 src/dbtools/dbLoadTemplate.1 create mode 100644 src/dbtools/dbLoadTemplate.3 create mode 100644 src/dbtools/dbfile.5 create mode 100644 src/dbtools/subtool.1 create mode 100644 src/dbtools/templatefile.5 diff --git a/src/dbtools/dbLoadRecords.3 b/src/dbtools/dbLoadRecords.3 new file mode 100644 index 000000000..1d2fc8e3a --- /dev/null +++ b/src/dbtools/dbLoadRecords.3 @@ -0,0 +1,116 @@ +.\" @(#)dbLoadRecords.3 1 93/11/04 SMI; +.TH DBLOADRECORDS 3 "11 Nov 1993" +.SH NAME +dbLoadRecords, dbLoadTemplate \- load ascii database records into an IOC +.SH SYNOPSIS +.LP +dbLoadRecords(char* db_file, char* substitutions) +.LP +dbLoadTemplate(char* template_file) +.SH DESCRIPTION +.LP +These routines are available from IOC core on the vxWorks command line. +Both provide a way to load ascii ".db" files (usually created by +.B gdct(1) +) into the IOC. The ".db" files contain ascii versions of record instances +and are described in more detail in dbfile(5). In addition to +loading the ".db" ascii files into the IOC, both routines provide a method +of performing variable substitution on record names and field values. +.sp +.B dbLoadRecords() +reads the ".db" file +.I db_file +performing substitutions specified in string +.I substitutions. +The substitution must be a string specified as follows: +.sp +.nf +"var1=sub1,var2=sub3,..." +.fi +.sp +Variables are specified in the ".db" file as $(variable_name). If the +substitution string "a=1,b=2,c=\\"this is a test\\"" were used, any +variables $(a), $(b), or $(c) would be substituted with the appropriate data. +See the +.B EXAMPLES +section for more details. +.sp +.B dbLoadTemplate() +will read a +.I template_file. +The +.I template_file +resides in the your IOC boot directory and +contains rules about loading ".db" files and performing substitutions. +The template_file must be in the form used by an IOC and is described in +templatefile(5). The +.B EXAMPLES +section descibes how it can be used. +.SH EXAMPLES +The next two examples of dbLoadRecords() and dbLoadTemplate() will +use the following ".db" file named +.I test.db +: +.sp +.nf +database(test) +{ + record(ai,"$(pre)testrec1") + record(ai,"$(pre)testrec2") + record(stringout,"$(pre)testrec3") + { + field(VAL,"$(STRING)") + field(SCAN,"$(SCAN)") + } +} +.fi +.sp +Running +.B dbLoadRecords +("test.db","pre=TEST,STRING=\\"this is a test\\",SCAN=Passive") +will produce the following records in the IOC's database: +.sp +.nf + TESTtestrec1 + TESTtestrec2 + TESTtestrec3 +.fi +.sp +The third record will have VAL set to "this is a test" and SCAN set to +"Passive". +.sp +Running +.B dbLoadTemplate +("test.template") with test.template containing: +.nf +file test.db +{ + {pre=TEST1, STRING = "this is a test two", SCAN="1 Second" } + {pre=TEST2, STRING = "this is a test one", SCAN=Passive } + {pre=TEST3, STRING = "this is a test three", SCAN=Passive } +} +.fi +will produce a total of nine records in the IOC's database: +.nf + TEST1testrec1 + TEST1testrec2 + TEST1testrec3 - (VAL="this is a test two", SCAN="1 Second") + TEST2testrec1 + TEST2testrec2 + TEST2testrec3 - (VAL="this is a test one", SCAN="Passive") + TEST3testrec1 + TEST3testrec2 + TEST3testrec3 - (VAL="this is a test three", SCAN="Passive") +.fi +.SH NOTES +The binary file +.IR "default.dctsdr" +must be loaded prior to running either of these routines. This file +contains the rules on how to construct records and change field values. +.sp +After the default.dctsdr file is loaded, these routines can be run as +many times as desired until iocInit is run. +.SH "SEE ALSO" +.BR gdct(1), +.BR templatefile(5), +.BR dbfile(5) diff --git a/src/dbtools/dbLoadTemplate.1 b/src/dbtools/dbLoadTemplate.1 new file mode 100644 index 000000000..344aee852 --- /dev/null +++ b/src/dbtools/dbLoadTemplate.1 @@ -0,0 +1,56 @@ +.\" @(#) +.TH DBLOADTEMPLATE 1 "04 Nov 1993" +.SH NAME +dbLoadTemplate \- Perform substitutions on variables in an ".db" file. +.SH SYNOPSIS +.B dbLoadTemplate +.IR substitution_file +.SH AVAILABILITY +The tool in available under Unix from the EPICS application directory +provided by getrel in release 3.11 or greater. +.SH DESCRIPTION +.LP +This tool applies variable substitutions specified in the +.B substitution_file. +It is specifically meant to operate on ".db" files. The template file +must be in the form used by an IOC to load database records using +dbLoadTemplate(3) on the IOC. A ".db" file with all the rules in the +.B substitution_file +applied will be printed to standard out. +See templatefile(5) for a full description of the template file. +.sp +.SH EXAMPLE +Running the command "dbLoadTemplate sub_file" with sub_file contents of +.sp +.nf +file a.db +{ + { a=test1,b=one } + { a=test2,b=two } +} +.fi +.sp +and a.db contents of +.sp +.nf +database(tester) +{ + record(ai,"$(a)rec1$(b)") + record(ai,"$(a)rec2$(b)") +} +.fi +.sp +writes to standard out the following: +.sp +.nf +database(tester) +{ + record(ai,"test1rec1one") + record(ai,"test1rec2one") + record(ai,"test2rec1two") + record(ai,"test2rec2two") +} +.fi +.sp +.SH "SEE ALSO" +.BR templatefile(5) diff --git a/src/dbtools/dbLoadTemplate.3 b/src/dbtools/dbLoadTemplate.3 new file mode 100644 index 000000000..fe11249f7 --- /dev/null +++ b/src/dbtools/dbLoadTemplate.3 @@ -0,0 +1,2 @@ +.so man3/dbLoadRecords.3 +.\" @(#)dbLoadTemplate.3 1 93/11/04 SMI; diff --git a/src/dbtools/dbfile.5 b/src/dbtools/dbfile.5 new file mode 100644 index 000000000..5c0f779c9 --- /dev/null +++ b/src/dbtools/dbfile.5 @@ -0,0 +1,69 @@ +.\" @(#)dbfile.5 1 93/11/04 SMI; +.TH DBFILE 5 "04 Nov 1993" +.SH NAME +".db" \- File containing textual EPICS database records and field values +.SH SYNOPSIS +.B file_name.db +.SH DESCRIPTION +.LP +This is a file which holds EPICS database record instances in a human +readable format. It is a replacement for the old dct short form report. +The general format is as follows: +.sp +.nf +database(database_name,"epics_release") +{ + record( rec_type, "record_name-1" ) + { + field( field_name-1, "field_value-1" ) + field( field_name-2, "field_value-2" ) + field( field_name-3, "field_value-3" ) + . + . + . + } + record( rec_type, "record_name-2" ) + { + field( field_name-1, "field_value-1" ) + field( field_name-2, "field_value-2" ) + field( field_name-3, "field_value-3" ) + . + . + . + } + . + . + . +} +.fi +.sp +The database_name is a name used to generate a binary ".database" file +with (do not use the extension ".database"). +The epics_release will probably be the 3.11 or greater. The rec_type +is any valid record type defined in a default.dctsdr file. The record_name +can be any string up to 29 characters in length. The field_name is any +valid field name for the record type, always four or less alphanumeric +characters. The field_value is any string that is valid +input for the field_name. +.SH EXAMPLES +The following is an example of a database with three records. The first +two records use all default values, the third replaces the SCAN field and +VAL field. +.sp +.nf +database(test) +{ + record(ai,"ai_record") + record(bo,"bo_record") + record(stringout,"sout_record") + { + field(SCAN,"1 second") + field(VAL,"This is a string") + } +} +.fi +.SH "SEE ALSO" +.BR gdct(1), +.BR db2database(1), +.BR dbLoadRecords(3), +.BR sf2db(1) diff --git a/src/dbtools/subtool.1 b/src/dbtools/subtool.1 new file mode 100644 index 000000000..bae57dbca --- /dev/null +++ b/src/dbtools/subtool.1 @@ -0,0 +1,51 @@ +.\" @(#) +.TH SUBTOOL 1 "04 Nov 1993" +.SH NAME +subtool \- Perform substitutions on variables in an ascii text file. +.SH SYNOPSIS +.B subtool +.IR file_name +.IR substitution_file +.SH AVAILABILITY +The tool in available under Unix from the EPICS application directory +provided by getrel in release 3.11 or greater. +.SH DESCRIPTION +.LP +This tool applies variable substitutions to +.B file_name +according to rules in the +.B substitution_file +to produce a file at standard out. See templatefile(5) for a full +description of the substitution file. +.SH EXAMPLE +Running the command "subtool file_name sub_file" with sub_file contents of +.sp +.nf +{ a=test1,b=one } +{ a=test2,b=two } +.fi +.sp +and file_name contents of +.sp +.nf +This is var a: $(a), this is var b: $(b) +This is another var a: $(a), this is another var b: $(b) +.fi +.sp +writes to standard out the following: +.sp +.nf +This is var a: test1, this is var b: one +This is another var a: test1, this is another var b: one +This is var a: test2, this is var b: two +This is another var a: test2, this is another var b: two +.fi +.sp +.SH NOTES +This tool will use all type of templatefile(5) definitions. If an +IOC type is used by the tool, the dbfile(5) information will be ignored +and the +.I file_name +will be used. +.SH "SEE ALSO" +.BR templatefile(5) diff --git a/src/dbtools/templatefile.5 b/src/dbtools/templatefile.5 new file mode 100644 index 000000000..06baa20c3 --- /dev/null +++ b/src/dbtools/templatefile.5 @@ -0,0 +1,116 @@ +.\" @(#)templatefile.5 1 93/11/04 SMI; +.TH TEMPLATEFILE 5 "04 Nov 1993" +.SH NAME +templatefile \- The file containing rules for substitutions. +.SH DESCRIPTION +.LP +This file contains the rules for performing substitutions on ascii text +file or ".db" files. Two formats can exist: one specifically for +an ascii ".db" file (usually produced by GDCT) and one for a plain ascii +text file. Most tools will except either format; the different +formats exist for convenience. +.sp +The purpose of this file is to specify a set of substitutions to be +performed on a file. Substitutions can be defined in one of two ways. +The general format for substitution +sets is defined as follows: +.nf +.sp +.B *Version-1* +{ set1var1=sub1, set1var2=sub2,...... } +{ set2var1=sub1, set2var2=sub2,...... } +{ set3var1=sub1, set3var2=sub2,...... } +\. +\. +\. + +- or - + +.B *Version-2* +pattern{ var1,var2,var3,....... } +{ sub1_for_set1, sub2_for_set1, sub3_for_set1, ... } +{ sub1_for_set2, sub2_for_set2, sub3_for_set2, ... } +{ sub1_for_set3, sub2_for_set3, sub3_for_set3, ... } +\. +\. +\. +.fi +.sp +Each braced line represents an entire variable substitution for the input +file. The input file will have each set applied to it to produce +one composite file with all the completed substitutions in it. +Interpreting version 1 should be obvious, for version 2, the variables +are listed in the "pattern{}" line, which must precede the braced +substitution lines. The braced substitution lines contains set which +match up with the pattern{} line. An example will be given later. +.sp +For some tools such as +.B subtool(1), +putting substitution rules into a file (only one version type +allowed per file) as +above is enough for the tool to operate. For other tools, such as +.B dbLoadTemplate(3) +which is capable of loading records onto an IOC, more information +must be given. +.sp +.nf +file name.db +{ + *put version 1 or 2 of substitutions here* +} +.fi +.sp +The keyword file identifies a +.B dbfile(5) +to perform the substitutions on, in this case "name.db". +.sp +To summarize, substitutions can be specified using version 1 or 2. The +files can be written in two different flavors: one way for an IOC dbfile(5), +and one way for a plain ascii text file. +.SH EXAMPLES +Four simple template file examples are listed here, the first two are +IOC db specific, the last two are general ones. All the examples +specify the same substitutions to perform: this=sub1 and that=sub2 for a +first set, and this=sub3 and that=sub4 for a second set. +.nf + +1) file test.db { { this=sub1,that=sub2 } { this=sub3,that=sub4 } } +2) file test.db { pattern{this,that} {sub1,sub2} {sub3,sub4 } } +3) { this=sub1, that=sub2 } { this=sub3, that=sub4 } +4) pattern{this,that} {sub1,sub2} {sub3,sub4 } + +input file for 1 and 2 (see dbfile(5) for examplanation of file): + +database(test) +{ + record(ai,"$(this)record") { field(DESC,"this = $(this)") } + record(ai,"$(that)record") { field(DESC,"this = $(that)") } +} + +input file for 3 and 4: + +The first variable "this" equals $(this), the +second variable "that" is equal to $(that). + +.fi +When 1 and 2 are applied to their corresponding file, two sets of the +record() lines will be produced: (sub1record,sub2record) and (sub3record, +sub4record), see dbLoadTemplate(1) for a more thorough explanation. +.sp +When 3 and 4 are applied to their corresponding file, the following is +produced. +.nf + +The first variable "this" equals sub1, the +second variable "that" is equal to sub2. + +The first variable "this" equals sub3, the +second variable "that" is equal to sub4. + +.fi +.SH NOTES +No special spacing or carriage returns are required in this file. +.SH "SEE ALSO" +.BR dbLoadTemplate(1), +.BR dbLoadTemplate(3), +.BR subtool(1)