# 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:

- A host command is any REXX expression that is not one of the REXX language instructions. For example, all of the following expressions will be recognized by REXX as 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.
- Host commands are always directed to the current host command environment. When a REXX program starts, a default host command environment is in effect until you use the REXX ADDRESS instruction to switch to another one.

  The format of the ADDRESS instruction is:

      ADDRESS host-command-environment-name

  For example to switch to the REXXTOOL host command environment, you would code:

      address rexxtool

  If 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.
- A single host command can be directed to a specific host command environment without changing the current host command environment. To do this you code the host command immediately after the ADDRESS instruction. For example:

      address sql "select * from dsn8310.emp"

- All host commands set the RC variable. As with any service call, you should always check the RC value (and other relevant variables that may be set by the host command) to ensure that the operation was successful. For example:

      address tso
      "listd mydataset m"
      if rc <> 0 then do
        say "An error has occurred. RC='rc
        exit 8
      end

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