From 492360a3d47871423d6bab5774bd6bbb8e98706e Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Fri, 20 Apr 2012 17:38:59 -0500 Subject: [PATCH] Documentation updates Clear out old stuff. Introduce global macro syntax. --- src/dbtools/msi.html | 53 +++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 28 deletions(-) diff --git a/src/dbtools/msi.html b/src/dbtools/msi.html index 7fd58c6a5..0be7bef5f 100644 --- a/src/dbtools/msi.html +++ b/src/dbtools/msi.html @@ -9,10 +9,6 @@

msi: Macro Substitution and Include Tool

-
-

Version 1.5, 10th November, 2008

-
-

Introduction

msi is a general purpose macro substitution/include tool. It accepts as input @@ -114,9 +110,8 @@ specify an illegal switch, e.g.

substitution is performed. If no file is given then input is read from stdin. Variable instances to be substituted by macro values are expressed in the template using the syntax $(name) or -${name}. If msi has been built with EPICS Base version -3.14.7 or later, the template can also provide default values to be used when a -macro has not been given a value, using the syntax +${name}. The template can also provide default values +to be used when a macro has not been given a value, using the syntax $(name=default) or ${name=default}.

@@ -230,9 +225,9 @@ first name is Irma family name is Kraimer -

Note that on an IOC when using the dbLoadTemplate command, the -template file does not support the substitute command, although -include is supported.

+

Note that the IOC's dbLoadTemplate command does not support the +substitute syntax in template files, although the include +syntax is supported.

Substitution File Format

@@ -242,8 +237,10 @@ dbTemplate format. We will discuss each separately.

Regular format

-
{var1=set1_val1, var2=set1_val2, ...}
+
global {gbl_var1=gbl_val1, gbl_var2=gbl_val2, ...}
+{var1=set1_val1, var2=set1_val2, ...}
 {var2=set2_val2, var1=set2_val1, ...}
+global {gbl_var1=gbl_val3, gbl_var2=gbl_val4, ...}
 {var1=set3_val1, var2=set3_val2, ...}
 {var2=set4_val2, var1=set4_val1, ...}
@@ -254,24 +251,27 @@ set of braces containing macro replacement values.

Pattern format

-
pattern {var1, var2, ...}
+
global {gbl_var1=gbl_val1, gbl_var2=gbl_val2, ...}
+pattern {var1, var2, ...}
 {set1_val1, set1_val2, ...}
 {set2_val1, set2_val2, ...}
 pattern {var2, var1, ...}
+global {gbl_var1=gbl_val3, gbl_var2=gbl_val4, ...}
 {set3_val2, set3_val1, ...}
 {set4_val2, set4_val2, ...}

This produces the same result as the regular format example above.

-

dbTemplate Format

+

dbLoadTemplate Format

This format is an extension of the format accepted by the EPICS IOC command dbLoadTemplate, and allows templates to be expanded on the host rather by using dbLoadTemplate at IOC boot time.

-
file template {
+
global {gbl_var1=gbl_val1, gbl_var2=gbl_val2, ...}
+file templatefile {
     pattern format or regular format
 }
 file "${WHERE}/template2" {
@@ -290,6 +290,11 @@ the filenames listed in the substitutions files.

 ignored. A comment line is any line beginning with the character #,
 which must be the very first character on the line.

 
+
Global definitions may supplement or override the macro values supplied on
+the command-line using the -M switch, and set default values that will
+survive for the remainder of the file unless another global definition of the
+same macro changes it.

+
 
For definitions within braces given in any of the file formats, a separator
 must be given between items. A separator is either a comma, or one or more of
 the standard white space characters (space, formfeed, newline, carriage return,
@@ -310,11 +315,10 @@ all equivalent:

 }
-

Within a substitutions file, the file name may appear inside double -quotation marks; these are only required if the name contains environment +

Within a substitutions file, the file name may appear inside double quotation +marks; these are required if the name contains certain characters or environment variable macros of the form ${ENV_VAR} or $(ENV_VAR), which will be expanded -before the file is opened. Environment variable macro expansion is only -available when msi has been built using EPICS base R3.14.3 or newer.

+before the file is opened.

Regular substitution example

@@ -334,8 +338,9 @@ family name is ${family}

and the file substitute is

-
{first=Marty,family=Kraimer}
-{first=Irma,family=Kraimer}
+
global {family=Kraimer}
+{first=Marty}
+{first=Irma}

The following is the output produced:

@@ -421,13 +426,5 @@ first name is Irma family name is Kraimer -

Building msi

- -

msi is built as a normal extensions product, and can be built with any -version of EPICS Base from 3.13.0beta11 onwards. Base version 3.14.3 or later -is required if the ability to expand environment variables in filenames is -needed. Base version 3.14.7 or later is required to allow the use of default -macro values in template files.

-