Studio RM - Tutorial MACROS

Studio RM - MACROS
Tutorial para Macros

CONTENIDO
COMANDOS PARA MACROS ----------------------------------------------------------------- 1
BACKTO ----------------------------------------------------------------------------------- 3
ECHO ------------------------------------------------------------------------------------- 5
END -------------------------------------------------------------------------------------- 6
FIELD ------------------------------------------------------------------------------------- 7
FILE ------------------------------------------------------------------------------------- 10
GOSUB ----------------------------------------------------------------------------------- 12
GOTO ------------------------------------------------------------------------------------ 14
HOLD ------------------------------------------------------------------------------------ 17
IF ------------------------------------------------------------------------------------- 18
INCLUDE ------------------------------------------------------------------------------- 23
KBOFF --------------------------------------------------------------------------------- 27
KBON ---------------------------------------------------------------------------------- 28
LET ------------------------------------------------------------------------------------ 29
LOADCF -------------------------------------------------------------------------------- 37
MACEND ------------------------------------------------------------------------------- 42
MACST --------------------------------------------------------------------------------- 43
MDEBUG ------------------------------------------------------------------------------- 45
MENU ---------------------------------------------------------------------------------- 49
NOHOLD ------------------------------------------------------------------------------- 52
NOMENU ------------------------------------------------------------------------------- 53
NORUN -------------------------------------------------------------------------------- 55
NOXRUN ------------------------------------------------------------------------------- 58
ONERR --------------------------------------------------------------------------------- 62
PICDIR -------------------------------------------------------------------------------- 64
PICFLD -------------------------------------------------------------------------------- 69
PICREC -------------------------------------------------------------------------------- 72
PROMPT ------------------------------------------------------------------------------- 77
REM ----------------------------------------------------------------------------------- 86
RETURN -------------------------------------------------------------------------------- 87
RUN ----------------------------------------------------------------------------------- 88
SCROFF -------------------------------------------------------------------------------- 93
DMCH S. A.–MACROS-ENT-0001-1.00 Índice de contenido 2

SCRON --------------------------------------------------------------------------------- 94
START --------------------------------------------------------------------------------- 95
STKPAR -------------------------------------------------------------------------------- 96
STKSAV -------------------------------------------------------------------------------- 97
SYSFILE ------------------------------------------------------------------------------- 98
VARINIT ------------------------------------------------------------------------------- 99
VARLOAD ---------------------------------------------------------------------------- 100
VARSAVE----------------------------------------------------------------------------- 101
XRUN -------------------------------------------------------------------------------- 102
DMCH S. A.–MACROS-ENT-0001-1.00 Índice de contenido 3

COMANDOS PARA MACROS
MACRO/MENU PROCESSES WITHIN STUDIO RM

BACKTO Unconditionally branches to a specified screen name or label.
ECHO Display a single line of text from within a macro.
END Ends a macro or menu within a macro library.
FIELD Sets up substitution variables to the values of fields in a file, for a
particular record. Default values may also be found.
FILE Finds existence of a database file, and sets number of records.
GOSUB Stores the current macro position and branches to a specified
command label within a macro or menu.
GOTO Unconditionally branches to a specified command label within a macro
or menu.
HOLD Prevents exit from a macro or menu if a DATAMINE fatal error occurs.
IF Conditionally branches to a specified command label within a macro or
menu.
INCLUDE Enables records from a DATABASE file to be included as normal data
and/or statement lines within a Macro or Menu.
KBOFF Takes prompted files, fields, parameters or data from the macro or
menu file.
KBON Takes prompted files, fields, parameters or data from the keyboard,
not the macro or menu file.
LET Sets values of substitution variables. Arithmetic and functions are
provided.
LOADCF Loads a character-format system menu file into a named random
access menufile for execution.
MACEND Terminates the routing of interactive input to a character-format
system macro file.
MACST Starts the routing of interactive input to a character-format system
macro file.
MDEBUG Interactive source code debugger for the development and testing of
macros and menus.
DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 1

MENU Executes a menu previously loaded into a named random access
menufile by LOADCF.
NOHOLD Allows exit from a macro or menu if a DATAMINE fatal error occurs.
NOMENU Validates the syntax of a menu previously loaded into a named random
access menufile by LOADCF.
NORUN Validates the syntax of a macro or menu in a database file.
NOXRUN Validates the syntax of a macro or menu in a character-format system
file.
ONERR Transfers control to a given label if a DATAMINE fatal error occurs.
PICDIR Select file names from the database directory using pattern matching.
PICFLD Select field names from a file using pattern matching.
PICREC Select records from a file using relational or pattern matching
expressions.
PROMPT Displays lines on screen and prompts for input.
REM Allows comments to be put anywhere in a macro or menu.
RETURN Transfers control back to the next statement following the GOSUB.
RUN Starts execution of a macro or menu in a database file.
SCROFF Diverts text screen output into a system file during macro execution.
SCRON In a macro or menu, restores screen output previously diverted by a
!SCROFF command.
START Names a macro or menu in a library.
STKPAR Reads substitution variables from a file.
STKSAV Saves substitution variables to a file.
SYSFILE Checks if a system file exists.
VARINT Initialises the number of substitution variables to zero for the current
macro level.
VARLOAD Reads substitution variables from a file.
VARSAVE Saves or merges substitution variables into a file.
XRUN Starts execution of a macro or menu in a character- format system file.

BACKTO
Introduction
Unconditionally branches to the named !SCREEN command and starts
executing it. The general format is:
!BACKTO <SCREEN NAME>
where <SCREEN NAME> is a string of up to sixteen character in length which
has been defined using the NAME: command within !SCREEN. It must be
present in the current macro/menu or an error will result.
Any previously executed !SCREEN command that contained a name can be
used as the target, as long as the macro or menu that contained the named
!SCREEN is currently active.
If the name is not a known screen name in the list of screens traversed in
the current terminal session, the name is treated as a local macro label, and
a GOTO is attempted.
Process Summary
BACKTO This macro command will make the macro system jump back to
the named !SCREEN command and start executing it.
Error and Warning Messages
None
Notes
If <SCREEN NAME> does not exist as either a screen name or as a label,
then the action taken is according to the current !ONERR setting.

Example
!Plot:rem
!SCREEN
NAME:Plot_param
(further processing)
!BACKTO:Plot
!BACKTO:Plot_param

ECHO
Introduction
Displays on the screen a single line of text from within a macro.
Process Summary
ECHO Display a single line of text from within a macro.
Echo outputs any text supplied on the current macro line to the
screen. Echo ignores any !SCRON/!SCROFF screen re-direction
that may be active. The displayed text line always begins with a
space. For a blank output line, supply no text. Substitution in
the line is permitted, variables placed in single quotes will not
be substituted.
Example
A typical macro fragment:
!LET $msg='A flavour enhancer'
!LET $time=ENV(time)
!ECHO At $time, the value of '$msg' is "$msg"
… gives screen display:
At 14:30:35, the value of '$msg' is "A flavour enhancer"

END
Introduction
Ends a macro or menu. When the END command is processed, execution of
the menu or macro stops. This will return control to the keyboard, unless the
macro is called from a higher macro or menu, in which case control will
revert to the higher macro. Outside a macro END is illegal.
Process Summary
END Ends a macro or menu within a macro library.
Example
!END

FIELD
Introduction
Detects the existence of a database file and sets up substitution variables to
the values of fields in the file, for a particular record. Default values of fields
may also be found. The format is:-
!FIELD <var1>=<filename>,<var2>=N,<var3>=<field1>,<var4>..
where <var1> is a substitution variable.
<filename> is the name of the database file.
N is the number of the record in the
database file.
<var2> is a second substitution variable.
<var3> is a third substitution variable.
and so on.
The command may extend over more than one line by ending the previous
line with a comma.
The variable <var1> will be set to 0 if the file does not exist, or there is a file
read error, or the file has no read access, or if any of the specified fields do
not exist. If the file exists, the DD can be read, read permission is granted,
and all fields exist, <var1> becomes 1.
The variable <var2> should be set to the value of the particular record
required. A value of 0 will give field default values, while + or a value greater
than the maximum number of records in the file will give the last record in
the file.
<var2> is set to the maximum number of records in the file or 0 if the
database file does not exist.
<var3> is set to the value of <field1> in record N.
<var4> is set to the value of <field2> in record N.
and so on.

Process Summary
FIELD FIELD sets values of substitution variables based on the
value(s) of one or more nominated fields within a given record
of a database file.
Format: ! field <var1>=<file>,<var2>=<record>,
<varA>=<fieldA>,<varB>=<fieldB>,...
Supplied Values:
"<file>,<record>,<fieldA>" may be supplied either as constants
or substitution variables. These values specify what is to be
read by FIELD.
<file> Nominates the database file to read.
<record> Specifies the index of the record to read from the
start of <file>. '0' will return the default values
from the data definition. '+' or >maximum records
will return the values from the last record in
<file>.
<fieldA> Nominates the name of the field to examine.
Substitution variables will be set based on the value found in
<fieldA>, and the state of the file <file>.
Returned Values:
"<var1>,<var2>,<varA>" must be supplied as substitution
variables, and are SET to special values on completion of the
FIELD command.
<var1> is set to 1 if <file> exists, 0 = does not exist.
<var2> is set to the total number of records in <file>. If <file>
does not exist, <var2> is set to 0.
<varA> Is set to the value of <fieldA> in record number
<record> from the start of <file>. If <file> does not exist, or
<fieldA> does not exist in <file>, then <varA> is unchanged.
Multiple pairs in the form <varA>=<fieldA>,
<varB>=<fieldB>,... can be supplied to extract more than one
value in a single field call. The list may be extended onto as
many lines as necessary; continuation is implied by ending the
previous line with a comma.

>>> !FIELD: ILLEGAL FORMAT <<<
>>> ERR 90 <<< (0) IN SOFFIE
<listing of command line>
The command is malformed. Fatal; the macro or menu is cancelled.
Notes
A message will be sent to the display if the file does not exist, or read
permission is denied, or there is a read error or any of the specified fields do
not exist.
Examples
1. Find the hole name of the 1000th sample in an assay file. The variable
"$hole#" is used to return this value; "$exists#" will be set to 1 if the
file ASSAYS is found; "$records#" will be set to the total number of
samples in the file.
!FIELD $exists#=ASSAYS,$records#=1000,$hole#=BHID
2. Extract the data area limits (mm) from a plot file. These values are
usually stored as implicit fields in the plot file header.
!FIELD $found#=PLOT.P,$recs#=0,
$xorig#=XORIG, $yorig#=YORIG,
$xrt#=XRT, $ytp#=YTP

FILE
Introduction
Detects the existence of a database file from within a menu or macro, and,
optionally, the number of records in the file. The format is:-
!FILE <var1>=<filename>,<var2>=recs
where <var1> is a substitution variable.
<filename> is the name of the database file.
<var2> is a second substitution variable.
Note that the name recs is not checked; any name following the = is
permitted. The structure is defined for consistency, and to allow future
extension of the format.
The variable <var1> will be set to 0 if the file does not exist, or there is a file
read error, or the file has no read access for the current usercode. If the file
exists, the DD can be read, and read permission is granted, <var1> becomes
1.
The optional variable <var2> will be set to the number of records in the file.
This will be zero if <var1> is zero.
Process Summary
FILE Finds if database file exists, sets number of records.
Format: !file <var1>=<filename>,<var2>=recs
where <var1> and <var2> are substitution variables.
,<var2>=recs is optional.
If <filename> exists/does not exist, <var1> is set to 1/0.
<var2> is set to the maximum no. of records in the file.

Errors
>>> !FILE: SUBSTITUTION VARIABLE OR FILE NAME OR RECS MISSING OR
>8 CHARACTERS <<<
>>> ERR 89 <<< (0) IN MACGET
The command is malformed. Fatal; the macro or menu is cancelled.
Notes
A message will be sent to the display if the file does not exist, read
permission is denied, or there is a read error.
Example
!FILE $EXIST=COLLARS,$RECS=RECS

GOSUB
Introduction
Stores the current macro position and branches to a specified command label
within a macro or menu.
Process Summary
Stores the current macro position and branches to a specified command label
within a macro or menu.
Usage: GOSUB <LABEL NAME>
A subroutine is any portion of a macro or menu that:-
1. Begins on a label line !<LABEL NAME>:
2. Ends with a !RETURN statement.
The label may consist of up to 16 characters, and must be present in the
current macro/menu or an error will result. Labels are denoted by using the
special char ":" (colon) as in the macro line below:-
!MYLABEL:REM -- this line specifies the label "MYLABEL"
When an executing macro or menu encounters a GOSUB statement, it saves
the current line number and then branches to the specified label. Execution
continues normally until a RETURN statement is executed, at which point the
macro or menu jumps back and resumes execution at the line after the
GOSUB statement.
Execution of a RETURN statement without a corresponding GOSUB will give
an error. For nested macros, the RETURN statement must be in the same
macro or menu as the corresponding GOSUB statement. Up to sixteen
RETURN's may be pending at any time within the currently executing macro
or menu.

Example
The following macro fragment will divert macro processing to the label
"PLOT_INIT". When "!RETURN" is encountered, control will be diverted to the
next line after "!GOSUB"
!GOSUB PLOT_INIT
!PLOT_INIT:REM - Subroutine: clean plot ---
!RETURN
See also: RETURN, GOTO, IF.

GOTO
Introduction
Branches unconditionally within a menu or macro to the given label. Outside
a menu or macro GOTO is illegal. The general format is:-
!GOTO <LABEL>
where <LABEL> is an up to sixteen character label preceding a command
within the same menu or macro in which the GOTO command appears.
Upper and lower case labels are treated separately; for example, aaaa and
AAAA are different labels. The !START command may not be the target of a
!GOTO.
Labels within the GOTO command may be modified by substitution strings;
for example:
!GOTO a$1
may be entered, where $1 is defined by the !PROMPT (or RUN) command.
Process Summary
GOTO Unconditionally branches to a specified command label within a
macro or menu.
Usage: GOTO <LABEL NAME>
The label may consist of up to 16 characters, and must be
present in the current macro/menu or an error will result.
Labels are denoted by using the special char ":" (colon) as in
the macro line below:-
!MYLABEL: REM -- this line specifies the label "MYLABEL"
@FLAG5* =-1 do not execute the GOTO statement within a macro or
menu. This is used by the NORUN, NOMENU and NOXRUN
processes.
>>> INCORRECT LABEL XXXX IN GOTOXXXX OR XXXX NOT FOUND <<<
>>> ERR 75 <<< (recordno) IN MACGET
Either the label was too long (>16 characters), or the label was not
present in the macro or menu.

Notes
All labels within a menu or macro are read by the RUN subroutine and
placed, together with the line numbers in the macro or menu in which they
occur, into the stack file prior to processing. Thus labels may not be modified
by use of substitution strings.
Example
The following macro fragment will force macro processing to ignore all
commands until the label "PLOT_INIT".
!GOTO PLOT_INIT
!PLOT_INIT:REM --- plot startup commands ---

HOLD
Introduction
Prevents exit from a menu or macro if a DATAMINE fatal error occurs. Under
these circumstances the current command in the menu or macro is
terminated, and the next one executed. This also applies to processes
executed by entering them directly as a command during a prompt from the
!PROMPT command. Note however that ! entered in response to a prompt
will still terminate the macro or menu, even if !HOLD has been specified.
Such a response must be trapped by the user to prevent exit under these
circumstances.
Once the !HOLD command has been given, it remains in force until the
!NOHOLD command (q.v.) is executed. Note that !NOHOLD is the default at
entry to a macro or menu.
The flag @FLAG3 is set to 1 to indicate that the !HOLD condition is in force.
Process Summary
HOLD Stops exit from macro or menu on DATAMINE fatal error.
Example
!HOLD

IF
Introduction
Branches conditionally within a macro or menu to the given label. Outside a
macro or menu IF is illegal.
Process Summary
IF Evaluates one or more logical expressions involving
substitution variables and constants in a macro or menu. There
are two categories of IF command - "SIMPLE" and "BLOCKED".
1. SIMPLE IF COMMAND
Format: !IF <CONDITION>,...,GOTO XXXX
or !IF <CONDITION>,...,GOSUB XXXX
or !IF <CONDITION>,...,LET <EXPR>
A series of comma separated conditions may be supplied. If
all conditions evaluate to "true", an attached GOTO, GOSUB
or LET statement is executed.
<CONDITION> can be one of either: <VAR1> <OP>
<VAR2>
or: <LVAR>
<VAR1> is a substitution variable, or one of @FLAG1 to
@FLAG5.
<VAR2> is a substitution variable or a constant.
<OP> is an operator from the set "<", "<=",
"=", ">=", ">" or "<>". The last of these
means "not equal to".
<LVAR> is a "logical" variable. The expression is "false"
if <LVAR> = 0 or 0.0, and "true" for all other
values. Note: All alpha values evaluate as
"true"
XXXX is a 16 character label in the macro or
menu.
<EXPR> is any valid expression recognised by the LET
command.

If <VAR1> and <VAR2> are numeric they are compared as
numbers. Otherwise they are compared character by
character using the DATAMINE collating sequence. Variables
and values may be enclosed in single quotes ' to preserve
spaces.
Substitution variables must be defined for comparison, a
macro error results if comparison is attempted on undefined
variables.
2. BLOCKED IF COMMAND
Format: !IF <CONDITION>,...,THEN
statement(s)
!ELSEIF <CONDITION>,...,THEN
statement(s)
!ELSEIF <CONDITION>,...,THEN
statement(s)
!ELSE
statement(s)
!ENDIF
The "blocked" IF statement is an extension of the simple IF
statement. Each <CONDITION> line is evaluated in turn.
The block of statements associated with the FIRST
<CONDITION> line to evaluate "true" is executed. Once
this block is finished, control passes to the first statement
after the !ENDIF.
. <CONDITION>s are specified in the same way as for
"simple" IF statements.
. Zero or more !ELSEIF...,THEN branches may be
supplied.
. An optional !ELSE branch may be supplied. This is
executed only when all preceeding branches fail.
. !ENDIF MUST be supplied to terminate the "block".
. IF blocks may be nested.

. It is legal to GOSUB from within a branch. The branch
will be "pending", and control will resume with the
!RETURN.
. It is illegal to GOSUB or GOTO a label contained within
an IF statement block either from outside the whole IF
block, or to a label within a different or deeper branch
of the whole block.

>>> !IF: TEST ON NON-EXISTENT SUBSTITUTION VARIABLE OR FLAG <<<
>>> ERR 80 <<< (0) IN SOFTIF
The substitution variable was not defined, or the flag was not one of the
set @FLAG1-5. Fatal; the macro or menu is abandoned.
>>> !IF: SUBSTITUTION VARIABLE aaaaaaaa NOT FOUND <<<
>>> ERR 87 <<< (0) IN SOFTIF
The substitution variable aaaaaaaaa was not found. Fatal; the macro or
menu is abandoned.
>>> !IF: SUBSTITUTION VARIABLE BLANK OR >8 CHARACTERS <<<
>>> ERR 88 <<< (0) IN SOFTIF
Illegal format for substitution variable. Fatal; the macro or menu is
abandoned.
>>> !IF: NO GOTOXXXX COMMAND <<<
>>> ERR 74 <<< (0) IN SOFTIF
No GOTO command was found. Fatal; the macro or menu is abandoned.
Either the label (displayed below the message) was too long (>4
characters) or was not found in the menu or macro. Fatal; the menu or
macro is abandoned. Recordno is the record number in the menu or
macro (from !START).
Notes
Because testing is abandoned if any individual test fails, then syntax errors
further to the right in the line (such as an illegal label) will not be picked up
unless all tests pass.

During character tests, blanks will be stripped out from the <val1> string
unless it is enclosed in quotes. This is true even if <val1> is a second
substitution variable. If in doubt, enclose <val1> in quotes.
Examples
1. GOTO the label "END" if variable $1 contains the numeric value '3' (eg 3,
3.0 etc) AND if variable $2 is NOT set to the string "Xyz Project".
Capitals are significant for string comparison.
!IF $1 = 3, $2 <> 'Xyz Project', GOTO END
2. Check the variable "$value#" and initialise it to the string "New Value" if
it has not already been defined. Note the use of single quotes.
!LET $test#=$value#
!IF $test#='$value''#',LET $value#='New Value'
3. This example will delete file DRILL.M if it exists. A message is also
displayed.
!FILE $exists#=DRILL.M,$recs#=recs
!IF $exists#,THEN
!DELETE &IN(DRILL.M)
!ECHO File DRILL.M deleted.
!ENDIF
4. Classify a plot as either A4,A3 or A0 depending on the plot dimensions
$min#,$max#. Indentation may be used to make the branching clearer.
!IF $min#>0,$min#<=210, $max#<=297,THEN
!LET $media#='A4'
!ELSEIF $min#<=297, $max#<=420,THEN
!LET $media#='A3'
!ELSEIF $min#<=841, $max#<=1189,THEN
!LET $media#='A0'
!ELSE
!LET $media#='Plot size error.'
!ENDIF

INCLUDE
Introduction
Allows records from a database file to be included as data and/or
statement lines in a macro or menu.
Process Summary
INCLUDE The "!INCLUDE" soft command enables records from a database
file to be incorporated as normal data and/or statement lines
within a DATAMINE macro or menu. When encountered at
runtime, the !INCLUDE command is replaced with one or more
records from the nominated file.
Format: !INCLUDE &FILE(file),*TEXT(textfld),
*KEY(keyfld), @VALUE='keyval'
&FILE(file) Specifies the database file to read, and must be supplied.
*TEXT(textfld) Is optional, and specifies the name of the field within &FILE
to use.
The default is 'TEXT'.
*KEY(keyfld),@VALUE='keyval' Are also optional. Taken together they
permit selection of a subset of records
from &FILE. Keyval is specified as a
quoted ('') string.
The statement may be extended onto as many lines as necessary;
continuation is implied by ending the previous line with a comma. !INCLUDE
commands can be nested. These are expanded as encountered, and placed
in a buffer for inclusion in the macro. The !INCLUDE command is discarded if
no (matching) lines are found in &FILE. It is illegal to supply additional
data/text on the !INCLUDE statement line.
The line(s) returned from &FILE must be valid data and/or command lines for
the macro/menu being executed. Blank lines in &FILE are honoured, and
passed on for macro processing. Substitution variables are permitted, both in
the statement itself and within the lines returned from the file.
The following restrictions should be noted:
1. Records from &FILE are stored in a buffer. Each line in the buffer is
processed in turn. When all lines have been processed, normal macro
execution resumes on the next line after the !INCLUDE call.

If control soft-commands (GOTO, GOSUB etc) are part of the included
text, all remaining commands in the buffer WILL STILL BE EXECUTED.
Control will be transferred to the target label ONLY when the buffer is
empty and normal processing resumes.
Macro Labels in !INCLUDEd text are ignored. For these reasons, it is
recommended that control commands are NOT supplied in include files.
2. Multi-line soft commands cannot be used in !INCLUDE files for the
current implementation i.e. FIELD, VARLOAD, VARSAVE are restricted to
single line commands, and PROMPT cannot be used.
Examples
Example macro fragments:
1. Create and use a standard set of test criteria to list all plotfiles with the
PICDIR process. All records in the file 'PLOTSPEC', field 'TEXT' will be
supplied as TEST> criteria to PICDIR.
!INPFIL &OUT(PLOTSPEC) # create the file
Database file containing test for plotfiles
TEXT A 72 Y ' '
]
ok
# no system file
(FILE *.P OR FILE ???????P) END
!PICDIR &OUT(PLOTLIST)
!INCLUDE &FILE(PLOTSPEC)
2. Incorporate one of a standard library of equations in a GENTRA routine.
The file FORMULAE contains various assay cut formulae, which are keyed
on the field ASSAYCUT. The required equation has the key value
AU10CUT.
!LET $value#='AU10CUT'
!GENTRA &IN(SAMPLES),&OUT(CUTASSAY)
!INCLUDE &FILE(FORMULAE),*TEXT(TEXT),
*KEY(ASSAYCUT),@VALUE='$value#'
END
OK

!LIST &IN(CUTASSAY)

KBOFF
Introduction
Causes the response to prompted information to be read from the macro file.
This is the default method of operation, in force when a macro or menu is
entered. The !KBOFF condition is set when it is required to use macros as
pseudo batch runs, in which all files, fields and parameters are satisfied in
the command line, and all data read by the process is contained in the
macro.
The !PROMPT command executes an implicit !KBOFF command whenever it is
entered; however the !PROMPT command itself always expects responses to
come from the keyboard.
The !RUN, !XRUN and !MENU processes also execute an implicit !KBOFF
command when they are entered. This is because the default condition at the
start of a menu or macro is !KBOFF. Upon return from a macro the state
(!KBOFF or !KBON) returned will be that established at the end of the called
macro.
The system flag @FLAG4 is set to 0 to indicate the !KBOFF condition. The
!KBON command (q.v) which is the opposite of !KBOFF, causing all data to
be read from the keyboard, sets @FLAG4 to 1.
Process Summary
KBOFF Take prompted information from the macro or menu file.
Example
!KBOFF

KBON
Introduction
Causes the response to prompted information to be read from the keyboard
in place of the macro file. The !KBON condition is set when it is required to
force prompting for files, fields and parameters and data required by a
process to be satisfied from the keyboard, while control is retained inside a
macro or menu.
The !KBON condition is retained in force until a !KBOFF command is
executed, or the !PROMPT command is executed, which carries out an
implicit !KBOFF. Note that the !MENU, !RUN and !XRUN processes also carry
out any implicit !KBOFF. Thus upon return from a macro the state (!KBON or
!KBOFF) returned will be that established at the end of the called macro.
The system flag @FLAG4 is set to 1 to indicate the !KBON condition. The
!KBOFF command (q.v) which is the opposite of !KBON, causing all data to
be read from the macro or menu, sets @FLAG4 to 0.
Process Summary
KBON Take prompted information from the keyboard.
Example
!KBON

LET
Introduction
Sets the value of a substitution variable.
The form of the command is:-
!LET <var>=<constant>
!LET <var>=<expression>
!LET <var>=<var1>
!LET <var>=<var1><op><var2>
!LET <var>=<constant1><op><var2>
!LET <var>=<var1><op><constant2>
!LET <var>=<constant1><op><constant2>
!LET <var>=<func1>(<var2>)
!LET <var>=<func1>(<constant1>)
!LET <var>=<func2>(<var2>,<var3>)
!LET <var>=<func2>(<constant1>,<var3>)
!LET <var>=<func2>(<var2>,<constant2>)
!LET <var>=<func2>(<constant1>,<constant2>)
where <var> is a substitution variable.
<constant> is either a number in DATAMINE format or a
character string.
<expression> is a mathematical expression which will be
evaluated using DATAMINE's expression parser.
<var1> is a substitution variable.
<op> is an arithmetic operator from the set
+ - * or /.
<var2> is a substitution variable with a numeric
value.
<constant1> is a numeric constant.
<constant2> is a numeric constant.

<func1> is a single argument function from the set SQRT,
EXP, LOG, LOGE, LOGN, INT, SIN, COS, TAN,
ASIN, ACOS, ATAN, ABS. Functions may be in
upper or lower case.
<var3> is a substitution variable with a numeric
value.
<func2> is a two argument function from the set MOD,
RAIS, MAX, MIN. Functions may be in upper or
lower case.
Numeric values must be in DATAMINE format, i.e. they must be of form
12, -12, +45.3, -0.00001, 1.56E3, 0.25E-12, or one of the special formats
DL, TR, + or -. Blanks are ignored.
Character variables or constants must be enclosed in quotes if they contain
blanks or special characters + - * / (or).
String concatenation may be specified as follows:-
!LET $1=$2$3.p
If $2 is file, $3 is 34, then $1 will be set to file34.p
The assumptions and restrictions on the operators and functions are as
follows:-
All Numeric constants or substitution
variables required which are not + or -.
+ None.
- None.
* None.
/ <var2> or <constant2> must not be zero.
SQRT(A1) A1 must be positive.
EXP(A1) None.
LOG(A1) Log to base 10. A1 > Trace (TR).
LOGN(A1) Log to base e. A1 > Trace (TR).
LOGE(A1) Log to base e. A1 > Trace (TR).
INT(A1) None.
SIN(A1) A1 in degrees.
COS(A1) A1 in degrees.

TAN(A1) A1 in degrees. A1 differs from 90 by at least
Trace (TR).
ASIN(A1) ABS(A1) < 1.0. Returned value in degrees.
ACOS(A1) ABS(A1) < 1.0. Returned value in degrees.
ATAN(A1) Returned value in degrees.
ABS(A1) None.
MOD(A1,A2) Remainder when A1 divided by A2. None.
RAIS(A1,A2) A1 ** A2. A1 <> 0. If A1 < 0, then A2 must be an
integer.
MAX(A1,A2) None.
MIN(A1,A2) None.
Process Summary
LET Sets values of substitution variables.
Arithmetic and functions are provided.
Format: !let <var>=<var1>
!let <var>=<var2><op><var3>
!let <var>=<func1>(<var2>)
!let <var>=<func2>(<var2>,<var3>)
!let <var>=ENV(<str1>[,<var2>])
!let <var>=LENG(<str1>)
!let <var>=INDX(<str1>,<str2>)
!let <var>=SUBS(<str1>,<var1>,[<var2>])
!let <var>=UPC(<str1>)
where <var> is a substitution variable.
<var1> is a substitution variable or a
constant.
<op> is an arithmetic operator + - * /.
<var2> is a numeric substitution variable or
a constant.
<var3> is a numeric substitution variable or
a constant.

<func1> is a function from the set SQRT, EXP, LOG,
LOGE, LOGN, INT, SIN, COS, TAN, ASIN,
ACOS, ATAN, ABS.
<func2> is a function from the set MOD, RAIS,
MAX, MIN.
<str1> is a string substitution variable or
constant.
<str2> is a string substitution variable or
constant.
If <str1> or <str2> contain embedded blanks which
must be preserved, the variable or constant should be
enclosed in (single) quotes.
ENV provides access to
environment variables.
<str1> is the name of an environment
variable.
If <var2> is included, it should specify
which value (1..N) of the environment
variable is required; if omitted, the first
value is returned.
LENG returns the length of the character
string <str1>, i.e. the number of
characters up to the first trailing blank.
INDX returns an integer, representing the
starting position within <str1> of a
substring identical to <str2>. If <str2>
occurs more than once, the position of the
first match is returned. If <str2> does not
occur within <str1>, INDX returns zero
(0).
SUBS returns a substring of <str1> that
begins at character position <var1> and is
at most <var2> characters long. If
<var2> is omitted, the remainder of the
string is assumed.

UPC returns its argument with all
lower case letters converted to their upper
case equivalents.

>>> !LET: SUBSTITUTION VARIABLE >8 CHARS <<<
>>> ERR 82 <<< (0) IN SOFLET
Illegal variable name. Fatal; the macro or menu is terminated.
>>> !LET: NUMERIC OPERATION ATTEMPTED ON NON-NUMERIC STRING
<<<
>>> ERR 83 <<< (0) IN SOFLET
Either a variable, or a constant for arithmetic or passed as a function
argument, is non-numeric. Fatal; the macro or menu is terminated.
>>> !LET: ILLEGAL VALUES FOR ARITHMETIC <<<
>>> OR ATTEMPT TO DIVIDE BY ZERO <<<
>>> ERR 84 <<< (0) IN SOFLET
One or more of the above conditions on arithmetic or functions was not
met. Fatal; the macro or menu is terminated.
>>> !LET: ILLEGAL FORMAT FOR FUNCTION <<<
>>> ERR 91 <<< (0) IN SOFLET
Wrong number of arguments for a function, or brackets missing, or
illegal characters. Fatal; the macro or menu is terminated.
Notes
During assignment of character values, blanks will be stripped from a string
unless it is enclosed in quotes. This is true even if one character variable is
assigned to another (!LET $1=$2, where $2 is a character variable). If in
doubt, enclose the second variable in quotes: e.g. !LET $1='$2'. This format
works correctly for both character and numeric assignments.
If desired, the variable <var> may also be enclosed in quotes. For example,
!LET '$1'='$2'
!LET can be used to assign the value of an environment variable to a
substitution variable. The general form is !LET $1=ENV(NAME[,VALUE])

where NAME is the name of the environment variable and VALUE optionally
specifies which value of the particular environment variable is required.
From Version 3.4.0 of DATAMINE, !LET can also return the length of a
character string, return an integer representing the starting position of a
sub-string within a string, return a sub-string within a string and convert
lower case letters to their upper case equivalents.
Example
!LET $1=23.2
!LET $1={10/5*6.3+SQRT(4+5)} (Expression).
!LET $1=$2
!LET $1='$2'
LET '$1'='$2'
!LET $1=$2a$3 (String concatenation).
!LET $1=$2 - $5
!LET $1=$2/34.26
!LET $1=max($1,23)
!LET $1=sin(12.5)
!LET $1=LOG($3)
!LET $1=MIN(12,$1)
!LET $1=ENV(C_BACKGROUND) (Assigns background colour to $1)
!LET $2=ENV(C_VALUES,8) (Assigns 8th element of colour array to $2)
!let $d=env(directory)
!let $s=subs($dXXXXX,1,5)
!let $s=$sSUB.DAT
Together, the last three examples will construct the name of the subset file
for any directory.

LOADCF
Introduction
The LOADCF process loads a character format system file, as set up for
example by the editor, into a random access system file to be accessed by
the !MENU process. It is used for producing user menu systems.
The character format system file containing the menu should be up to 80
characters wide. It must follow the normal macro conventions.
If there is more than one macro in the file to be loaded, only the first macro
will be loaded.
The user may choose the name of the binary random access menu file to be
created. This may be up to 56 characters long, and may include pathnames.
It must not contain the character '.', except as part of an up to three
character extension. If an extension is given, it will be used; otherwise an
extension of form.MEN will be appended. The following are legal menu
names:-
\datamine\projects\mymenu
mymenu.men
datamine/mymenu.dat
Note that the form of file accepted is system dependent.
If the response to the menu name question is blank<return> or just
<return>, then a name MENUFILE.DAT will be assumed. This is for
compatibility with earlier releases of DATAMINE.
The menu name set up in !LOADCF is the one that must be specified in the
!menu or !nomenu commands.
Process Summary
LOADCF Load character menu file into named binary menu file.
LOADCF pre-processes macros to increase their general runtime
performance. Specific optimisation can be performed for
customised SCREEN based menu applications.
Three levels of processing are available:
LEVEL = 0 Convert the macro file into the standard.STK
and.MEN files.

LEVEL = 1 Optimise the performance for screen based menus
with the following:
a) Pre-process and verify !SCREEN definitions to
create 'tokenised' SCreen Code (.SCC) and
SCreen Text (.SCT) files for the menu.
b) Replace !SCREEN code with references to
relevant entries in.SCC file.
c) Strip !REM and # inline remarks, remove
indentation.
LEVEL = 2 Optimise the performance for both !SCREEN and
general macro processing with the following:
a) All the features from Level 1.
b) Preprocessing and resolving all command line
parameters from the helpfile at LOADCF time.
c) Report any required files, fields or parameters
that are not supplied on the command line.
@PRINT* >=1 display each line of the macro file as loaded.
@ECHO* =1 copy of output to printer (0).
@LEVEL* Level of menu compilation (0).
=0 Standard compilation.
=1 'Optimise' for !SCREEN processing.
=2 'Optimise' for general command processing.
>SYSFILE> Character format menu file. The name may be up to 56
characters long.
>NAME > Name of menu binary file to be created. Up to 56 characters
permitted. If no file extension supplied,.MEN added.
>>> INPUT SYSTEM FILE DOES NOT EXIST <<<
Fatal; the process is exited.
>>> ERROR IN CREATING OUTPUT FILE <<<
There is a system problem in trying to open the output file. Fatal; the
process is exited. If the menu file already exists, it should be deleted
and the process restarted.

Notes
The !LOADCF process deletes the stack file <name>.STK, where <name> is
the requested macro name minus the extension.
Example
!LOADCF
>>> ENTER NAME OF CHARACTER SYSTEM FILE FOR INPUT <<<
SYSFILE>menu.mac
>>> ENTER MENU NAME <<<
NAME >mymenu

MACEND
Introduction
Terminates the storage of interactive input in a character format system file.
The statement !END is first written to the system file and then the file is
closed.
Once the !MACEND command has been given it remains in force until the
!MACST command (q.v.) is executed.
Process Summary
MACEND Ends storing interactive input in system macro file.
STORAGE OF INTERACTIVE INPUT TO MACRO IS NOT ACTIVATED
A !MACST command had not been issued before !MACEND.
Notes
If no errors are detected the message:
STORAGE OF INTERACTIVE INPUT TO MACRO ENDED
is displayed.
Example
!MACEND

MACST
Introduction
Starts the storage of all subsequent interactive input in a character format
system macro file. The macro name may be specified following the MACST
command name. The macro name supplied is then appended to the !START
command and written to the system macro file. If no macro name is
specified in this way, a message is immediately displayed and the user must
supply one interactively in response to a prompt.
Once the !MACST command has been given it remains in force until the
!MACEND command (q.v.) is executed.
A MACST command would look like:-
!MACST macro1
SYSFILE>maclib.dat
Process Summary
MACST Starts storing interactive input in system macro file.
AAAAAAAA The macro name in the system file.
>SYSFILE> Enter name of character format system macro file for storage of
all subsequent interactive input. This file name may be up to 56
characters long and may contain pathnames (if these are
supported by your operating system). A response of !<return>
exits the process.
>>> ERROR READING FROM MACRO SYSTEM FILE ffffffff.fff <<<
An error has been detected in reading from the specified system macro
file. Fatal; the process is exited.
>>> ERROR WRITING TO MACRO SYSTEM FILE ffffffff.fff <<<
An error has been detected in writing !START <macroname> to the
system macro file. Fatal; the process is exited.

Notes
If the macro name is not specified following the MACST command name, the
message:
MACRO NAME NOT SUPPLIED, PLEASE SUPPLY NAME
is displayed, followed by a prompt for the name:
MACRONAME><macroname>.
If no errors are detected the message:
STORAGE OF INTERACTIVE INPUT TO MACRO STARTED
is displayed.
If the system file specified already exists, all subsequent interactive input is
appended to the existing contents of the file. In this way, a number of
macros can be created in a macro library from different interactive sessions.
Example
!MACST M1
SYSFILE>MYMAC1.DAT
STORAGE OF INTERACTIVE INPUT TO MACRO STARTED
!MACEND

MDEBUG
Introduction
Interactive source-code debugger for macros and menus.
Process Summary
Provides an interactive source code debugger for the development and
testing of macros and menus.
The facility provides features similar to that found in a computer language
debugger.
MDEBUG is implemented as a soft command in DATAMINE and can be
accessed in the following ways:
1. At the PROMPT input command by typing !MDEBUG
2. From the SCREEN F3 function key by entering the command MDEBUG
3. As an inline command within a macro or menu
MDEBUG passes control to the macro debugger and displays the current line
number. MDEBUG will display the current line and the action that caused
execution to pause at that line. One of three states will be indicated:
1. A BREAKPOINT has been previously set, and control has paused at a
breakpoint.
2. The STEP command has previously been entered from MDEBUG and the
previously been executed, and control has paused at the next command
line.
3. An inline MDEBUG command has been read from the macro or menu.
MDEBUG permits the execution of the following debug commands.
Commands can be abbreviated (to one character as each command starts
with a unique letter).
ASSIGN <stack variable> <string>
Assign value of <string> to <stack variable>.
<stack variable> need not already exist.
BREAKPOINT <label>
BREAKPOINT <line>
BREAKPOINT

Set breakpoint at <label>, <line> or list all breakpoints currently set.
CLEAR <label>
CLEAR <line>
CLEAR +
Clear breakpoint set at <label>, <line> or all breakpoints currently set.
DELETE <stack variable>
Delete <stack variable>
EXECUTE <command string>
Execute a DATAMINE command. eg. ex list @dict=2
FIND <string>
List all lines in current macro which contain <string>.
HELP
Show these comments.
INFO
Display a summary of the stack file.
LIST
LIST n1 n2
List lines near current position, or lines n1 to n2 of the current macro.
PROCEED
PROCEED <label>
PROCEED <line>
Continue processing from the current line, the line with <label>, or
<line>.
REVIEW
Review commands held on the stack.
STEP

Execute the current command and break at the next at the next
command.
TYPE <stack variable>
TYPE +
TYPE
Show current value of <stack variable>, or all variables.
MDEBUG can be exited with the PROCEED and STEP commands. Entering
! or ENTER is accepted as a PROCEED command.

MENU
Introduction
Initiates the currently established menu. The menu name is requested. This
must be the name of a binary random access menu file loaded by the
!LOADCF command.
!MENU commands should not be nested. A menu may be called from a macro
(!RUN or !XRUN command) or another menu, and a menu may call a macro.
Process Summary
MENU Executes a named menu.
The menu should previously have been loaded into a named
random access menufile by LOADCF.
>NAME > Enter the name of the required menu. The name is one of the
menus loaded by the LOADCF process. The name may be up to
56 characters long and may contain pathnames. The name
should not contain the character '.', except as part of an
optional file extension (.FFF). If there is no extension.MEN will
be appended. If the response is “?”, a help message will be
displayed. If the response is just <return>, the name
MENUFILE.DAT will be used.
>>> MENU FILE DOES NOT EXIST <<<
>>> ERR 78 <<< (0) IN RUN
The menu file either does not exist, or is malformed. Fatal; the process
is exited.
>>> WARNING - MORE THAN 250 SUBSTITUTION VARIABLES <<<
>>> ERR 84 <<< (250) IN UPDSTV
Only 250 variables may be in use at any time. Warning; the excess is
ignored and processing continues.
>>> MACRO NAME NOT FOUND <<<
>>> ERR 72 <<< (0) IN RUN
No !START command was found to introduce the menu. Fatal; the
process is exited.

Notes
On executing the !MENU command for the first time for any menu, there will
be a delay while the menu is scanned and labels etc. entered into the system
stack file. This stack file (of form <name>.STK, where <name> is the menu
file name minus the extension) is saved, and on second and subsequent uses
of the !MENU command, the stack file is copied for direct execution. This
means second and subsequent uses of !MENU start execution much faster
than the first time.
If the stack file should not match the menu file, then the menu may not work
correctly. This could happen if the binary menu file was overwritten (not by
the !LOADCF command), leaving an old stack file in place. If this should
happen, reload the menu using !LOADCF.
The total number of labels allowed is 250. If this number is exceeded, all
labels beyond that will not be accessible.
Example
!MENU
NAME >MYMENU

NOHOLD
Introduction
Allows exit from a menu or macro if a DATAMINE fatal error occurs, or if ! is
entered by the user. The current command in the menu or macro is
terminated, and control returns to the keyboard with the system prompt
!>>> if @DICT is set to 0, 1 or 2 or the message
>>> PRESS RETURN TO INVOKE COMMAND PROCESSOR <<<
is displayed if @DICT is set to 3 (i.e. the user is working with the full screen
interface).
!NOHOLD is the default condition on entry to a menu or macro.
Once the !NOHOLD command has been given, it remains in force until the
!HOLD command (q.v) is executed.
The flag @FLAG3 is set to 0 to indicate that the !NOHOLD condition is in
force.
Process Summary
NOHOLD Allows exit from macro or menu on DATAMINE fatal
error.
Notes
Unlike !KBON and !KBOFF, the current !HOLD/!NOHOLD position is
unchanged by calling a lower level macro. However, if the position is
changed within the lower level macro, then this is passed back to the calling
macro.
Example
!NOHOLD

NOMENU
Introduction
Checks the syntax of the currently established menu. !NOMENU works in the
same way as !MENU, except that the menu is not executed.
The menu name is requested. This must be the name of a binary random
access menu file loaded by the !LOADCF command.
Process Summary
NOMENU Validates the syntax of a menu.
The menu should have been loaded previously into a named
random access menufile by LOADCF.
>NAME > Enter the name of the required menu. The name is one of the
menus loaded by the LOADFCF process. The name may be up to
56 characters long and may contain pathnames. The name
should not contain the character '.', except as part of an
optional file extension (.FFF). If there is no extension.MEN will
be appended. If the response is ?, a help message will be
displayed. If the response is just <return>, the name
MENUFILE.DAT will be used.
>>> MENU FILE DOES NOT EXIST <<<
>>> ERR 78 <<< (0) IN RUN
The menu file either does not exist, or is malformed. Fatal; the process
is exited.
>>> WARNING - MORE THAN 250 SUBSTITUTION VARIABLES <<<
>>> ERR 84 <<< (250) IN UPDSTV
Only 250 variables may be in use at any time. Warning; the excess is
ignored and processing continues.
>>> ERR 72 <<< (0) IN RUN
No !START command was found to introduce the menu. Fatal; the
process is exited.

Notes
On executing the !NOMENU command for the first time for any menu, there
will be a delay while the menu is scanned and labels etc. entered into the
system stack file. This stack file (of form <name>.STK, where <name> is
the menu file name minus the extension) is saved, and on second and
subsequent uses of the !MENU command, the stack file is copied for direct
execution.
This means second and subsequent uses of !NOMENU start execution much
faster than the first time.
If the stack file should not match the menu file, then the menu may not work
correctly. This could happen if the binary menu file was overwritten (not by
the !LOADCF command), leaving an old stack file in place. If this should
happen, reload the menu using !LOADCF.
The total number of labels allowed is 250. If this number is exceeded, all
labels beyond that will not be accessible.
Example
!NOMENU
NAME >MYMENU

NORUN
Introduction
Checks a macro for syntax. Each macro command line is validated by the
Command Processor, but execution is not passed to the individual process.
This makes NORUN fast to execute, but prevents it from carrying out process
specific checks, as for example that files exist and are in the correct format.
The format of the NORUN command exactly matches that of the RUN
command.
The macro name may be specified following the NORUN command name. It
is located in the macro library attached to &MACLIB. If no macro name has
been specified, and there is more than one macro in the library, then a list of
macro names found in the library is displayed, and the user must select one
interactively.
If the macro contains substitution variables to be substituted at run time,
these substitutions may be entered on the command line, exactly as for the
RUN command. Note that if the !PROMPT, !LET or !STKPAR commands also
supply the same substitution variables, then these values override those
entered on the command line.
A NORUN command would look like:-
!NORUN MACRO,&MACLIB(MACLIB),$1='MYFILE'
Note that NORUN cannot be used to validate nested macros. Each macro
must be individually validated.
Process Summary
NORUN Validates syntax of a macro or menu in a database file.
&MACLIB The macro library.
AAAAAAAA (Optional) The macro or menu name in the library.
If there is more then one macro or menu in the library, and no macro or
menu name was specified, then a list of macro names is given and the user
must select the one required:
>NAME> Enter required macro or menu name. If the name entered
does not appear in the list, the question is repeated. A response
of !<return> will exit the process. A response of ?<return> will
give a help message.
Substitution parameters follow as retrieval criteria.

>>> ERR 72 <<< (0) IN RUN
No macroname supplied. (This message is only produced if !NORUN is
executed from a macro, and no macro name is supplied; in this case,
name prompting does not take place). Fatal; the process is exited.
>>> SUBSTITUTION STRING NOT IN QUOTES <<<
>>> ERR 76 <<< (wordno) IN RUN
Substitution variable was not within quotes. wordno is the word number
in the retrieval fields. This refers to the $1='$2' command line setting.
>>> NULL SUBSTITUTION VARIABLE NAME <<<
Null or blank substitution variable. Blanks may not be replaced. wordno
is the word number in the retrieval fields. Fatal; the process is exited.
Notes
Aliases for NORUN may not be used if the !NORUN command appears in a
macro.
Example
!NORUN MACRO,&MACLIB(MACLIB),$1='*KEY1(COPPER),*KEY2(GOLD)'

NOXRUN
Introduction
Checks a macro for syntax. The macro library is located in a character format
system file external to the database. Each macro command line is validated
by the Command Processor, but execution is not passed to the individual
process. This makes NOXRUN fast to execute, but prevents it from carrying
out process specific checks, as for example that files exist and are in the
correct format. The format of the NOXRUN command exactly matches that of
the XRUN command.
The macro name may be specified following the NOXRUN command name. It
is located in the macro library name supplied in response to the SYSFILE>
prompt. If no macro name has been specified, and there is more than one
macro in the library, then a list of macro names found in the library is
displayed, and the user must select one interactively.
these variables may be entered on the command line, exactly as for the RUN
command. Note that if the !PROMPT or !LET or !STKPAR commands also
A NOXRUN command would look like:-
!NOXRUN MACRO,$1='MYFILE'
SYSFILE>MACLIB.DAT
Note that NOXRUN cannot be used to validate nested macros. Each macro
must be individually validated.
Process Summary
NOXRUN Validates the syntax of a macro or menu.
The macro or menu should be in a character-format system file.
>SYSFILE> Character-format macro or menu file. The name may be up to
56 characters long and may contain pathnames (if these are
supported by your operating system). If the response is
?<return> then a help message is produced. A response of
!<return> exits the process. If the file does not exist, a
message is produced and the process exited.

>>> SYSTEM FILE NOT FOUND <<<
>>> ERR 79 <<< (0) IN RUN
The requested system file does not exist, or is corrupted or is not a
character format file. Fatal; the process is exited.
>>> ERR 72 <<< (0) IN RUN
No macroname supplied. (This message is only produced if !NOXRUN is

Notes
Aliases for NOXRUN may not be used if the !NOXRUN command appears in a
macro.
Example
!NOXRUN MACRO,$1='*KEY1(COPPER),*KEY2(GOLD)'
SYSFILE>MACRO.DAT

ONERR
Introduction
Transfers control to a specified label in the menu or macro if a fatal error
occurs.
!ONERR works identically to the !HOLD command, except that transfer is
made to the specified label rather than to the next command in the macro if
a fatal error is found. A fatal error is one that causes the flag NFATAL to be
set. Such errors are described in the Reference Manual as 'Fatal'. The
exception to this is that syntax errors in macro or menu commands will
cause an immediate exit from the menu or macro.
The format is:-
!ONERR GOTOXXXX
where XXXX is an up to four character label in the macro. The label may be
separated from the GOTO for ease of reading.
Once the !ONERR command has been given, it remains in force until
cancelled. This may be done by use of the !NOHOLD command.
Like the !HOLD command, !ONERR uses FLAG(3) to indicate that the
condition has been specified. In the case of !ONERR, FLAG(3) holds the alpha
label string.
Process Summary
ONERR Transfers control to label on DATAMINE fatal error.
Format: !onerr gotoXXXX
where XXXX is a label in the current menu or macro.
Either the label (displayed below the message) was too long (>4
characters) or was not found in the menu or macro. Fatal; the menu or
macro is abandoned. recordno is the record number in the menu or
macro (from !START).

Notes
The label is not checked until a fatal error occurs and an attempt is made to
take the transfer.
Example
!ONERR GOTO ERR

PICDIR
Introduction
Writes file names to an output file (catalogue file) if the file name or field
names within the file match the given pattern expressions.
Process Summary
PICDIR selects file names from the database directory if the file name or
contained field names conform to a series of pattern matching expressions.
Expression Syntax
In the following discussion, all keywords are capitalised. When running
PICDIR, any keyword may be entered in either uppercase or lowercase and
abbreviated to its first three (or more) characters.
The syntax of a pattern matching expression is:
[FILE] [REGEXP] <pattern>
or FIELD [REGEXP] <pattern>
or FIELD <kind>
or FIELD [REGEXP] <pattern>, <kind>
The keyword "FILE" is optional. If a pattern is to be matched against field
names, the keyword "FIELD" must be included. The field "kind" will be
matched against the type (numeric or alphanumeric) and storage class
(explicit or implicit) of the fields in any file.
The keyword "REGEXP" is normally omitted, in which case "pattern" may
consist of literal characters to be matched, or one of the following elements:
? Any single character.
* A group of zero or more characters.
[...] Any one of the characters enclosed in the square brackets.
The shorthand notation "a-z" means any lowercase letter; refer
to the examples below for more details.
[^...] Any character except one of these.
The special meaning of a character (e.g. "*") is lost if the character is
preceded by "\", hence to match a literal "*", use "\*". Quotes (double or
single) may be used to enclose patterns if desired.

Where a pattern is applied to file names, lowercase letters are translated into
uppercase before the pattern is used.
If the keyword "REGEXP" is used,the pattern specifies a full regular
expression similar to those used by various UNIX utilities. Regular
expressions allow advanced users to make more complex selections than are
possible by using the pattern elements specified above. A regular expression
in PICDIR may contain the following elements:
% Matches the beginning of the file or field name.
$ Matches the end of the file or field name.
* Zero or more occurrences of the preceding pattern element.
? As above.
[...] As above.
[^...] As above.
The "kind" is a list of field type or storage class specifiers, separated by
commas. Keywords that specify field type are "NUMERIC" or
"ALPHANUMERIC". Storage classes are "EXPLICIT" or "IMPLICIT". Of course,
any of these may be abbreviated to three (or more) letters.
If more than one type or class keyword is given, the last one specified is
used.
Concatenation of Expressions
The result of a pattern matching expression is either TRUE or FALSE. Any
result may be inverted by preceding the expression by the keyword "NOT"
(e.g. "NOT XPICRT,IMPLICIT"). Two expressions may be joined together by
"AND" or "OR" operators. The result is another expression. The "AND"
operator has higher precedence than "OR". Parentheses (brackets) may be
used to override the normal order of evaluation of expressions.
&OUT Output catalogue file, giving list of files.
*FILE* Optional name for the field that is to contain the
file names. The default is "'FILENAM", i.e. PICDIR will
produce a catalogue file.
@APPEND* If set to 1 then selected field names will be appended
to the &OUT file, provided it exists and has a valid DD (0).
@PRINT* =0 No display of matching file names
>0 Display file names as they are selected. (0)

@SORT* If set to 1 then the output file will be sorted after all file
names have been written to it (0).

>TEST> Enter one or more file or field name pattern matching
expressions to specify the desired record selection. Input is
free-format, and may occupy as many lines as necessary.
THE KEYWORD "END" MUST BE ENTERED LAST TO SIGNAL
PICDIR TO START PROCESSING THE FILE.
>>> WARNING: Cannot append to file ffffffff
A new file will be created
Cannot append fieldnames to the file specified as &OUT. Check the file
name given. A new &OUT file will be created.
>>> ERROR: Unable to open file ffffffff
File will be ignored by PICDIR
Cannot open file specified in pattern matching expression. Ignored.
>>> ERROR: PICDIR works with native file databases
>>> ERROR: Files have different DDs, cannot append
File specified in pattern matching expression and the file specified as
&OUT have different DDs. Fatal; the process is exited.
>>> ERROR: Unexpected execution error
>>> ERROR: Illegal instruction found
>>> SYNTAX ERROR AT " "
Syntax of pattern matching expression is incorrect. Fatal; the process is
exited.

Example
1. Select files whose name ends in "S", except for the file "PRECIOUS".
TEST>*S AND NOT PRECIOUS END
2. Select all perimeter files.
TEST>FIELD XP,NUMERIC,EXPLICIT AND
TEST>FIELD YP,NUMERIC,EXPLICIT AND
TEST>FIELD ZP,NUMERIC,EXPLICIT AND
TEST>FIELD PTN,NUMERIC,EXPLICIT AND
TEST>FIELD PVALUE,NUMERIC,EXPLICIT END
3. A database contains a series of section plots. Sections are spaced 50
metres apart. A file naming convention has been used, such that the
name is made up from a five-digit section coordinate, followed by a
direction code ("N" or "E"), followed by ".P". Select (by name only) all
such files for sections 10200N to 10700N and 20800E to 21150E.
TEST>10[2-7]00N.P OR 10[2-6]50N.P OR
TEST>20[89][05]0E.P OR 21[01][05]0E.P END
4. Select all files that contain implicit alphanumeric fields. (This will select
all RESULTS files).
TEST>ALPHA,IMPLICIT END

PICFLD
Introduction
Writes field names to an output file if the field names in the input file match
the given pattern expressions.
Process Summary
PICFLD selects field names from a file if they conform to a series of pattern
matching expressions.
Field Selection Syntax
PICFLD, any keyword may be entered in either uppercase or lowercase and
[FIELD] <pattern>
or [FIELD] <kind>
or [FIELD] <pattern>, <kind>
In each case, the keyword "FIELD" is optional. The "pattern" will be matched
against the names of the fields in the &IN file. The field "kind" will be
matched against the type (numeric or alphanumeric) and storage class
(explicit or implicit) of the input file fields.
A "pattern" may consist of literal characters to be matched, or one of the
following elements:

The "kind" is a list of field type or storage class specifiers, separated by
commas. Keywords that specify field type are "NUMERIC" or
"ALPHANUMERIC". Storage classes are "EXPLICIT" or "IMPLICIT". Of course,
any of these may be abbreviated to three (or more) letters. If more than one
type or class keyword is given, the last one specified is used.
Concatenation of expressions
The result of a pattern matching expression is either TRUE or FALSE. Any
result may be inverted by preceding the expression by the keyword "NOT"
(e.g. "NOT XPICRT,IMPLICIT"). Two expressions may be joined together by
"AND" or "OR" operators. The result is another expression. The "AND"
operator has higher precedence than "OR". Parentheses (brackets) may be
used to override the normal order of evaluation of expressions.
&IN Input file, from which fields are to be
selected.
&OUT Output file, containing selected field names.
*FIELDNAM* Optional name for the field in &OUT that is to contain
the selected field names. The default is "FIELDNAM".
@PRINT* =0 No display of matching field names
>0 Display field names as they are matched. (0)
@APPEND* If set to 1 then selected field names will be appended
to the &OUT file, provided it exists and has a valid DD (0).
@SORT* If set to 1 then the output file will be sorted after
all field names have been written to it (0).
>TEST> Enter one or more field name specifiers to obtain the
desired field selection. Input is free-format, and may
occupy as many lines as necessary. THE KEYWORD "END"
MUST BE ENTERED LAST TO SIGNAL PICFLD TO START
PROCESSING THE FILE.
Error and warning Messages

Syntax of pattern matching expression is incorrect. Fatl; the process is
exited.
Example
1. Select all three-letter fields that begin with "Au" or "AU". The fields must
be numeric.
TEST>FIELD A[uU]?,NUMERIC END
2. Select all explicit, numeric fields from a model file, except for the
"standard" ones.
TEST>NUMERIC,EXPLICIT AND NOT
TEST>([XYZ]C OR [XYZ]INC OR IJK) END
Note that brackets are required to associate the "NOT" with all the seven
standard fields.

PICREC
Introduction
Writes records to an output file if the records in the input file match the
given input expressions.
Process Summary
PICREC selects records from a file if they conform to a series of input
expressions.
Expression Syntax
An expression may be either a relational expression or a pattern matching
expression.
PICREC, any keyword may be entered in either uppercase or lowercase and
Relational Expressions
The syntax of a relational expression is:
[FIELD] <fieldname> <operator> [CONSTANT] <value>
or [FIELD] <fieldname> <operator> [FIELD] <fieldname>
or [CONSTANT] <value> <operator> [FIELD] <fieldname>
The keywords FIELD and CONSTANT are optional, and need only be specified
where necessary to avoid confusion (e.g. "ROCKTYPE=FIELD T2" or
"ROCKTYPE=CONSTANT T2").
Any of the six relational operators (">", ">=", "=", "<=", "<" or "<>") may
be used. "<>" means "not equal to".
Pattern Matching
<fieldname> MATCHES [REGEXP] <pattern>
If the keyword REGEXP is missing, a "pattern" may consist of literal
characters to be matched, or one of the following elements:

If the keyword REGEXP is included, the pattern may be a full regular
expression similar to those used by various UNIX utilities. Regular
expressions allow advanced users to make more complex selections than are
possible by using the pattern elements specified above. A regular expression
in PICREC may contain the following elements:
% Matches the beginning of the field value.
$ Matches the end of the field value.
* Zero or more occurrences of the preceding pattern element.
? As above.
[...] As above.
[^...] As above.
Concatenation of expressions
The result of a relational or pattern matching expression is either TRUE or
FALSE. Any result may be inverted by preceding the expression by the
keyword "NOT" (e.g. "NOT BHID MATCHES RHD*"). Two expressions may be
joined together by "AND" or "OR" operators. The result is another
expression. The "AND" operator has higher precedence than "OR".
Parentheses (brackets) may also be used to override the normal order of
evaluation of expressions.
&IN The name of the file from which records
are to be selected.
&OUT The name of the file to which selected records
are to be written.

&FIELDLST* Optional file to specify fields to output.
*F1* The name of the first field to be transferred from
the input file to the output file. If no fields are explicitly
named, all fields are copied. You may only apply relational
and pattern matching tests to fields that are to appear in
the output file.
*F2* Second field to be copied.
*F3* Third field to be copied.
*F4* Fourth field to be copied.
*F5* Fifth field to be copied.
*FIELDNAM* Field in &FIELDLST that holds the names of the data fields
to output in &OUT.
@APPEND* If set to 1 then selected records will be appended to
the &OUT file, provided it exists and has the same fields as
the input file (0).
>TEST> Enter one or more relational or pattern matching
expressions to specify the desired record selection. Input is
free-format, and may occupy as many lines as necessary.
THE KEYWORD "END" MUST BE ENTERED LAST TO SIGNAL
PICREC TO START PROCESSING THE FILE.
>>> ERROR: Read error from file ffffffff
Read error from file specified as &IN. Fatal; the process is exited.
>>> ERROR: field aaaaaaaa is too long

Syntax of pattern matching expression is incorrect. Fatl; the process is
exited.
>>> ERROR: Incompatible types for " "
and " "
Field types are incompatible in relational expression. Fatal; the process
is exited.
>>> ERROR: " " MATCHES...
Alphanumeric field required
Alphanumeric field required for pattern matching expression. Fatal; the
process is exited.
>>> ERROR: Illegal pattern:
Illegal pattern in pattern matching expression. Fatal; the process is
exited.
>>> ERROR: More than nnnnn instructions
Maximum number of expressions is 100. Fatal; the process is exited.
Example
1. Select records from a file where BHID values start with the letters
"RDH", or the field XCOLLAR is between 10200 and 11200:
TEST>BHID MATCHES RDH* OR
TEST>XCOLLAR>=10200 AND XCOLLAR<=11200
TEST>END
2. Select records where the contents of field "Au1" is greater than the
contents of field "Au2":
TEST>Au1 > Au2 END

3. Select records where the field LOG contains both codes "Cu" and "Pb".
TEST>LOG MATCHES *[cC][uU]*[pP][bB]* OR
TEST>LOG MATCHES *[pP][bB]*[cC][uU]* END
Note that "[cC][uU]" will match "cu", "cU", "Cu" or "CU".
4. Select records where CODE is five characters long, but does NOT end in
3 or 4.
TEST>CODE MAT ????[^34] END
alternatively, one could specify the following:
TEST>CODE MAT ????? AND NOT CODE MAT *[34] END
5. Select all records where ROCKCODE = 7, and BHID is DDH034, DDH147
or DDH136.
TEST>ROCKCODE=7 AND (BHID=DDH034 OR
TEST>BHID=DDH147 OR BHID=DDH136) END
Note that parentheses are required here, since by the default the
expressions would be combined as below:
TEST>(ROCKCODE=7 AND BHID=DDH034) OR
TEST>BHID=DDH147 OR BHID=DDH136 END
6. Select all records where BHID values begin with zero or more spaces,
followed by "RDH".
TEST>BHID MATCHES REGEXP "% *RDH" END
A full regular expression is required to match possible leading spaces.
Note also how quotes are required, since the pattern contains a space.

PROMPT
Introduction
Displays lines on the screen and prompts for input. The !PROMPT process
allows menu screens to be built up, and substitution variables to be defined
or redefined as often as required. In-built validation procedures are available
on the responses to prompts.
The prompt process is followed by as many data lines as required. If the first
character of the line is 0 then the line will be displayed on the screen; if the
first character is a 1 then a prompt string is being defined. If the first
character is a 2, then the screen will be cleared. A line beginning with any
other character will be ignored as a comment.
Each data line may be up to 80 characters long, including the first 0 or 1. An
example is:-
!PROMPT
0
0 File listing macro.
0 ===================
1 Enter the file name to be listed (up to 8 chars)>'$1',a,8
!LIST &IN($1)
The user's response, supplied after the > character prompt is placed in
substitution variable $1, so that all subsequent references to $1 in the macro
will be substituted by the given response.
Numeric responses
The substitution variable, defined as shown by quotes, may optionally be
followed by a number of parameters. The most simple form of prompt string
is:-
1 Enter number>'$1'
The response to $1 must be numeric (i.e. an integer or decimal number of
form 12 or 12.56, a number with an exponent such as 2.3E-6, or the absent
data (lowest system number) response -, or the highest system number +,
or 'trace' (TR) or 'detection limit' (DL)). The number must lie within the
limits - and +, i.e. effectively unlimited.

For numeric strings, range limits can be placed on the response. For
example:-
1 Enter number>'$1',n,1,3
The numeric response (indicated by n or N) must now lie in the range 1-3
(inclusive). Note that both upper and lower limits must be specified, if either
are. The order is lower,upper.
We can further enter a string of permitted values for the response. For
example:-
1 Enter number>'$1',n,1,3,1,2,3
In this case, only values 1, 2 or 3 are permitted. This omits 1.1 etc, which
would have been allowed in the earlier example. Note that the comparison is
done on the numeric value, not on the string. This means that 1.0, 1, 1E0,
etc. are all considered identical.
For numbers, we may also specify that the ! symbol is permitted. Although
this is not a numeric response, by specifying ! we can trap the use of this
symbol. The use of this is discussed later.
Alphanumeric responses
The format for alphanumeric strings is very similar. For example:-
1 Enter file name>'$1',a
would allow a character string (indicated by a or A) up to the maximum (72
chars) as a response.
We can define the maximum length of the string:-
1 Enter file name>'$1',a,8
Here the string may be no more than 8 characters long.
Just as for numbers, we can also specify a set of responses which are legal.
For example:-
1 Enter file name>'$1',a,5,file1,file2,file3
would permit only the responses file1, file2 or file3.
If the last character on a prompt line (starting with 1) is a comma, then the
line can be continued. A maximum length of 240 characters is permitted,
counting from the character following the initial 1 to the end of the last
non-blank character. For example:-
1 Enter number for required option>'$1',n,1,20,1,2,3,4,5,6,7,8,9,10,
11,12,13,14,15,16,17,18,19,20,!

Any characters following 240 will be ignored
Upon matching responses, an exact response is required for alphanumeric
variables. (For numeric variables, the requirement is that the numbers
match). If a comma is to be part of the required response, then the response
must be contained within quotes. For example:-
1 Enter response >'$1',a,10,'a,b','b,c'
would permit the responses to be a,b or b,c.
Default Values
A default may be defined to any response. This default is contained within
square brackets, and must appear before the substitution variable. For
example:-
1 Enter choice (1,2,or 3) [1]>'$1',n,1,3,1,2,3
If <return> is pressed, then the default taken will be 1. The default does not
have to be part of the permitted responses, but it must be of the same type
(numeric or alphanumeric).
Substitution in Prompt Lines
Existing substitution variables may be incorporated into prompt lines.
Suppose that a variable $1 was already set up with value collars. We could
then include a prompt:-
!PROMPT
0 Your input file is $1
1 Enter required file name [$1]>'$1',a,8
This would appear as:-
Your input file is collars
Enter required file name [collars]>
The response would default to collars if <return> was pressed. If another
name were given, this would replace $1 with its new value.
Substitution can also take place within the permitted responses. For
example, the following is legal:-
1 Enter choice [$2]>'$1',n,1,$3,$1,$2,$3
Note that, in this example, $1, $2 and $3 must be numeric variables. If they
are not, a run time error will occur. The user must beware that substitution
will not make the line greater than 80 characters. The above prompt is better
written as:-

1 Enter choice [$2]>'$1',1n,1,$3,
1$1,
1$2,
1$3
to avoid this possibility.
Stack File Display
If to any prompt the response is !!, then the current stack file will be
displayed. The format is:-
STACK NUMBER 4
==============
STACK FILE REVISION NO: STACK V3.2
FILE TYPE (0=DATABASE,1=MENU,>=2=EXTERNAL): 3
FILE NAME: mymacro.mac
MACRO NAME IN FILE: m
RECORD NUMBER OF !START: 36
MACRO POINTER WITHIN MACRO: 12
NUMBER OF SUBSTITUTION VARIABLES: 2
SUBSTITUTION VARIABLES AND VALUES
=================================
$1 = 3
$2 = 12.0000
END OF STACK LISTING
====================
Errors in Processing
If an incorrect response is given, an error message is displayed, and the
prompt given again. For a numeric response, possible messages are:-
>>> OUTSIDE RANGE OF 99999 TO 99999 <<<
>>> ILLEGAL CHARACTER IN POSITION 9 <<<
Also, if the permitted response is non-numeric, the message will be given:-
>>> NON-NUMERIC PERMITTED RESPONSE <<<

For alphanumeric strings, if the response is too long:-
>>> ALPHA STRING LONGER THAN 9999 CHARS <<<
For both types, if there is no match to the set of permitted responses:-
>>> NO MATCH TO PERMITTED VALUES <<<
<Listing of all permitted values>
The response ? to any prompt will give the message:-
>>> Number required in range of 99999 to 99999 <<<
>>> Response must be one of the following:-
For alphanumeric fields, ? gives:-
>>> Alphanumeric string required of up to 99 characters <<<
>>> Response must be one of the following:-
Any prompt string which is unrecognisable will give rise to the message:-
>>> MALFORMED PROMPT STRING <<<
Followed by display of the incorrect line.
Termination of Macros or Menus
The response ! will cause a menu or macro to be terminated, unless this
response has been trapped by entering it as a permitted response.
Bypassing Macros or Menus
If !<string> has been entered which is not one of the permitted responses,
then this will be assumed to be a DATAMINE command for execution. It will
be executed immediately, following which return will be made to the start of
the !PROMPT command from which the command was issued. This facility
allows a menu to be temporarily bypassed.

Process Summary
PROMPT Displays lines on screen and prompts for input.
2....... Clears screen.
0....... Lines to be displayed.
1....... '$1',n,bot,top,<list of responses>
Prompt line for numeric response. Bot is lower limit, top is
upper limit. <list of responses> with each separated by
commas: eg. 3,4.2,5. All items following '$1' are optional.
1....... '$1',a,len,<list of responses>
Prompt line for alpha response. Len is maximum length of
response in characters. <List of responses> with each
separated by commas: eg. a,ab,c. All items following '$1' are
optional.
Response is placed in variable '$1' (any string up to 8 chars)
and substitutes in all command and data lines (except labels).
Defaults are placed in square brackets. Substitution in the line is
permitted. E.g: 1 Enter choice ($1,$2,$3)
[$3]>'$1',n'$1,$3,$1,$2,$3
Apart from the errors given above, a syntax error is produced if the prompt
string (starting with 1) is incorrect.
>>> MALFORMED PROMPT STRING <<<
<Listing of malformed line>
>>> ERR 77 <<< (0) IN GETPMT
Fatal; the menu or macro will be abandoned.
Notes
!PROMPT executes an automatic !KBOFF command each time it is executed.
Example
!XX0:PROMPT
0
0 DATAMINE EXAMPLE MENU
0 ------------------------

0
0 Select from the following choices:-
0
0 List the file directory 1
0 List a named file 2
0 End session !
0
1 Enter your choice (1,2,3) >'$1',n,1,2,1,2,!
!GOTO XX$1
!XX1:LISTDR
!GOTO XX0
!XX2:PROMPT
1 Enter name of file to be listed>'$2',a,8
!LIST &IN($2)
!GOTO XX0
!XX!:LOGOFF
!END

REM
Introduction
Allows comments to be put anywhere in a macro or menu file. Anything on
the line following !REM is treated as comment.
Process Summary
REM Allows comments to be put anywhere in a macro
or menu.
Example
!REM This menu used for input of additional drillhole data

RETURN
Introduction
Transfers control back to the next statement following a GOSUB statement in
a macro or menu.
Process Summary
RETURN The GOSUB statement transfers control to a
subroutine; the RETURN statement transfers control back to
the next statement following the GOSUB.
There may be a number of GOSUBs to the same subroutine,
and a RETURN occurring in that subroutine returns control
to the statement following the specific GOSUB used to get
to the subroutine.
A subroutine should only be entered by using a GOSUB. Otherwise, the RETURN
statement will cause an error when it is executed.
None.
Example
!RETURN

RUN
Introduction
Starts execution of a macro in a database file.
The macro name may be specified following the RUN command name. It is
located in the macro library attached to &MACLIB. If no macro name has
been specified, and there is more than one macro in the library, then a list of
macro names found in the library is displayed, and the user must select one
interactively.
these substitutions may be entered on the command line. Note that if the
!PROMPT, !LET or !STKPAR commands also supply the same substitution
variables, then these values override those entered on the command line.
A RUN command would look like:-
!RUN macro,&MACLIB(maclib),$1='myfile'
Process Summary
RUN ` Starts execution of a macro or menu in a database file.
&MACLIB The macro library.
If there is more than one macro or menu, and no macro or menu name was
specified:-
>NAME> Enter required macro or menu name. If the name entered does
not appear in the list, the question is repeated. A response of
!<return> will exit the process. A response of ?<return> will
Substitution parameters follow as retrieval criteria.
>>> ERR 72 <<< (0) IN RUN
No macroname supplied. (This message is only produced if !RUN is

Notes
It is a requirement to use $ as the first character in substitution strings and
that they be no longer than 8 characters.
Care is required in substituting character strings. If a macro contained the
line:-
ROCKTYPE='$1'
then the substitution $1='A' would correctly give:-
ROCKTYPE='A'
The quotes must surround the substitution variable, as quotes cannot be
passed through within a string; i.e. ROCKTYPE=$1 with $1='A' would lead to
the incorrect substitution ROCKTYPE=A.
If a substitution variable has no value set, then the original dummy string is
left in place. This can be used to advantage. For example, suppose a macro
contained:-
!LIST &IN(MYFILE),$1
Then $1 could be used for optional retrieval criteria. For example, if
$1='Cu>0.01,@ECHO=1' then the listing would be echoed to the print
device, and would contain only those records satisfying Cu>0.01. If the
macro was run without a specification for $1, then $1 would be ignored; this
is because $1 by itself on a command line is taken to be a retrieval criteria of
$1>-<+, and since $1 is not a field in the file, the Command Processor
ignores it. Thus dummy parameters need not be substituted if the context
means that they are ignored.
If a file or field symbolic name is not given an actual name within a macro,
then the actual name will be prompted at run time. This is true whether the
file or field name is compulsory or optional. For example, suppose that a
macro for listing a single field within a file consisted of:

!START MACRO
!LIST &IN,*F1
!END
On running the macro, using command:-
!RUN &MACLIB(MACLIB),MACRO
the following prompts would appear:-
LIST
FILE ASSIGNMENTS
================
IN () >
PROCESS FIELDS
================
F1 () >
The names of the required file and the field within it are entered at run time.
Aliases for RUN may not be used if the !RUN command appears in a macro.
Example
!RUN MACRO,&MACLIB(MACLIB),$1='*KEY1(COPPER),*KEY2(GOLD)'

SCROFF
Introduction
Directs text to a system file rather than the screen, in a macro or menu.
Process Summary
SCROFF Diverts text screen output into a system file during macro
execution.
Only output created by interactive prompts, or created by the soft
commands !ECHO, !PROMPT or !SCREEN is seen on the display.
!SCROFF only works from within a macro or menu, and then only
after !HOLD or !ONERR has been executed. If neither !HOLD or
!ONERR are active, a warning message is displayed, and screen
output continues to be seen as macro execution proceeds.
Screen output is re-established by means of the !SCRON command,
the !NOHOLD command, or whenever the macro or menu
terminates. For nested menus, each menu maintains its own
!SCRON/SCROFF status. The default on macro entry is !SCRON.
The system file name is based on the database directory name
("XXXXXLOG.DAT"), or from the first value assigned to an
environment variable called "ScreenLog".
@CLEAR Control the action to clear the screen and/or logfile: 0 none, 1
screen, 2 logfile, 3 screen and logfile (2).

SCRON
Introduction
Redirects output to the screen following previous use of the !SCROFF
command in a macro or menu.
Process Summary
SCRON In a macro or menu, restores screen output previously diverted by a
!SCROFF command.
See SCROFF for a description of screen output control.
@CLEAR Control the action to clear the screen and/or logfile:
0 none, 1 screen, 2 logfile, 3 screen and logfile (0).
Example
!scron

START
Introduction
Starts a macro or menu. The START <macroname> command must be the
first in a macro or menu. The <macroname> parameter defines the name of
the macro or menu, and is referenced in the !MENU, !RUN or !XRUN
processes; it must be unique within a macro library. A macro name may be
up to 8 characters long, and may not start with the characters @, &, * or !.
It should not contain embedded blanks or the characters = > < ' or,. Upper
and lower case names are considered different.
Outside a macro START is illegal.
Following the macro name, a comment may be placed, separated from the
macroname by one or more commas. For example:-
!START mac1 This is a section plotting macro.
The macroname and the comment will be shown by the RUN or XRUN
processes, if the user is invited to select the required macro from several.
The !START command may not take a label preceding it.
Process Summary
START Names a macro or menu in a library.
AAAAAAAA The macro or menu name.
Example
!START MYMAC Macro to validate data.

STKPAR
Introduction
Retrieves substitution variables and their values from a system character
format file. This file may be set up by the !STKSAV command from within a
macro or menu, or it may be set up with a system editor. The variables from
file totally replace any existing variables in the stack. The form of the
command is:-
!STKPAR <filename>
where <filename> is a system file name. It may be up to 56 characters in
length and may contain pathnames. The <filename> may be substituted in
whole or in part by substitution variables. The form of the system file is:-
nnn Number of substitution variables on file. Max 250.
<var1><val1>
<var2><val2>
where <var1>,<var2> are the names of the substitution variables, and
<val1>, <val2> are their values. Each <var> occupies 8 characters,
followed by the value (max 72 characters).
Process Summary
STKPAR Reads substitution variables from a file.
Format: !stkpar <filename> where <filename> is a system file
name up to 56 chars long.
>>> !STKSAV OR !STKPAR: ERROR IN ACCESSING SYSTEM FILE <<<
>>> ERR 90 <<< (0) IN MACGET
The file did not exist, was the wrong type, or a read error was
encountered. This message will also occur if no file was specified, or the
file name was too long. Fatal; the macro or menu is exited.
Example
!STKPAR \DATAMINE\PROJECTS\$PROJ

STKSAV
Introduction
Writes substitution variables and their values to a system character format
file. This file may be read by the !STKSAV command from within a macro or
menu. The form of the command is:-
!STKSAV <filename>
where <filename> is a system file name. It may be up to 56 characters in
length and may contain pathnames. The <filename> may be substituted in
whole or in part by substitution variables. The form of the system file is:-
nnn Number of substitution variables on file. Max 50.
<var1><val1>
<var2><val2>
where <var1>,<var2> are the names of the substitution variables, and
<val1>, <val2> are their values. Each <var> occupies 8 characters,
followed by the value (max 72 characters).
Process Summary
STKSAV Saves substitution variables to a file.
Format: !stksav <filename> where <filename> is a system file
name up to 56 chars long.
>>> !STKSAV OR !STKPAR: ERROR IN ACCESSING SYSTEM FILE <<<
>>> ERR 90 <<< (0) IN MACGET
The file already existed and was the wrong type, or a write error was
encountered. This message will also occur if no file was specified, or the
file name was too long. Fatal; the macro or menu is exited.
Example
!STKSAV \DATAMINE\PROJECTS\$PROJ

SYSFILE
Introduction
Checks to see if a system file exists and sets the value of a substitution
variable to 1 or 0 if the file exists or does not exist respectively.
Process Summary
SYSFILE Checks if a system file exists.
The command format is similar to the !FILE command:
!sysfile <var>=<pathname>
where <var> is a substitution variable which is set to '1' if the
file indicated by <pathname> exists, otherwise <var> is set to
0. The <pathname> may optionally be specified by means of a
substitution variable. If necessary, its length will be truncated to
56 characters.
Note that the existence of a file does not imply that the file is
readable.
Example
!sysfile $exists#=COLLARS.ASC
If the file COLLARS.ASC exists, $exists# will be set to '1', otherwise,
$exists# will contain '0'.

VARINIT
Introduction
Initialises the number of substitution variables to zero for the current macro
level.
Example
!varinit

VARLOAD
Introduction
Enables substitution variables to be read from a file to be used with or to
replace substitution variables already being used in a macro or menu.
Process Summary
Reads substitution variables from a file. The variables read from file are
added to the current list if the parameter @MERGE equals 1, otherwise any
current variables are erased. VARLOAD will, (by default) load all substitution
variables, but will allow a named set of variables only to be loaded or merged
from the file.
Format: !VARLOAD <file>[,@MERGE=<merge>]
[,@DESC=$dname#][,$name#...]
where <file> is a system file path name up to 56 chars long. If the
parameter "@MERGE" is not specified, or <merge> is zero,
all current variables are erased. If <merge> is 1, any
variable that already exists in memory is updated with the
file value, and new variables are added to those in memory.
Both <file> and <merge> may be substitution variables.
The description supplied when the file was created can
optionally be restored into a supplied variable <$dname>.
If the optional list of variables is given, only these variables
are considered; otherwise all variables are loaded. The list
may be extended onto as many lines as necessary;
continuation is implied by ending the previous line with a
comma.
Example
E.g. !varload \datamine\projects\$proj, @merge=1, $title1#, $title2#,
$xmin#, $xmax#, $ymin#, $ymax#

VARSAVE
Introduction
Enables substitution variables being used in a macro or menu to be saved to
a file, either adding to or replacing substitution variables already in the file.
Process Summary
Saves or merges substitution variables into a file. VARSAVE will, (by default)
save all substitution variables, but will allow a named set of variables only to
be saved or merged into the file.
Format: !VARSAVE <file>[,@MERGE=<merge>]
[,@DESC=<description>][,$name#...]
where <file> is a system file path name up to 56 chars long. If the
parameter "@MERGE" is not specified, or <merge> is zero,
all contents of <file> are cleared first. If <merge> is 1, any
variable that already exists in the file is updated with the
current macro value, and new variables are added to the
file. Both <file> and <merge> may be substitution
variables. A description for the contents of the file can be
supplied. The description is stored on the first record of the
file with the revision number, and can be up to 68
characters long. Quotes may be used enclose the
description. If the optional list of variables is given, only
these variables are considered; otherwise all variables are
saved. The list may be extended onto as many lines as
necessary; continuation is implied by ending the previous
line with a comma.
Example
E.g. !varsave \datamine\projects\$proj, @merge=1, $title1#,
$title2#, $xmin#, $xmax#, $ymin#, $ymax#

XRUN
Introduction
Starts execution of a macro in a system file outside the database. This is
conventionally set up with the system editor. The maximum length of line is
80 characters.
The macro name may be specified following the XRUN command name. It is
located in the macro library name supplied in response to the SYSFILE>
prompt. If no macro name has been specified, and there is more than one
macro in the library, then a list of macro names found in the library is
displayed, and the user must select one interactively.
these substitutions may be entered on the command line, exactly as for the
RUN command. Note that if the !PROMPT, !LET or !STKPAR commands also
An XRUN command would look like:-
!XRUN macro,$1='myfile'
SYSFILE>maclib.dat
Process Summary
XRUN Starts execution of a macro or menu.
The macro or menu should be in a character-format system file.
>SYSFILE> Character-format macro or menu file. The name may be up to
56 characters long and may contain pathnames (if these are
supported by your operating system). If the response is
?<return> then a help message is produced. A response of
!<return> exits the process. If the file does not exist, a
message is produced and the process exited.

>>> SYSTEM FILE NOT FOUND <<<
>>> ERR 79 <<< (0) IN RUN
The requested system file does not exist, or is corrupted or not a
character format file. Fatal; the process is exited.
>>> ERR 72 <<< (0) IN RUN
No macroname supplied or macro name length greater than 8
characters. This message may be produced if !XRUN is executed from a
macro, and no macro name is supplied; in this case, name prompting
does not take place.
is the word number in the retrieval fields.
Notes
The notes for the RUN command for string substitution apply equally to the
!XRUN command.
Aliases for XRUN may not be used if the !XRUN command appears in a
macro.
Example
!XRUN MACRO,$1='*KEY1(COPPER),*KEY2(GOLD)'
SYSFILE>MACRO.DAT

Studio RM - Tutorial MACROS

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Studio RM - Tutorial MACROS

Uploaded by

Copyright:

Available Formats

Studio RM - MACROS

Tutorial para Macros

DMCH S. A.–MACROS-ENT-0001-1.00 Índice de contenido 2

DMCH S. A.–MACROS-ENT-0001-1.00 Índice de contenido 3

MACRO/MENU PROCESSES WITHIN STUDIO RM

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 1

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 2

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 3

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 4

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 5

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 6

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 7

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 8

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 9

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 10

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 11

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 12

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 13

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 14

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 16

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 17

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 18

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 19

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 20

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 21

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 22

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 23

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 25

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 26

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 27

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 28

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 29

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 31

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 32

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 33

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 34

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 35

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 36

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 37

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 39

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 41

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 42

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 43

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 44

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 45

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 47

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 48

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 49

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 51

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 52

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 53

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 54

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 55

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 57

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 58

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 60

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 61

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 62

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 63

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 64

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 65

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 66

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 67

DMCH S. A.-MACROS-ENT-0001-1.00 Tutorial de MACROS 68