Notational Conventions | Using Shadow REXXTOOLS Functions | |
Using Shadow REXXTOOLS Host Commands | Special Shadow REXXTOOLS Variables |
OPEN(
ddname
[,password]Important Note: Optional arguments for REXX functions are positional. That is, if you decide to skip over an optional item, you must use a place holding comma. For example, in the following function call, the first and third arguments are coded; the second argument, which is optional, is skipped:
FUNC('ABC', , 'DEF')Had we wanted to omit both the second and third arguments we would simply have coded:
FUNC('ABC')
{A|B|C}
[,'(option,...)']
{A|B|C}
All other punctuation shown in syntax diagrams (quotation marks,
parentheses, etc.) must be coded exactly as shown.
Using Shadow REXXTOOLS Functions
All syntax diagrams in this manual show the invocation of
Shadow REXXTOOLS functions using the REXX function call syntax:
FUNC(arg1, arg2, arg3,...)You may safely call all Shadow REXXTOOLS functions using this method since they all return values.
CALL FUNC arg1, arg2, arg3,...Functions that are CALLed, return their values in the RESULT special variable.
Quick Tip: Remember when you are converting a function call into a CALL to remove the parentheses from around the arguments. If you forget to do this, REXX will pass all your arguments as one string.
Example:
ddname = 'INDD' options = '(IN,OUT,ADR)' call open 'vsam' , ddname, optionsIn this example, the values for DDNAME and OPTIONS will replace the variable names before the OPEN function executes.
Examples:
'KEY'
'(KEY,SEQ,UPD)'
'(KEY)'
Note: Option strings must not contain leading, trailing,
or imbedded blanks.
Using Shadow REXXTOOLS Host Commands
Shadow REXXTOOLS supplies the following host command environments:
The specific documentation for the commands associated with these host command environments is found this manual and other Shadow REXXTOOLS publications. The following bullets describe the general rules for using host commands:
/* a literal host command */ "vput (var1, var2) shared" /* a concatenation expression with variables */ "allocate fi("||myfile||") da("||mydsn||") shr reu" /* a function call expression that returns the host command to be executed */ makecmd()Host commands composed of REXX expressions are completely evaluated by the REXX interpreter (or compiler) prior to execution. Thus, all that a host command environment ever receives is a character string containing the command to be executed.
The format of the ADDRESS instruction is:
ADDRESS host-command-environment-nameFor example to switch to the REXXTOOL host command environment, you would code:
address rexxtoolIf you are unsure about which environment is in effect, you can use the REXX ADDRESS function to find out what it is. For example:
CurEnvir = address()Programming Tip: It is a good practice to use the ADDRESS instruction liberally. You should put an ADDRESS instruction fairly close to any sequence of host commands. This provides for good documentation (after all, some host command environments have very similar commands), and it can eliminate one of the most common REXX programming errors: sending a host command to the wrong host command environment.
address sql "select * from dsn8310.emp"
address tso "listd mydataset m" if rc <> 0 then do say "An error has occurred. RC='rc exit 8 end
Note: Functions invoked with the REXX CALL instruction will always return a value in the RESULT variable.
Unless stated otherwise, all REXXTOOLS-generated variables contain data that has been converted to the REXX printable format. That is, numbers and addresses of various types are converted to REXX printable decimal numbers or printable hexadecimal strings. However, some data is returned unchanged (e.g., the keys of KSDSs).
WARNING: Modification of some REXXTOOLS generated variables could result in catastrophic program failures. In general, you should never use these variables as the target of any type of assignment (assignment statements, PARSE instructions, EXECIO commands, etc.), unless the documentation specifically indicates that it is safe to do so.