CUBE (Config Update/Batch Editing)

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