home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / cube.zip / CUBE.DOC < prev    next >
Text File  |  1993-06-07  |  27KB  |  523 lines
  1.                                 CUBE
  2.                                ══════
  3.                                 V2.6
  4.  
  5.  ┌──────────────────────────────────────────────────────────────────────────┐
  6.  │NOTE TO USERS of CUBE versions 1.x : some modifications in strings        │
  7.  │  substitution with environment variables values, and REPSTRING syntax    │
  8.  │  may require that you update Procedure files before using version 2.x    │
  9.  └──────────────────────────────────────────────────────────────────────────┘
  10.  
  11.   CUBE is a REXX procedure used to modify a CONFIG.SYS-like ASCII file (the
  12. Target File), based on a set of CUBE's commands (the Procedure File).
  13.  
  14.   CUBE was initially developped to automatically create/update CONFIG.SYS
  15. or STARTUP.CMD files. It may be integrated in dynamic processes used to
  16. customize PS/2 configurations. Any other ASCII file (such as profiles,
  17. commands files, etc...) may also be customized with CUBE.
  18.  
  19.   CUBE has its own set of commands (described below) that provide editing
  20. functions at the line and string levels. This set of commands includes
  21. ADD, REPLACE and DELETE functions.
  22.  
  23.   Most of CUBE's commands require identification of the Target File line they
  24. act upon: the line will be identify by its leftmost characters (as many as
  25. necessary for a precise or generic identification) starting from column 1.
  26. This was inherited from the CONFIG.SYS type of file CUBE was created for.
  27. However, the option '*ID', wherever available, tells CUBE to identify the
  28. Target File line as any line containing the identification string, starting at
  29. any position. Furthermore, the command LINEID may specify that leading
  30. characters in Target File lines should be ignored (stripped) for identification.
  31.  
  32.   Commands in a Procedure File may be further customized at CUBE's execution
  33. time: strings may contain 'variables' names that will be replaced by their
  34. current value at execution time. This is known as 'substitution' and comes in
  35. two flavors: command line substitution and environment variable substitution.
  36.   Command line substitution: values of variables are passed in the command
  37. line. Environment variable substitution: values of variables are those of
  38. currently defined OS/2 environment variables at CUBE's execution time.
  39.   Substitution in CUBE's commands always occurs, while substitution in a Target
  40. File line only occurs if this line is processed by a CUBE's command.
  41.   Variable names are always identified by delimiters: any single character you
  42. wish, unique for a given variable name, to avoid conflict with other characters
  43. in a string or system interpretation. Variable names ARE case sensitive.
  44.  
  45.  
  46.  
  47.                          CUBE calling syntax
  48.                         ═════════════════════
  49.  ┌───────────────────────────────────────────────────────────────────────────┐
  50.  │ CUBE  procfname  targetfname  [backupfname]  [options]  [ >log-fname ]    │
  51.  ├───────────────────────────────────────────────────────────────────────────┤
  52.  │       procfname = name of Procedure file containing CUBE's commands       │
  53.  │                                     --or--                                │
  54.  │                   { single cube command }                                 │
  55.  │                                     --or--                                │
  56.  │                   QUEUE                                                   │
  57.  │                                                                           │
  58.  │                   Notes: 1) { and } are required delimiters for single    │
  59.  │                             cube command passed on command line.          │
  60.  │                          2) QUEUE (uppercase!) is the required keyword    │
  61.  │                             when CUBE is called from a Rexx command that  │
  62.  │                             have 'queued' cube commands in the session    │
  63.  │                             queue, rather than used a Procedure file.     │
  64.  │                                                                           │
  65.  │     targetfname = name of Target File to be updated                       │
  66.  │                                                                           │
  67.  │     backupfname = if specified, is the file name under which Target File  │
  68.  │                   will be saved, before CUBE's processing                 │
  69.  │                                                                           │
  70.  │         options = [ PAUSE ]                                               │
  71.  │                     CUBE pauses after each command executed from Procfname│
  72.  │                                                                           │
  73.  │                   [ CHECK ]                                               │
  74.  │                     Run CUBE but *DON'T SAVE* the Target File. Return code│
  75.  │                     will reflect the number of changes that would occur   │
  76.  │                     in Target File.                                       │
  77.  │                                                                           │
  78.  │                   [ MAKE code ]                                           │
  79.  │                     Implements the 'conditionnal command execution'. CUBE │
  80.  │                     will only execute the profile's commands that are     │
  81.  │                     under the control of a matching WHEN command. See WHEN│
  82.  │                     command for explanations. Code can be any string,     │
  83.  │                     default is *.                                         │
  84.  │                                                                           │
  85.  │                   [ DLM char  ]                                           │
  86.  │                     Define a new delimiter for CUBE's commands strings.   │
  87.  │                     See definition of d-string below.                     │
  88.  │                                                                           │
  89.  │                   [ RS(#varnam1#=value1 #varnam2#=value2 .... ) ]         │
  90.  │                                                                           │
  91.  │                     Specifies a set of 'variablename=value' . CUBE will   │
  92.  │                     replace each occurrence of a variable, within each    │
  93.  │                     Procedure file command, with its corresponding value. │
  94.  │                     Substitution is done before commands processing.      │
  95.  │                     varnames must be defined with delimiters (# above).   │
  96.  └───────────────────────────────────────────────────────────────────────────┘
  97.  
  98.         examples:  CUBE c:\config.pro config.sys config.bak >cube.log
  99.  
  100.                    CUBE p.cub config.sys (rs(#drive1#=D #drive2#=E) pause
  101.  
  102.                    CUBE {RS "#var2#" (RS#) all} startup.cmd >startup.log
  103.  
  104.                    CUBE QUEUE appl.pro
  105.  
  106.  
  107.                  CUBE Procedure File Commands Syntax
  108.                  ═══════════════════════════════════
  109.  
  110. Within CUBE's commands, any string representing the actual string to be looked
  111. for, replaced and/or inserted in the Target File, must be enclosed between
  112. two identical characters (delimiters). These strings will be referred to as
  113. "d-strings" (delimited strings). The default delimiter is " (double-quote).
  114. DLM option can be used to define your own delimiter for a given CUBE execution.
  115.  
  116. Commands will be interpreted/executed sequentially from Procedure File.
  117. Commands may be upper or lower case. d-strings too, but will be handled
  118. according to the last CASE command encountered (see CASE command).
  119.  
  120. Commands may span on more than one line. A ',' must end a command that is to
  121. be continued on next line. ',' within d-strings will not be interpreted
  122. as a continuation characters.
  123.  
  124. Blank (null) lines are accepted. Comments lines may be inserted, with either
  125. '*' or '--' as their first character(s). Blank and comments lines may NOT
  126. appear in between continuation lines of a command.
  127.  
  128.   ───────────────────────────────────────────────────────────────────────────
  129.  
  130. ONERROR         specify what action to be taken in case of syntax error while
  131.                 processing a command of the current Procedure File.
  132.  
  133.                 ┌──────────────────────────────┐
  134.                 │ ONERROR { CONTINUE | STOP }  │
  135.                 └──────────────────────────────┘
  136.  
  137.                 CONTINUE : issue error message and skip to next command.
  138.                 STOP     : issue error message and stop CUBE processing.
  139.                            All updates to Target File will be lost in this
  140.                            case (even those applied before the ONERROR STOP
  141.                            command).
  142.  
  143.                 Default is STOP if no ONERROR command issued.
  144.  
  145.   ───────────────────────────────────────────────────────────────────────────
  146.  
  147. CASE            specify how Procedure and Target strings are handled for
  148.                 strings comparisons. Once set, it applies for both
  149.                 line identifications and strings identifications within line.
  150.  
  151.                 ┌───────────────────────────────┐
  152.                 │  CASE  { SENSITIVE | IGNORE } │
  153.                 └───────────────────────────────┘
  154.  
  155.                 SENSITIVE: strings comparisons will be case sensitive.
  156.                 IGNORE   : strings comparisons will NOT be case sensitive.
  157.                            ex: "AbCdef" matches "ABCDEf".
  158.  
  159.                 Default is IGNORE if no CASE command issued.
  160.  
  161.   ───────────────────────────────────────────────────────────────────────────
  162.  
  163. WHEN            Following CUBE's commands will only be executed if the CUBE's
  164.                 command line option MAKE matches one of the 'codes' specified.
  165.                 Applies until another WHEN command is found. WHEN has no effect
  166.                 on 'ONERROR', 'CASE', 'LINEID' , 'STRINGDELIMITER' and 'WHEN'
  167.                 commands: these will always get executed.
  168.  
  169.                 ┌──────────────────────────────┐
  170.                 │  WHEN  { code1 ... coden  }  │
  171.                 └──────────────────────────────┘
  172.  
  173.                 coden    : any string, case insensitive.
  174.                            If * then following commands will all get executed,
  175.                            whatever was specified in MAKE option. * always
  176.                            matches the MAKE option.
  177.  
  178.                 Default is * (no WHEN command specified)
  179.  
  180.   ───────────────────────────────────────────────────────────────────────────
  181.  
  182. LINEID          specify that identification of Target File lines should
  183.                 begin at column 1 (CUBE's default) or ignore leading
  184.                 characters.
  185.  
  186.                 ┌─────────────────────────────────┐
  187.                 │  LINEID { NOSTRIP | STRIP "x" } │
  188.                 └─────────────────────────────────┘
  189.  
  190.                 NOSTRIP  : return to default CUBE identification (column 1).
  191.                 STRIP "x": strip leading x's in Target File lines for line
  192.                            identification.
  193.  
  194.                 Default is NOSTRIP if no LINEID command issued.
  195.  
  196.   ───────────────────────────────────────────────────────────────────────────
  197.  
  198. REPLINE         REPLACE an entire LINE of Target File with a new text.
  199.                 The d-string used to identify the line to be replaced,
  200.                 corresponds to the leftmost characters of the line.
  201.                 If the line is not found within Target File, the new line
  202.                 may be added to the Target File.
  203.  
  204.                 ┌───────────────────────────────────────────────┐
  205.                 │  REPLINE lineid WITH replacement [( options]  │
  206.                 └───────────────────────────────────────────────┘
  207.  
  208.                 Command Abbreviation : RL
  209.  
  210.                 lineid      : d-string to identify line
  211.                 replacement : d-string representing the new line
  212.  
  213.                 options     : [ ALL | FIRST | LAST ]
  214.                               [ ADDTOP | ADDBOTTOM | DONTADD ]
  215.                               [ *ID ]
  216.                               [ RS(x) ]
  217.                               [ IF "x"  ]
  218.                               [ IFNOT "x"  ]
  219.  
  220.                 ALL   : replaces ALL occurences of 'lineid' (default)
  221.                 FIRST : only replaces 1st occurences of 'lineid'
  222.                 LAST  : only replaces last occurence of 'lineid'
  223.  
  224.                 ADDTOP    : if no 'lineid', add replacement at top of file
  225.                 ADDBOTTOM : if no 'lineid', add replacement at bottom
  226.                 DONTADD   : if no 'lineid', don't add replacement (default)
  227.  
  228.                 *ID       : target line identification anywhere in the line.
  229.  
  230.                 RS(x)     : replace string(s) within the new line.
  231.                             x is a single character used as a string delimiter
  232.                             for the duration of this command only; all strings
  233.                             delimited by a pair of x, in the new line,
  234.                             will be interpreted as environment variable names
  235.                             replaced by their value. This occurs BEFORE any
  236.                             other REPLINE processing.
  237.  
  238.                 IF "x"    : Replace only if a line identified by "x" exists
  239.                             in the Target File.
  240.                 IFNOT "x" : Replace only if a line identified by "x"
  241.                             doesn't exist in Target File.
  242.   ───────────────────────────────────────────────────────────────────────────
  243.  
  244. ADDLINE         Conditionnally ADDs a LINE to the Target File. Position of
  245.                 the line may be specified by reference to an existing line.
  246.  
  247.                 ┌────────────────────────────┐
  248.                 │ ADDLINE  line  [( options] │
  249.                 └────────────────────────────┘
  250.  
  251.                 Command Abbreviation : AL
  252.  
  253.                 line    : d-string representing the line to be added
  254.  
  255.                 options : [ AFTER x [ONLY] | BEFORE x [ONLY] ]
  256.                           [ IFNEW | ALWAYS ]
  257.                           [ *ID ]
  258.                           [ RS(x) ]
  259.                           [ IF "x"  ]
  260.                           [ IFNOT "x"  ]
  261.  
  262.                 AFTER x  : add after line identified by d-string x.
  263.                            If x is not specified or not present in Target
  264.                            file, line will be added at bottom of Target File.
  265.                 BEFORE x : add before line identified by d-string x.
  266.                            If x is not specified or not present in Target
  267.                            File, line will be added at top of Target File.
  268.                 ONLY     : with AFTER/BEFORE: add only if x there
  269.  
  270.                 IFNEW    : add line only if not already there (default)
  271.                 ALWAYS   : always add line (even if already there)
  272.  
  273.                 *ID      : target line identification anywhere in the line.
  274.  
  275.                 RS(x)    : replace string(s) within the line to be added.
  276.                            x is a single character used as a string delimiter
  277.                            for the duration of this command only; all strings
  278.                            delimited by a pair of x, in the line to be added,
  279.                            will be interpreted as environment variable names
  280.                            replaced by their value. This occurs BEFORE any other
  281.                            ADDLINE processing.
  282.  
  283.                 IF "x"    : Add only if a line identified by "x" exists
  284.                             in the Target File.
  285.                 IFNOT "x" : Add only if a line identified by "x"
  286.                             doesn't exist in Target File.
  287.   ───────────────────────────────────────────────────────────────────────────
  288.  
  289. DELLINE         DELETE a given LINE from Target File.
  290.  
  291.                 ┌────────────────────────────┐
  292.                 │ DELLINE lineid [(options ] │
  293.                 └────────────────────────────┘
  294.  
  295.                 Command Abbreviation : DL
  296.  
  297.                 lineid  : d-string identifying the line to be deleted.
  298.                           Correspond to the lefmost characters of the line.
  299.                 options : [ ALL | FIRST | LAST ]
  300.                           [ *ID ]
  301.                           [ RS(x) ]
  302.                           [ IF "x"  ]
  303.                           [ IFNOT "x"  ]
  304.  
  305.                 ALL     :  deletes all occurences of 'lineid' (default)
  306.                 FIRST   :  only deletes 1st occurence of 'lineid'
  307.                 LAST    :  only deletes last occurence of 'lineid'
  308.  
  309.                 *ID     : target line identification anywhere in the line.
  310.  
  311.                 RS(x)   : replace string(s) within lineid to identify the
  312.                           line to be deleted. Standard RS() pre-processing;
  313.                           refer to addline.
  314.  
  315.                 IF "x"    : Delete only if a line identified by "x" exists
  316.                             in the Target File.
  317.                 IFNOT "x" : Delete only if a line identified by "x"
  318.                             doesn't exist in Target File.
  319.   ───────────────────────────────────────────────────────────────────────────
  320.  
  321. COMMENTLINE     Comment out a line in Target File. In fact, places a
  322.                 user-specified character string at the beginning of a line.
  323.  
  324.                 ┌──────────────────────────────────────────┐
  325.                 │ COMMENTLINE lineid WITH type [(options ] │
  326.                 └──────────────────────────────────────────┘
  327.  
  328.                 Command Abbreviation : CL
  329.  
  330.                 lineid  : d-string identifying the line to be commented out.
  331.                 type    : d-string representing comment character(s)
  332.                 options : [ALL | FIRST | LAST]
  333.                           [ *ID ]
  334.                           [ IF "x"  ]
  335.                           [ IFNOT "x"  ]
  336.  
  337.                 ALL     : comment all occurences of 'lineid' (default)
  338.                 FIRST   : only comments 1st occurence of 'lineid'
  339.                 LAST    : only comments last occurence of 'lineid'
  340.  
  341.                 *ID       : target line identification anywhere in the line.
  342.  
  343.                 IF "x"    : Comment only if a line identified by "x" exists
  344.                             in the Target File.
  345.                 IFNOT "x" : Comment only if a line identified by "x"
  346.                             doesn't exist in Target File.
  347.   ───────────────────────────────────────────────────────────────────────────
  348.  
  349. ADDSTRING       Add a string within a given line of Target File. The position
  350.                 of the string is specified by reference to an existing string
  351.                 within the line.
  352.  
  353.                 ┌──────────────────────────────────────────────────────────────┐
  354.                 │ ADDSTRING string IN lineid ( { AFTER s | BEFORE s} [Options] │
  355.                 └──────────────────────────────────────────────────────────────┘
  356.  
  357.                 Command Abbreviation : AS
  358.  
  359.                 string   : d-string representing the string to be added
  360.                 lineid   : d-string identifying the line where string
  361.                            must be added. Correspond to the leftmost
  362.                            characters of the line.
  363.  
  364.                 AFTER [s]: add string after d-string s in line. If s is not
  365.                            specified or not present in line, string will be
  366.                            added at end of line.
  367.                 BEFORE [s]: add string before d-string s in line. If s is not
  368.                             specified or not present in line, string will be
  369.                             added at beginning of line, but after the
  370.                            identifier (lineid).
  371.  
  372.                 options  : [ IFNEW | ALWAYS ]
  373.                            [ ALL | FIRST | LAST ]
  374.                            [ *ID ]
  375.                            [ RS(x) ]
  376.                            [ ADDTOP | ADDBOTTOM ]
  377.  
  378.                 ALL      : add to all occurences of 'lineid'
  379.                 FIRST    : add only to 1st occurence of 'lineid'
  380.                 LAST     : add only to last occurence of 'lineid'
  381.  
  382.  
  383.                 IFNEW    : add string only if not already there (default)
  384.                 ALWAYS   : always add string (even if already there)
  385.  
  386.                 *ID      : target line identification anywhere in the line.
  387.  
  388.                 RS(x)    : replace substring(s) within the new string.
  389.                            x is a single character used as a string delimiter
  390.                            for the duration of this command only; all substrings
  391.                            delimited by a pair of x, in the new string,
  392.                            will be interpreted as environment variable names
  393.                            replaced by their value. This occurs BEFORE any
  394.                            other ADDSTRING processing.
  395.  
  396.                 ADDTOP   : if lineid not found, adds line lineid || string
  397.                            at TOP of Target File.
  398.                 ADDBOTTOM: if lineid not found, adds line lineid || string
  399.                            at BOTTOM of Target File.
  400.   ───────────────────────────────────────────────────────────────────────────
  401.  
  402. REPSTRING       REPLACE a given STRING by another, within a given line
  403.                 of Target File. If no line is specified (lineid) then
  404.                 all occurences of string within Target File will be
  405.                 replaced with the new string. All occurences of the
  406.                 string in a given line are replaced.
  407.  
  408.                 ┌───────────────────────────────────────────────────────┐
  409.                 │ REPSTRING ostring WITH nstring [IN lineid] [(Options] │
  410.                 └───────────────────────────────────────────────────────┘
  411.                 Command Abbreviation : RS
  412.  
  413.                 ostring  : d-string representing the string to be replaced.
  414.                 nstring  : d-string representing the new string
  415.                 lineid   : d-string identifying the line where string must be
  416.                            replaced. Optional.
  417.                 options  : [ ALL | FIRST | LAST ]
  418.                            [ *ID ]
  419.                            [ RS(x) ]
  420.  
  421.                 ALL      : replaces in all occurences of 'lineid'
  422.                 FIRST    : replaces only in 1st occurence of 'lineid'
  423.                 LAST     : replaces only in last occurence of 'lineid'
  424.  
  425.                 *ID      : target line identification anywhere in the line.
  426.  
  427.                 RS(x)    : replace substring(s) within the new string.
  428.                            x is a single character used as a string delimiter
  429.                            for the duration of this command only; all substrings
  430.                            delimited by a pair of x, in the new string,
  431.                            will be interpreted as environment variable names
  432.                            replaced by their value. This occurs BEFORE any
  433.                            other ADDSTRING processing.
  434.  
  435.   ───────────────────────────────────────────────────────────────────────────
  436.  
  437. DELSTRING       DELETE a given STRING in a given line of Target File. If
  438.                 no line is specified, then all occurrences of string within
  439.                 Target File will be deleted. All occurences of the string in
  440.                 a given line are deleted.
  441.  
  442.                 ┌─────────────────────────────────────────┐
  443.                 │ DELSTRING string [IN lineid] [(Options] │
  444.                 └─────────────────────────────────────────┘
  445.                 Command Abbreviation : DS
  446.  
  447.                 string   : d-string representing the string to be deleted.
  448.                 lineid   : d-string identifying the line where string must be
  449.                            deleted. Optional.
  450.                 options  : [ ALL | FIRST | LAST ]
  451.                            [ *ID ]
  452.                            [ RS(x) ]
  453.  
  454.                 ALL      : deletes in all occurences of 'lineid'
  455.                 FIRST    : deletes only in 1st occurence of 'lineid'
  456.                 LAST     : deletes only in last occurence of 'lineid'
  457.  
  458.                 *ID       : target line identification anywhere in the line.
  459.  
  460.                 RS(x)     : replace substring(s) within string to be deleted.
  461.                             Standard RS() pre-processing; refer to addstring.
  462.   ───────────────────────────────────────────────────────────────────────────
  463.  
  464. Examples:
  465.  
  466. ONError CONTINUE
  467.   continue processing even in case of error(s)
  468.  
  469. REPline "COUNTRY=" with "COUNTRY=001,C:\OS2\SYSTEM\COUNTRY.SYS" (ADDBOTTOM
  470.   replaces all occurences of lines starting with "COUNTRY="
  471.   adds new line at bottom of Target File if no line starting with "COUNTRY="
  472.   exists.
  473.  
  474. ADDLINE "CODEPAGE=437,850" (AFTER "COUNTRY=" IFNEW
  475.   adds a line "CODEPAGE=437,850" after the line starting with "COUNTRY=" ,
  476.   only if "CODEPAGE=437,850" doesn't already exist in Target File. If it
  477.   is to be added and no line starting with "COUNTRY=" exist, then add at
  478.   bottom of file (implied by AFTER).
  479.  
  480. DELLINE "SET=" (first
  481.   deletes the first line starting with "SET=" .
  482.  
  483. DELLINE "SET=" (first  ifnot "REQUIRESET"
  484.   deletes the first line starting with "SET=" only if Target File does not
  485.   contain a line starting "REQUIRESET"
  486.  
  487. commentline "ifs=c:\os2\hpfs.ifs" with "rem "
  488.   comments the line starting with "IFS=C:\OS2\HPFS.IFS" with "REM ". Line
  489.   will then be: REM IFS=C:\OS2\HPFS.IFS ....
  490.  
  491. ADDSTRING "C:\MYDLL;" IN "LIBPATH=" (FIRST IFNEW BEFORE "C:\OS2\DLL;"
  492.   adds "C:\MYDLL;", if it doesn't already exist, within the line starting
  493.   with "LIBPATH=". Adds the string before "C:\OS2\DLL;" if it exists;
  494.   otherwise adds the string after "LIBPATH=".
  495.  
  496. AS "MYNAME" IN "USERID" (AFTER *ID
  497.   adds "MYNAME", if it doesn't already exist, within any line containing
  498.   "USERID". Adds the string after "USERID".
  499.  
  500. AS "#indirect# IN "SET VALUES=" (AFTER RS(#)
  501.   assuming that the command 'SET INDIRECT=3' has been executed prior to CUBE
  502.   execution, appends "3", if it doesn't already exists, to "SET VALUES=".
  503.  
  504. REPSTRING "D:\TOOLKT13\IPFC;" WITH "D:\TK13\IPFC" IN "SET HELP=" (LAST
  505.   replaces the string "D:\TOOLKT13\IPFC; with "D:\TK13\IPFC;" within the
  506.   last line starting with "SET HELP=".
  507.  
  508. REPSTRING "D:\TOOLKT13" WITH "D:\TK13" (all
  509.   replaces all occurences of "D:\TOOLKT13" with "D:\TK13".
  510.  
  511. AL "USER=#name#,NODE=#node#" (AFTER IFNEW
  512.   assuming CUBE has been invoked with option (RS(#name#=ME #node#=HERE), will
  513.   adds a line "USER=ME,NODE=HERE" .
  514.  
  515. WHEN C
  516.   assuming CUBE has been invoked with option (MAKE C , the following commands
  517.   will be executed.
  518.  
  519. DELSTRING _xxx"xxxxxxx_ (All
  520.   deletes all occurences of  xxx"xxxxxxx  if option DLM _ was used on
  521.   CUBE's command line
  522.  
  523.