Family members

CUBE V3.3


DISCLAIMER

I or any other contributors allow you to use and modify freely under the condition that I or other contributors are in no way responsible for any damage or loss you may suffer.

WHAT'S NEW

HISTORY

History
09/10/03V3.3new COMMENT TOP, AL (COPY
MAKE can be several words
braces for single command for backward compatibility
improved UPKWD
datapath mapping (gjarvis@ieee.org)
24/05/03V3.2dynamic string delimiters
rewrote documentation in xhtml format
strings in options are excluded from keyword search
code reuse heavily exploited command line
RS()->ENV & KEY with greater flexibility
tested and fixed most options
requires Object REXX (gjarvis@ieee.org)
20/03/03V3.1unreleased - untested code) (gjarvis@ieee.org)
ADDSTRING\DELSTRING now handles separation char
25/06/02V3.0In procedure "C:\" replaced by actual boot path
Added verb COMMENT & IGNORESPACES
New cmd line print usage & option VBACK
show only changed lines
(gjarvis@ieee.org)
04/06/93V2.6Add 'procedure read from QUEUE' (from Steve
03/06/93V2.5Add IF/IFNOT to xLINE cmds (generalize N. Marks
Correct ADDSTRING BEFORE option (Neil Marks)
07/04/93V2.4Corrected ADDBOTTOM/ADDTOP in ADDSTRING (Per Hertz)
Address cmd + CHECK Option + new exit rtne
21/01/93V2.3Added user defined string delimiter in CUBE cmds
21/12/92V2.2Added conditionnal command processing (WHEN)
26/11/92V2.1RS() for DL, DS (desinstallation case)
New LINEID command (strip leading chars)
ADDTOP,ADDBOTTOM for AS (W. Pachl requirement)
Fix Whereis (Walter Pachl).
Exit with SaveFile return code (Walter Pachl)
18/11/92V2.0Changes with environment variable substitution (RS)
(AS, RS, AL & AL now all have same RS() option)
Logging of all changes made to Target File
Adapt/Include some of Walter Pachl's enhancements:
Single CUBE command on command line
Add'l string substitution at command line level
PAUSE option (debugging purposes)
05/11/92V1.5AL with pre substitution
03/11/92V1.4AS with substitution ; fix RS recursion.
02/11/92V1.3Bug fixes & cmds abbrev, thanks to Walter Pachl.
Target Backup & lineid no more limited to col 1.
30/10/92V1.2Added env variable substitution + version #
31/08/92V1.1Bug fix
21/07/92V1.0Initial revision
Didier LAFON - LAFON at CBEPROFS

DOCUMENTATION

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 developed 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.

Commands consist of keywords and strings. Keywords can be any case. All strings are surrounded by a character delimiter from the set "'`!@#$%^&. This set is easy to remember on a QWERTY layout keyboard. All 3 quotes plus shift_1 to shift_7. Both ends of string must use the same delimiter. The case of strings are always preserved on target modifications but for string matches, which can be modified, the default being case insensitive.

Some commands have options. When using an options, the first option is preceded by a left brace. Options, unlike parameters, may be given in any order. An option consist of a keyword and may have a string following the keyword.

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 or handle text profiles intelligently. You can define what defines a comment in a Target file an exclude them from identification. You can define begin, block, trail and top comments.

Strings at CUBE's execution time are replaced by their current value at execution time. Both D:\ is replaced with actual data path which is defined as the drive running CUBE and C:\ is replaced with actual boot path.

Strings 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 with the KEY option. Environment variable substitution: values of variables are those of currently defined OS/2 environment variables at CUBE's execution time. Substitution in a Target File line only occurs if this line is processed by a CUBE's command with corresponds KEY or ENV option. The value of both keywords and environment variables, case is preserved and may include any character including spaces. If a value is missing, then it is flagged as an error which can be changed by ONERROR command or preferably check with command line option TEST.

You can select parts of a Procedure File to be executed by using both command WHEN and command line option MAKE. These can also tested with command line option TEST.

Command Line Syntax

Command Line Syntax
CUBE procfname targetfname [backupfname] [(options] [>log-fname]
CUBE 'single cube command' targetfname [backupfname] [(options] [>log-fname]
CUBE QUEUE targetfname [backupfname] [(options] [>log-fname]
CUBE
Parameter Description
procfname name of Procedure file containing CUBE's commands
targetfname name of target file to modify
backupfname name of the original target file renamed to *.bak
log-fname name of log file to catch standard out
Notes:
  • For single cube command passed on command line, use either braces or a dynamic delimiter.
  • 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.
  • If no arguements are given then the commmand line usage is displayed.
Options Description
PAUSE pauses after each command executed from Procfname Each command is displayed even if no change in target rather only show command for changed target line.
CHECK CUBE but *DON'T SAVE* the Target File. Return code will reflect the number of changes that would occur in Target File. Each command is displayed even if no change in target rather only show command for changed target line.
VBACK Uses VBACK, an intelligent back up routine. Only backs if file date has changed. Back up existing target file if needed. Back up the new target file if needed.
MAKE "c1 c2 ..." Implements the 'conditional 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. Codes are space seperated alpha-numeric identifer that's case insensitive. Empty list is valid.
KEY "k1 'v1' k2 'v2' ...." Specifies a list of keyword and value pairs. CUBE will replace each occurrence of a keyword, in commands that have a KEY option set, with its corresponding value. Substitution is done when command is processed.
TEST Test for [WHEN] command and [KEY] and [ENV] options by running in a dummy mode showing all [WHEN] and undefine [KEY] and [ENV].

examples:

CUBE c:\config.pro config.sys config.bak >cube.log
CUBE p.cub config.sys (KEY "drive1 #D:# drive2 #E:#" pause
CUBE {RS "F:\" WITH "G:\" (ALL} startup.cmd >startup.log
CUBE QUEUE appl.pro

Other Recommend Tools


Netlabs EPM Distribution
PCI card sniffer
Craig's PCI page
Initor (simple INI editor)
Graphical File Compare

CUBE Procedure File Syntax

The Procedure file is a text file that is read one line at a time. Blank lines are ignored. Comments lines may be inserted, with either '*' or '--' as their first character(s) are also ignored. Non-ignored lines are treated as commands.

Commands may span on more than one line. A comma must end the line that is to be continued on next line. Strings can not be split. Blank and comments lines may not appear in between continuation lines of a command.

Commands are divided into two groups: modifiers and functions. Modifiers have an effect interpretation on subsequent commands. Functions operate on the target file.

Modifiers
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.
Parameter 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.
COMMENT Defines what constitutes comments in a target file. This command is useful for text profiles as C:\ibmlan\ibmlan.ini rather than config.sys. One may define upto 3 different comment types.
Parameter COMMENT BEGIN "x" | BLOCK "x" TO "y" | TAIL "x" | TOP "x" | QUOTE "x"
BEGIN "x" A line beginning with x is ignored
BLOCK "x" TO "y" All lines between x and y are ignored. x and y can proceeded by any characters. If x is preceded by non-blank characters then it is treated as tail comment.
TAIL "x" If a line containing x is proceeded by spaces then line is ignored else the rest of line is excluded from string matches. Default is no comments defined.
TOP "x" If x is a number then the top x lines is treated as a comment, else the first line to the line containing x anywhere on the line is treated as a comment. Any function that insert a line at top will actually insert line after this top comment. Default is line 0 (none).
QUOTE "x" Any character of x is a delimiter of a quoted string. Can used with escape option to sophisticated strings such C language. Quoted strings may have embedded comments and can provide extra info that some string functions can take advantage of.
LINEID specify that indentation of Target File lines should begin at column 1 (CUBE's default) or ignore leading characters.
Parameter LINEID NOSTRIP | STRIP "x" | PROFILE
NOSTRIP return to default CUBE identification (column 1).
STRIP "x" strip all leading x (one character) in the Target File lines for line identification. Default is NOSTRIP if no LINEID command issued.
PROFILE If a string starts with at least one space then the target must also start with at least one space. The amount of indentation is not important in matches. This command is useful for text profiles as C:\ibmlan\ibmlan.ini rather than config.sys.
ONERROR specify what action to be taken in case of syntax error while processing a command of the current Procedure File.
Parameter ONERROR CONTINUE | STOP
CONTINUE issue error message and skip to next command.
STOP issue error message and stop CUBE processing. All updates to the Target File will be lost in this case (even those applied before the ONERROR STOP command). Default is STOP if no ONERROR command issued.
SELECTAREA Restrict funnctions to selected are of target.
Parameter SELECTAREA lineid1 TO lineid2 (INCLUDE
SA lineid1 TO lineid2 (INCLUDE
lineid1 lineid of from line of target.
lineid2 lineid of to line of target.
INCLUDE Lineids are included in area, normaly area is between them.
WHEN CUBE's functions 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. Note that all modifiers will always be executed. The space separated list has no delimiters and can be any alpha-numeric identifier or an asterisk. An asterisk will match any make. At the start of CUBE there is an implicit asterisk.
Parameter WHEN code1 code2 ... coden
codei can be any alpha-numeric identifer that's case insensitive. "*" always matches the MAKE option. Default is * (no WHEN command specified)
Functions
ADDLINE Conditionally Adds a LINE to the Target File. Position of the line may be specified by reference to an existing line.
Parameter ADDLINE line [( options]
AL line [( options]
line representing the line to be added
Options [AFTER|BEFORE [ONLY]] [IFNEW|ALWAYS|COPY] [*ID] [ENV] [KEY] [IF|IFNOT]
AFTER ["x"] if line not found then add line after lineid x. If x is not found then add to bottom of the Target file.
BEFORE ["x"] if line not found then add line before lineid x. If x is not found then add to top of the Target file.
ONLY with AFTER/BEFORE add only if x found.
IFNEW add line only if not already there (default)
ALWAYS always add line (even if already there)
COPY "n" add line[s] until there are n lines exist. n maybe zero. Extra existing lines will be deleted. The options ENV and KEY also operate on n. If n is not a number then it is treated as zero.
*ID target line identification anywhere in the line.
ENV ["x"] line and COPY n in these lines may contains environment variables. Optional x, default "%", defines delimit character
KEY ["x"] line and COPY n in these lines may contains keywords from commmand line option KEY. Optional x, default "#", defines delimit character
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.
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.
Parameter ADDSTRING string IN lineid [(Options]
AS string IN lineid [(Options]
string is the string to be added to the target line. Note that last character is interpreted as a string separator character.
lineid identifies the target line.
Options [AFTER|BEFORE] [FROM] [TO] [INIT] [NOTERM] [IFNEW|ALWAYS] [ALL|FIRST|LAST] [*ID] [ENV] [KEY] [ADDTOP|ADDBOTTOM]
AFTER ["x"] if string not found then add string after x. If x is not given then add to end of the line.
BEFORE ["x"] if string not found then add string before x. If x is not given then add just after lineid.
FROM ["x"] the begining of target string is delimited by x in target line. EG. for a function foo() 'as "0," in "foo" (noterm from "(" to ")"'.
TO ["x"] the end of target string is delimited by x in target line. EG. for a function foo() 'as "0," in "foo" (noterm from "(" to ")"'.
INIT the begining of the target string is terminated with a character separator
NOTERM the end of the target string is not terminated with a character separator
ALL add to all occurrences of lineid (default)
FIRST add only to 1st occurrence of lineid
LAST add only to last occurrence 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.
ENV ["x"] string in this line contains environment variables. Optional x, default "%", defines delimit character
KEY ["x"] string in this line contains keywords from commmand line option KEY. Optional x, default "#", defines delimit character
ADDTOP if lineid not found, adds a new line at the top of the Target File.
ADDBOTTOM if lineid not found, adds a new line at the bottom of the Target File.
COMMENTLINE Comment out a line in Target File. In fact, places a user-specified character string at the beginning of a line.
Parameter COMMENTLINE lineid WITH type [(options]
CL lineid WITH type [(options]
lineid identifies the target line.
type representing comment character(s)
Options [ALL|FIRST|LAST] [*ID] [IF|IFNOT]
ALL comment all occurrences of lineid (default)
FIRST only comments 1st occurrence of lineid
LAST only comments last occurrence 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.
DELLINE Delete a given LINE from Target File.
Parameter DELLINE lineid [(options]
DL lineid [(options]
lineid identifies the target line.
Options [ALL|FIRST|LAST] [*ID] [ENV] [KEY] [IF|IFNOT]
ALL deletes all occurrences of lineid (default)
FIRST only deletes 1st occurrence of lineid
LAST only deletes last occurrence of lineid
*ID target line identification anywhere in the line.
ENV ["x"] lineid in this line contains environment variables. Optional x, default "%", defines delimit character
KEY ["x"] lineid in this line contains keywords from commmand line option KEY. Optional x, default "#", defines delimit character
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.
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 occurrences of the string in a given line are deleted.
Parameter DELSTRING string [IN lineid] [(Options]
DS string [IN lineid] [(Options]
string representing the string to be deleted.
lineid identifies the target line. Optional
Options [NOTERM] [ALL|FIRST|LAST] [*ID] [ENV] [KEY]
NOTERM the end of the line is not terminated with a character separator
ALL deletes in all occurrences of lineid (default)
FIRST deletes only in 1st occurrence of lineid
LAST deletes only in last occurrence of lineid
*ID target line identification anywhere in the line.
ENV ["x"] string in this line contains environment variables. Optional x, default "%", defines delimit character
KEY ["x"] string in this line contains keywords from commmand line option KEY. Optional x, default "#", defines delimit character
REPLINE Replace an entire LINE of Target File with a new text. The 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.
Parameter REPLINE lineid WITH replacement [(options]
RL lineid WITH replacement [(options]
lineid identifies the target line.
replacement representing the new line
Options [ALL|FIRST|LAST] [ADDTOP|ADDBOTTOM|DONTADD] [*ID] [ENV] [KEY] [IF|IFNOT]
ALL replaces ALL occurrences of lineid (default)
FIRST only replaces 1st occurrence of lineid
LAST only replaces last occurrence of lineid
ADDTOP if lineid not found, adds a new line at the top of the Target File.
ADDBOTTOM if lineid not found, adds a new line at the bottom of the Target File.
DONTADD if no lineid, don't add replacement (default)
*ID target line identification anywhere in the line.
ENV ["x"] replacement in this line contains environment variables. Optional x, default "%", defines delimit character
KEY ["x"] replacement in this line contains keywords from commmand line option KEY. Optional x, default "#", defines delimit character
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.
REPSTRING Replace a given string by another, within a given line of Target File. If no line is specified (lineid) then all occurrences of string within Target File will be replaced with the new string. All occurrences of the string in a given line are replaced.
Parameter REPSTRING ostring WITH nstring [IN lineid] [(Options]
RS ostring WITH nstring [IN lineid] [(Options]
ostring representing the string to be replaced.
nstring representing the new string
lineid identifies the target line. Optional.
Options [ALL|FIRST|LAST] [*ID] [ENV] [KEY]
ALL replaces in all occurrences of lineid (default)
FIRST replaces only in 1st occurrence of lineid
LAST replaces only in last occurrence of lineid
*ID target line identification anywhere in the line.
ENV ["x"] nstring in this line contains environment variables. Optional x, default "%", defines delimit character
KEY ["x"] nstring in this line contains keywords from commmand line option KEY. Optional x, default "#", defines delimit character

Examples:

ONERROR CONTINUE

continue processing even in case of error(s)

REPline "COUNTRY=" with "COUNTRY=001,C:\OS2\SYSTEM\COUNTRY.SYS" (ADDBOTTOM

replaces all occurrences of lines starting with "COUNTRY=" adds new line at bottom of Target File if no line starting with "COUNTRY=" exists. "C:\" will be replaced with actual boot root directory.

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 . "C:\" will be replaced with actual boot root directory.

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=". "C:\" will be replaced with actual boot root directory.

addstring "c:\mybin;" in "path=" (after

adds "c:\mybin;", if it doesn't already exist, within the line starting with "path=". Note that the file seperator character is optional at the end of line and sometimes missing. The default is to terminate the line. Both ADDSTRING and DELETESTRING deal intelligently with this.

deletestring "warpcenter," in "set autostart=" (noterm

deletes "warpcenter" string from "set autostart=" line if found. Note that the string seperator character is not at the end of line. Both ADDSTRING and DELETESTRING deal intelligently with this. Remove "," from end of line if there is one.

as "/V " in "BASEDEV=USB" (after init noterm 

appends a verbose switch to all USB base drivers and making shure the first parameter has initial space and the last parameter has no terminating space. Nothing happens to a line if switch is already present in that line.

ONERROR CONTINUE
RL "SET VALUES=" WITH "SET VALUES=%indirect%" (ADDBOTTOM ENV

assuming that the command 'SET INDIRECT=3' has been executed prior to CUBE execution, if line "SET VALUES=" exits then replace line with "SET VALUES=3" else adds line to target bottom. If no environment variable found then displays an error message and continues with next command.

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 occurrences of "D:\TOOLKT13" with "D:\TK13".

AL "USER=#name#,NODE=#node#" (AFTER IFNEW key

assuming CUBE has been invoked with option (KEY "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.

al !SET MYNAME="#name#"! (key

assuming CUBE has been invoked with option (key "name #John Smith#", will add a line SET MYNAME="John Smith".

lineid profile
COMMENT BEGIN ";"
REPLINE " COMPUTERNAME =" WITH " COMPUTERNAME = %hostname% (env"

a COMPUTERNAME but must have at least one leading space in target. The with string is still the exact replacement. Any lines beginning with a semi-colon are ignored. This example for C:\ibmlan\ibmlan.ini as target.

For more examples