                                CUBE
                               
                                V3.0

 Ŀ
 NOTE TO USERS of CUBE versions 1.x : some modifications in strings        
   substitution with environment variables values, and REPSTRING syntax    
   may require that you update Procedure files before using version 2.x    
 

  CUBE is a REXX procedure used to modify a CONFIG.SYS-like ASCII file (the
Target File), based on a set of CUBE's commands (the Procedure File).

  CUBE was initially developped to automatically create/update CONFIG.SYS
or STARTUP.CMD files. It may be integrated in dynamic processes used to
customize PS/2 configurations. Any other ASCII file (such as profiles,
commands files, etc...) may also be customized with CUBE.

  CUBE has its own set of commands (described below) that provide editing
functions at the line and string levels. This set of commands includes
ADD, REPLACE and DELETE functions.

  Most of CUBE's commands require identification of the Target File line they
act upon: the line will be identify by its leftmost characters (as many as
necessary for a precise or generic identification) starting from column 1.
This was inherited from the CONFIG.SYS type of file CUBE was created for.
However, the option '*ID', wherever available, tells CUBE to identify the
Target File line as any line containing the identification string, starting at
any position. Furthermore, the command LINEID may specify that leading
characters in Target File lines should be ignored (stripped) for identification.

  Commands in a Procedure File may be further customized at CUBE's execution
time: strings may contain 'variables' names that will be replaced by their
current value at execution time. This is known as 'substitution' and comes in
two flavors: command line substitution and environment variable substitution.
  Command line substitution: values of variables are passed in the command
line. Environment variable substitution: values of variables are those of
currently defined OS/2 environment variables at CUBE's execution time.
  Substitution in CUBE's commands always occurs, while substitution in a Target
File line only occurs if this line is processed by a CUBE's command.
  Variable names are always identified by delimiters: any single character you
wish, unique for a given variable name, to avoid conflict with other characters
in a string or system interpretation. Variable names ARE case sensitive.



                         CUBE calling syntax
                        
 Ŀ
  CUBE  procfname  targetfname  [backupfname]  [ ( options]  [ >log-fname ] 
 Ĵ
        procfname = name of Procedure file containing CUBE's commands       
                                      --or--                                
                    { single cube command }                                 
                                      --or--                                
                    QUEUE                                                   
                                                                            
                    Notes: 1) { and } are required delimiters for single    
                              cube command passed on command line.          
                           2) QUEUE (uppercase!) is the required keyword    
                              when CUBE is called from a Rexx command that  
                              have 'queued' cube commands in the session    
                              queue, rather than used a Procedure file.     
                                                                            
      targetfname = name of Target File to be updated                       
                                                                            
      backupfname = if specified, is the file name under which Target File  
                    will be saved, before CUBE's processing                 
                                                                            
          options = [ PAUSE ]                                               
                      CUBE pauses after each command executed from Procfname
                                                                            
                    [ CHECK ]                                               
                      Run CUBE but *DON'T SAVE* the Target File. Return code
                      will reflect the number of changes that would occur   
                      in Target File.                                       
                                                                            
                    [ MAKE code ]                                           
                      Implements the 'conditionnal command execution'. CUBE 
                      will only execute the profile's commands that are     
                      under the control of a matching WHEN command. See WHEN
                      command for explanations. Code can be any string,     
                      default is *.                                         
                                                                            
                    [ DLM char  ]                                           
                      Define a new delimiter for CUBE's commands strings.   
                      See definition of d-string below.                     
                                                                            
                    [ RS(#varnam1#=value1 #varnam2#=value2 .... ) ]         
                                                                            
                      Specifies a set of 'variablename=value' . CUBE will   
                      replace each occurrence of a variable, within each    
                      Procedure file command, with its corresponding value. 
                      Substitution is done before commands processing.      
                      varnames must be defined with delimiters (# above).   
 

        examples:  CUBE c:\config.pro config.sys config.bak >cube.log

                   CUBE p.cub config.sys (rs(#drive1#=D #drive2#=E) pause

                   CUBE {RS "#var2#" (RS#) all} startup.cmd >startup.log

                   CUBE QUEUE appl.pro


                 CUBE Procedure File Commands Syntax
                 

Within CUBE's commands, any string representing the actual string to be looked
for, replaced and/or inserted in the Target File, must be enclosed between
two identical characters (delimiters). These strings will be referred to as
"d-strings" (delimited strings). The default delimiter is " (double-quote).
DLM option can be used to define your own delimiter for a given CUBE execution.

Commands will be interpreted/executed sequentially from Procedure File.
Commands may be upper or lower case. d-strings too, but will be handled
according to the last CASE command encountered (see CASE command).

Commands may span on more than one line. A ',' must end a command that is to
be continued on next line. ',' within d-strings will not be interpreted
as a continuation characters.

Blank (null) lines are accepted. Comments lines may be inserted, with either
'*' or '--' as their first character(s). Blank and comments lines may NOT
appear in between continuation lines of a command.

  

ONERROR         specify what action to be taken in case of syntax error while
                processing a command of the current Procedure File.

                Ŀ
                 ONERROR { CONTINUE | STOP }  
                

                CONTINUE : issue error message and skip to next command.
                STOP     : issue error message and stop CUBE processing.
                           All updates to Target File will be lost in this
                           case (even those applied before the ONERROR STOP
                           command).

                Default is STOP if no ONERROR command issued.

  

CASE            specify how Procedure and Target strings are handled for
                strings comparisons. Once set, it applies for both
                line identifications and strings identifications within line.

                Ŀ
                  CASE  { SENSITIVE | IGNORE } 
                

                SENSITIVE: strings comparisons will be case sensitive.
                IGNORE   : strings comparisons will NOT be case sensitive.
                           ex: "AbCdef" matches "ABCDEf".

                Default is IGNORE if no CASE command issued.

  

WHEN            Following CUBE's commands will only be executed if the CUBE's
                command line option MAKE matches one of the 'codes' specified.
                Applies until another WHEN command is found. WHEN has no effect
                on 'ONERROR', 'CASE', 'LINEID' , 'STRINGDELIMITER' and 'WHEN'
                commands: these will always get executed.

                Ŀ
                  WHEN  { code1 ... coden  }  
                

                coden    : any string, case insensitive.
                           If * then following commands will all get executed,
                           whatever was specified in MAKE option. * always
                           matches the MAKE option.

                Default is * (no WHEN command specified)

  

LINEID          specify that identification of Target File lines should
                begin at column 1 (CUBE's default) or ignore leading
                characters.

                Ŀ
                  LINEID { NOSTRIP | STRIP "x" } 
                

                NOSTRIP  : return to default CUBE identification (column 1).
                STRIP "x": strip leading x's in Target File lines for line
                           identification.

                Default is NOSTRIP if no LINEID command issued.

  

REPLINE         REPLACE an entire LINE of Target File with a new text.
                The d-string used to identify the line to be replaced,
                corresponds to the leftmost characters of the line.
                If the line is not found within Target File, the new line
                may be added to the Target File.

                Ŀ
                  REPLINE lineid WITH replacement [( options]  
                

                Command Abbreviation : RL

                lineid      : d-string to identify line
                replacement : d-string representing the new line

                options     : [ ALL | FIRST | LAST ]
                              [ ADDTOP | ADDBOTTOM | DONTADD ]
                              [ *ID ]
                              [ RS(x) ]
                              [ IF "x"  ]
                              [ IFNOT "x"  ]

                ALL   : replaces ALL occurences of 'lineid' (default)
                FIRST : only replaces 1st occurences of 'lineid'
                LAST  : only replaces last occurence of 'lineid'

                ADDTOP    : if no 'lineid', add replacement at top of file
                ADDBOTTOM : if no 'lineid', add replacement at bottom
                DONTADD   : if no 'lineid', don't add replacement (default)

                *ID       : target line identification anywhere in the line.

                RS(x)     : replace string(s) within the new line.
                            x is a single character used as a string delimiter
                            for the duration of this command only; all strings
                            delimited by a pair of x, in the new line,
                            will be interpreted as environment variable names
                            replaced by their value. This occurs BEFORE any
                            other REPLINE processing.

                IF "x"    : Replace only if a line identified by "x" exists
                            in the Target File.
                IFNOT "x" : Replace only if a line identified by "x"
                            doesn't exist in Target File.
  

ADDLINE         Conditionnally ADDs a LINE to the Target File. Position of
                the line may be specified by reference to an existing line.

                Ŀ
                 ADDLINE  line  [( options] 
                

                Command Abbreviation : AL

                line    : d-string representing the line to be added

                options : [ AFTER x [ONLY] | BEFORE x [ONLY] ]
                          [ IFNEW | ALWAYS ]
                          [ *ID ]
                          [ RS(x) ]
                          [ IF "x"  ]
                          [ IFNOT "x"  ]

                AFTER x  : add after line identified by d-string x.
                           If x is not specified or not present in Target
                           file, line will be added at bottom of Target File.
                BEFORE x : add before line identified by d-string x.
                           If x is not specified or not present in Target
                           File, line will be added at top of Target File.
                ONLY     : with AFTER/BEFORE: add only if x there

                IFNEW    : add line only if not already there (default)
                ALWAYS   : always add line (even if already there)

                *ID      : target line identification anywhere in the line.

                RS(x)    : replace string(s) within the line to be added.
                           x is a single character used as a string delimiter
                           for the duration of this command only; all strings
                           delimited by a pair of x, in the line to be added,
                           will be interpreted as environment variable names
                           replaced by their value. This occurs BEFORE any other
                           ADDLINE processing.

                IF "x"    : Add only if a line identified by "x" exists
                            in the Target File.
                IFNOT "x" : Add only if a line identified by "x"
                            doesn't exist in Target File.
  

DELLINE         DELETE a given LINE from Target File.

                Ŀ
                 DELLINE lineid [(options ] 
                

                Command Abbreviation : DL

                lineid  : d-string identifying the line to be deleted.
                          Correspond to the lefmost characters of the line.
                options : [ ALL | FIRST | LAST ]
                          [ *ID ]
                          [ RS(x) ]
                          [ IF "x"  ]
                          [ IFNOT "x"  ]

                ALL     :  deletes all occurences of 'lineid' (default)
                FIRST   :  only deletes 1st occurence of 'lineid'
                LAST    :  only deletes last occurence of 'lineid'

                *ID     : target line identification anywhere in the line.

                RS(x)   : replace string(s) within lineid to identify the
                          line to be deleted. Standard RS() pre-processing;
                          refer to addline.

                IF "x"    : Delete only if a line identified by "x" exists
                            in the Target File.
                IFNOT "x" : Delete only if a line identified by "x"
                            doesn't exist in Target File.
  

COMMENTLINE     Comment out a line in Target File. In fact, places a
                user-specified character string at the beginning of a line.

                Ŀ
                 COMMENTLINE lineid WITH type [(options ] 
                

                Command Abbreviation : CL

                lineid  : d-string identifying the line to be commented out.
                type    : d-string representing comment character(s)
                options : [ALL | FIRST | LAST]
                          [ *ID ]
                          [ IF "x"  ]
                          [ IFNOT "x"  ]

                ALL     : comment all occurences of 'lineid' (default)
                FIRST   : only comments 1st occurence of 'lineid'
                LAST    : only comments last occurence of 'lineid'

                *ID       : target line identification anywhere in the line.

                IF "x"    : Comment only if a line identified by "x" exists
                            in the Target File.
                IFNOT "x" : Comment only if a line identified by "x"
                            doesn't exist in Target File.
  

ADDSTRING       Add a string within a given line of Target File. The position
                of the string is specified by reference to an existing string
                within the line.

                Ŀ
                 ADDSTRING string IN lineid ( { AFTER s | BEFORE s} [Options] 
                

                Command Abbreviation : AS

                string   : d-string representing the string to be added
                lineid   : d-string identifying the line where string
                           must be added. Correspond to the leftmost
                           characters of the line.

                AFTER [s]: add string after d-string s in line. If s is not
                           specified or not present in line, string will be
                           added at end of line.
                BEFORE [s]: add string before d-string s in line. If s is not
                            specified or not present in line, string will be
                            added at beginning of line, but after the
                           identifier (lineid).

                options  : [ IFNEW | ALWAYS ]
                           [ ALL | FIRST | LAST ]
                           [ *ID ]
                           [ RS(x) ]
                           [ ADDTOP | ADDBOTTOM ]

                ALL      : add to all occurences of 'lineid'
                FIRST    : add only to 1st occurence of 'lineid'
                LAST     : add only to last occurence of 'lineid'


                IFNEW    : add string only if not already there (default)
                ALWAYS   : always add string (even if already there)

                *ID      : target line identification anywhere in the line.

                RS(x)    : replace substring(s) within the new string.
                           x is a single character used as a string delimiter
                           for the duration of this command only; all substrings
                           delimited by a pair of x, in the new string,
                           will be interpreted as environment variable names
                           replaced by their value. This occurs BEFORE any
                           other ADDSTRING processing.

                ADDTOP   : if lineid not found, adds line lineid || string
                           at TOP of Target File.
                ADDBOTTOM: if lineid not found, adds line lineid || string
                           at BOTTOM of Target File.
  

REPSTRING       REPLACE a given STRING by another, within a given line
                of Target File. If no line is specified (lineid) then
                all occurences of string within Target File will be
                replaced with the new string. All occurences of the
                string in a given line are replaced.

                Ŀ
                 REPSTRING ostring WITH nstring [IN lineid] [(Options] 
                
                Command Abbreviation : RS

                ostring  : d-string representing the string to be replaced.
                nstring  : d-string representing the new string
                lineid   : d-string identifying the line where string must be
                           replaced. Optional.
                options  : [ ALL | FIRST | LAST ]
                           [ *ID ]
                           [ RS(x) ]

                ALL      : replaces in all occurences of 'lineid'
                FIRST    : replaces only in 1st occurence of 'lineid'
                LAST     : replaces only in last occurence of 'lineid'

                *ID      : target line identification anywhere in the line.

                RS(x)    : replace substring(s) within the new string.
                           x is a single character used as a string delimiter
                           for the duration of this command only; all substrings
                           delimited by a pair of x, in the new string,
                           will be interpreted as environment variable names
                           replaced by their value. This occurs BEFORE any
                           other ADDSTRING processing.

  

DELSTRING       DELETE a given STRING in a given line of Target File. If
                no line is specified, then all occurrences of string within
                Target File will be deleted. All occurences of the string in
                a given line are deleted.

                Ŀ
                 DELSTRING string [IN lineid] [(Options] 
                
                Command Abbreviation : DS

                string   : d-string representing the string to be deleted.
                lineid   : d-string identifying the line where string must be
                           deleted. Optional.
                options  : [ ALL | FIRST | LAST ]
                           [ *ID ]
                           [ RS(x) ]

                ALL      : deletes in all occurences of 'lineid'
                FIRST    : deletes only in 1st occurence of 'lineid'
                LAST     : deletes only in last occurence of 'lineid'

                *ID       : target line identification anywhere in the line.

                RS(x)     : replace substring(s) within string to be deleted.
                            Standard RS() pre-processing; refer to addstring.
  

Examples:

ONError CONTINUE
  continue processing even in case of error(s)

REPline "COUNTRY=" with "COUNTRY=001,C:\OS2\SYSTEM\COUNTRY.SYS" (ADDBOTTOM
  replaces all occurences of lines starting with "COUNTRY="
  adds new line at bottom of Target File if no line starting with "COUNTRY="
  exists.

ADDLINE "CODEPAGE=437,850" (AFTER "COUNTRY=" IFNEW
  adds a line "CODEPAGE=437,850" after the line starting with "COUNTRY=" ,
  only if "CODEPAGE=437,850" doesn't already exist in Target File. If it
  is to be added and no line starting with "COUNTRY=" exist, then add at
  bottom of file (implied by AFTER).

DELLINE "SET=" (first
  deletes the first line starting with "SET=" .

DELLINE "SET=" (first  ifnot "REQUIRESET"
  deletes the first line starting with "SET=" only if Target File does not
  contain a line starting "REQUIRESET"

commentline "ifs=c:\os2\hpfs.ifs" with "rem "
  comments the line starting with "IFS=C:\OS2\HPFS.IFS" with "REM ". Line
  will then be: REM IFS=C:\OS2\HPFS.IFS ....

ADDSTRING "C:\MYDLL;" IN "LIBPATH=" (FIRST IFNEW BEFORE "C:\OS2\DLL;"
  adds "C:\MYDLL;", if it doesn't already exist, within the line starting
  with "LIBPATH=". Adds the string before "C:\OS2\DLL;" if it exists;
  otherwise adds the string after "LIBPATH=".

AS "MYNAME" IN "USERID" (AFTER *ID
  adds "MYNAME", if it doesn't already exist, within any line containing
  "USERID". Adds the string after "USERID".

AS "#indirect# IN "SET VALUES=" (AFTER RS(#)
  assuming that the command 'SET INDIRECT=3' has been executed prior to CUBE
  execution, appends "3", if it doesn't already exists, to "SET VALUES=".

REPSTRING "D:\TOOLKT13\IPFC;" WITH "D:\TK13\IPFC" IN "SET HELP=" (LAST
  replaces the string "D:\TOOLKT13\IPFC; with "D:\TK13\IPFC;" within the
  last line starting with "SET HELP=".

REPSTRING "D:\TOOLKT13" WITH "D:\TK13" (all
  replaces all occurences of "D:\TOOLKT13" with "D:\TK13".

AL "USER=#name#,NODE=#node#" (AFTER IFNEW
  assuming CUBE has been invoked with option (RS(#name#=ME #node#=HERE), will
  adds a line "USER=ME,NODE=HERE" .

WHEN C
  assuming CUBE has been invoked with option (MAKE C , the following commands
  will be executed.

DELSTRING _xxx"xxxxxxx_ (All
  deletes all occurences of  xxx"xxxxxxx  if option DLM _ was used on
  CUBE's command line
