How to Use Shadow REXXTOOLS

The following sections describe how to code REXXTOOLS host commands and functions.

Notational Conventions Using Shadow REXXTOOLS Functions
Using Shadow REXXTOOLS Host Commands Special Shadow REXXTOOLS Variables

Notational Conventions

Throughout this manual the following notational conventions are used:
Uppercase
Uppercase text shows items that must be coded exactly as shown. For example:
OPEN(
Lowercase
Lowercase text is used to indicate values which the user must supply. Example:
ddname
Brackets
[ ] are used around optional items. For example, the following item may or may not be coded:
[,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')
Braces
{ } are used around items where one (and only one) of the listed choices may be coded. Example:
{A|B|C}
OR
| is used to separate choices in a list of items. Only one of the items in the list may be coded (see previous example).
Ellipses
... are used whenever an item (or group of items) may be repeated. Example:
[,'(option,...)']
Underscore
Underscored items are used to indicate default values (i.e., the value that will take effect if you do not code an item). Example:
{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.

Using the CALL Instruction

You may invoke any Shadow REXXTOOLS function using the REXX CALL instruction as is shown below:
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.

Using REXX Variables for Arguments

Throughout this manual, many examples depict arguments to Shadow REXXTOOLS functions as numeric or character literals. However, as with all REXX functions, you may use REXX variables or even complex expressions to supply argument values. REXX always performs expression evaluation and variable substitution before invoking a function.

Example:

ddname = 'INDD'
options = '(IN,OUT,ADR)'
call open 'vsam' , ddname, options
In this example, the values for DDNAME and OPTIONS will replace the variable names before the OPEN function executes.

Coding Option Strings

Option strings are single character string arguments that contain one or more processing options. Unless stated otherwise, when only one option is to be passed, the option may appear by itself with no other punctuation. If several options are to be specified, they must be enclosed within parentheses and separated by commas (not blanks).

Examples:

  1. Single option:
    'KEY'
    
  2. Multiple options:
    '(KEY,SEQ,UPD)'
    
  3. This is OK too:
    '(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:
REXXTOOL
supports commands for dynamic allocation, global variables, and REXXTOOLS configuration.
IDCAMS
for issuing IDCAMS commands
SQL
for executing DB2/SQL statements (Dynamic DB2/SQL Service only).

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:

Special Shadow REXXTOOLS Variables

Many Shadow REXXTOOLS functions and host commands return information in specially named REXX variables. The "Returned Information" section of each service lists and describes these variables. In general, service return codes are returned in the RC variable. Reason code information is returned (when applicable) in the REASON variable. Some REXXTOOLS services may create additional variables. Consult the service's description for more information concerning the variables it creates.

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.


© Copyright 1998 by Open Software Technologies, Inc.