MPE/iX release 7.5 3 CI enhancements
Jazz home
Software
Papers & Training
by Hariprasad and Jeff Vance, CSY
Enhancements summary:
User defined CI functions allow CI scripting to be more powerful and natural.
In support of user functions the RETURN command now supports an optional expression parameter.
User Functions
Syntax: userFuncName ( [parm-1] [,parm-2] ... [,parm-N] )
where:
userFuncName is the basename of an MPE or POSIX-named file. Typically
HPPATH variable is used to qualify 'userFuncName' just as
is done by the CI for command file names.
parm-x the parameters (arguments) of a user function can be any
arguments found in a CI expression. Thus, integers, quoted
strings, Booleans, CI variables, predefined CI functions,
and user functions are all possible argument values. A
user function without any parameters still requires the
enclosing parenthesis.
User defined functions are new to 7.5 and require patches MPEMXP9 and MPEMXQ0. User functions can be specified anywhere predefined CI functions are used. For example, where WORD(), STR, JINFO, FINFO, HEX, MIN() are used today in expression, a user functions can also be invoked. The semantics are the same as for the predefined functions in that the name of the function and all of its arguments are replaced by its function return value.
A user function is simply a UDC or command file (script) which returns a value to the caller (invocator). This is accomplished via the RETURN command, see below for more details. User functions can return Boolean, string, or 32 bit signed integer values. In a UDC environment a user function is the UDC name, and the only difference from standard UDCs is the RETURN command is required and must return a value. In a script, a user function is the script name (filename), and like UDCs, the only difference from conventional scripts is the RETURN command must return a value to the caller.
There are some differences between script filenames and user function filenames. Recall that as of MPE XL release 5.0 Express 3 scripts can have POSIX names. Also, later in release 6.0, in order to better support Java, POSIX filenames were allowed to contain the following additional special characters: ~\$%^*+|{}:. POSIX named user function script filenames cannot contain any characters which could be ambiguous in an expression. Thus, special characters such as +, *, %, $ and / cannot be supported in a POSIX named user function. To make the exclusion rule simple, POSIX named user functions may contain upper and lowercase A-Z, 0-9, ".", and "_". Since the "/" character is not permitted, POSIX named user functions may not be absolute pathnames and thus are not allowed to be qualified. This means that HPPATH must be used to resolve a POSIX named user function. Therefore, if POSIX named user functions are to be exploited the HPPATH variable must be modified to include one or more POSIX syntax names. Even if the POSIX named user function resides in an MPE group, HPPATH still needs to be changed to contain this MPE group name in POSIX syntax, e.g. :setvar HPPATH HPAPTH + ",../MYGROUP". Lastly, related to user function script names, an MPE-named and POSIX-named file can have the same spelling but be different names due to letter case.A For instance MYFUNC and MyFunc are spelled the same but are two different filenames. If there is a POSIX name in the HPPATH variable these subtle difference can be important.
Recursion (nesting) limits are the same as for predefined functions, namely the CI halts recursion at 30 levels deep. In some complex recursive examples it may be more possible to cause a NM CI stack overflow. This is due to the extra stack space consumed to execute a single user funcion. To further reduce the chance of a NM stack overlfow the CI's stack has been increased from 3,000,0000 bytes (750 pages) to 3,500,0000 bytes (875 pages). In addition to the larger NM stack, code was added to detect if a user function is executing near the stack limit. If there are just a few pages of stack space remaining the CI will generate this new warning:
Potential NM stack overflow prevented. (CIWARN 2027)
and terminate the execution of the function. It may still be possible to cause a CI stack overflow which aborts the CI. If this occurs try running the CI with a larger NMstack= value or reducing the complexity of the user function.
The CI evaluator enforces partial evaluation, meaning that the minimal amount of a Boolean expression is evaluated once the result can be determined. For example, in the expression:
if FALSE and input( prompt) = "yes" then ...
since the left side of the AND is known to be FALSE, the evaluator ignores the portion of the expression right of the AND. This is referred to as partial evaluation and is common for most programming languages. Besides a performance benefit, partial evaluation prevents unwanted side-effects. In the example above, the user should not see the prompt nor have to input something in that expression since the result is FALSE regardless of what they input. This same partial evaluation logic applies to user defined functions. For instance, in the expression:
if TRUE or myFunc(a, false, "?") = 7 then ...
the user function "myFunc" will not be invoked because the expression is known to be TRUE after the side left of the OR is evaluated and thus the right hand side is not processed.
Online HELP is available for user functions by entering :help functions.
Examples
Input
Syntax: INPUT [NAME=]varname
[[;PROMPT=]prompt ] [[;WAIT=]seconds ]
[[;READCNT=]chars ] [[;DEFAULT=]default_str ]
[;CONSOLE ]
where the new parameters are:
default_str - a string value to be used as a default for varname
if no response is provided by the user.
CONSOLE - an option that causes the prompt to be written to
the system console, and the value for varname to be
read from the console.
The INPUT command assigns a value to a CI variable by reading its value from the $STDIN file, or from the system console. The $STDIN file can be redirected to a disk file so that the INPUT command can be used to read records from a file into a CI variable. CONSOLE input cannot be redirected.
The varname parameter is any variable that can be set with the SETVAR command. The input value provided via $STDIN or by a console operator is stored in this variable. If varname does not already exist, INPUT creates it.
The prompt parameter is a string that is displayed prior to receiving input. If prompt is omitted, INPUT displays nothing, but waits for an input value. If the CONSOLE option is used the prompt is written to the system console and non-highlighting escape sequences are removed. Otherwise, the prompt is written to $STDLIST. To include CI parsing delimiters ("," or ";", etc.) as part of the prompt string, it must be surrounded with quote marks.
The user may optionally select a timed read by specifying the WAIT parameter. The read will be cancelled after seconds seconds. The INPUT command also supports the HPTIMEOUT variable. The length of the timed read is seconds or HPTIMEOUT (in minutes), whichever is smaller, as long one or the other is greater than zero. If a timed read expires, then the pending read terminates and CIWARN 9003 is reported. If the CONSOLE option was selected and the INPUT read times out, the entry in the Reply Information Table (RIT) is removed. The default seconds is zero (0) meaning no timer is set for the read from $STDIN or from the console. If the input times out the variable varname will be set to the default_str value, if specified. The wait value cannot exceed the positive value of the HPTIMEOUT variable.
The user may optionally restrict the number of characters to be read by specifying the READCNT= parameter. For example, if readcnt=1 is supplied, the read will terminate after the 1st character is typed by the user. The behavior is slightly different when the CONSOLE option is used. In this case, the READCNT value is treated as the maximum number of characters allowed in the reply. If the chars value is specified as a negative number, INPUT uses the absolute value. The maximum character count allowed (and the default) is the maximum size of a CI variable, which is currently 1024 characters. However, if the CONSOLE option is specified, chars becomes the maximum length of a legal reply. An operator may be able to type more than chars characters, but an error will be reported by the REPLY command if chars is exceeded. Currently, CONSOLE replies are limited to 31 characters. If chars is zero no read is done from $STDIN, and if the CONSOLE option is used, chars will be set to 31.
The default_str parameter is a string value to be used as a default for varname if no response is provided by the user. No response is indicated if "enter" is pressed with no other input, or if the read has expired due to a timeout. The length of the default_str is not restricted by the chars value. If default_str is omitted and the user provides no input response, varname will be created (if it does not already exist) with a null string value. On the other hand, if varname does exist, its value will not be overwritten on null responses unless default_str is supplied.
The CONSOLE parameter causes INPUT to write the prompt to the system console, and read the value for varname from the console. All of the INPUT command features are available for console input. However, due to some internal restrictions the maximum input size is 31 characters, and the maximum prompt size is approximately 80 characters. Absence of the CONSOLE option increases the input value to the maximum size of a CI variable (1024 characters), and the prompt can be as large as the CI's internal buffer (less the characters needed for the rest of the command).
The INPUT command provides a way to establish an interactive dialog with an executing UDC or command file. The variable varname will always be created by INPUT if it does not yet exist. Varname's value is typically the exact value entered as a response by the user; however, if the user enters no response (either by just pressing the enter key, or via the INPUT read expiring) varname's value is determined as follows:
if a DEFAULT= value is provided that becomes the value for varname.
if no DEFAULT= is specified and varname already exists it is not changed.
if no DEFAULT= and varname does not exist it is created with a value of "" (empty string).
The INPUT command can be used with CI IO redirection to read from a disk file. IO redirection may be specified, but has no meaning, when the CONSOLE option is used.
This command is available in a session, job, or program or in BREAK. Pressing [Break] aborts the execution of this command, without creating or modifying varname. However, break is not detectable when using the CONSOLE option, so it may be wise to always use the WAIT= parameter for console requests.
Examples
It is vital to remember that INPUT does not evaluate expressions, but merely stores all input as a string. If the input value needs to be evaluated then it should be modified via the SETVAR command. For example:
:INPUT bleep
# assume a number was entered
:CALC typeof(bleep)
2, $2, %2 # string
:SETVAR bleep !bleep
:CALC typeof(bleep) # integer
1, $1, %1
The above example reads input (no prompt) from $STDIN and stores the value in a variable named "bleep". Assuming the user enters a number, the second line shows the value is really treated as a string value. The third line evaluates the value of bleep, and as seen in the fourth line, it is now stored as a integer.
INPUT go,"Is the first job ready?";readcnt=1;default=Y;console
The above example writes the prompt "Is the first job ready?" to the system console, accepts a reply of one character, provides a default response of "Y", and stores the result in the CI variable named GO.
INPUT record <*msg
This example reads a single record from the file referred to by the file equation *MSG into the CI variable named RECORD.
Input function
The INPUT() function provides nearly the same functionality as the INPUT command. A minor difference exists regarding the value returned when no input is provided by the user. If no response is provided to the INPUT command, and a default value is also not supplied, and varname already exists then varname will not be modified.
If the INPUT() function is used as in:
:setvar myvar INPUT(prompt)
and no response is provided, and a default value is not supplied, then the INPUT function returns a null string (""). Thus, varname is also set to null, even if it already exists.
Syntax: INPUT([prompt][,wait][,cnt][,default][,'console'])
All parameters work as described for the INPUT command above.
Store-to-disk
All versions of STORE now fully support the ability to send the STORE output to disk rather than to tape. This capability is referred to as "store-to-disk" and used to only be available in the most expensive version of STORE. The RESTORE command has been able to read store-to-disk files since release 6.0.
To create a store-to-disk archive file, try the following:
:file storeout;dev=disc
:purge storeout
:store file1, file2, ... ;*storeout ;show ...
Note that the store-to-disk file should be purged before STORE tries to write to it.
|