Basic structure of REXX execs running under CICS

REXX for CICS® TS provides a main interface program named CICREXD for the REXX Development System, and CICREXR for the REXX Runtime Facility, which is used to load and issue REXX execs within a CICS region.

Each REXX exec runs under a separate CICS task. Any nested REXX execs run under the CICS task of the parent exec.

Note: To determine whether the exec is running in the development system or the runtime facility, you can use the GETVERS command. See GETVERS.

REXX exec invocation

  • Execs started from a terminal

    CICS uses transaction identifiers associated with programs to determine which programs to execute. REXX for CICS TS uses a table created by the REXX DEFTRNID command to associate CICS transaction identifiers with specific REXX execs. The CICS transaction identifier associated with the REXX supplied exec, CICRXTRY, is known as the default REXX transaction identifier. The supplied default is REXX.

    If REXX alone is entered from a CICS screen, the CICRXTRY exec is started. If other operands are specified, for example: REXX MYEXEC ABC, the exec MYEXEC is started and ABC is passed to it as an argument. CICS transaction identifiers other than the REXX default transaction identifier cause the associated exec to be started and any other operands are passed as an argument to the exec. For example, EDIT TEST.EXEC causes the REXX editor exec, CICEDIT, to start and TEST.EXEC, the argument, names the file to edit or create. All REXX transaction identifiers must have CICS definitions that associate them with the REXX main module, CICREXD.

  • Execs started using a CICS START command

    REXX execs can be started by using the CICS START command. The START command names the CICS transaction identified to start and the table created by the REXX DEFTRNID command names the exec to start.

    If the exec is CICRXTRY and CICS start data is present, the first operand names the exec to start and any other operands are passed to the exec as an argument. If no start data is present, CICRXTRY is started.

    For execs other than CICRXTRY, start data is passed to the exec as an argument. Usually, REXX execs have a terminal associated with them. However, if a REXX exec does not have a terminal associated to the transaction, any terminal output is either discarded or directed to a CICS temporary storage queue as specified by the REXX SET TERMOUT command. An error is generated if terminal input is requested for a transaction for which no terminal is associated.

  • Execs started using a CICS LINK or XCTL command
    The REXX interface program, CICREXD or CICREXR, can be invoked by using the CICS LINK or XCTL command. A COMMAREA must be passed to the interface program when invoked in this way.
    • If a CICS LINK is used to invoke REXX, the communications area must be at least 16 characters in length. The first four characters are used to return a completion code to the calling application. This completion code is a return code of REXX for CICS TS processing, not the return code of the called exec. The next 12 characters are reserved for future use. Data that follows the 16 character prefix can be used to pass a blank delimited REXX exec name, and arguments to be passed to the exec. An exec started with CICS LINK must run in conversational mode. This is necessary to protect the caller's storage for returning to the calling application.
    • If CICS XCTL is used to invoke REXX, the communications area might contain an MVS SIB type 1 control block. If a SIB is not used, the area must be at least 16 characters long. The 16 character prefix is reserved for future use. Data that follows the 16 character prefix can be used to pass a blank delimited REXX exec name, and arguments to be passed to the exec.
  • Execs issued from an MVS SIB type 1 control block

    REXX execs can be invoked from OfficeVision or MVS by an Application Type Description (ATD). When creating an ATD, use XCTL or START for the invocation. If you use XCTL, use CICREXD or CICREXR as the application program. If you use START, place the default transaction ID for REXX forCICS TS (for example, REXX) in the application program field.

    There are two ways to pass the exec name and any parameters:
    • The MSG-TEXT field - (MSG-REDEF = '1')
    • The Parameter Description Record (PDR) - 'REXXEXEC'

    The MSG-TEXT field is filled in with the data keyed on the command line if the ATD name and at least one parameter is specified. If the PDR REXXEXEC is used, the exec name plus any parameters needed must be in the data area for the PDR. If both the MSG-TEXT and the PDR REXXEXEC are used, the data in the MSG-TEXT takes precedence. If neither of the two are used, the REXXTRY interactive utility (CICRXTRY exec) is invoked.

Note: A utility called REXXTRY (CICRXTRY exec) is provided with REXX for CICS TS that allows the interactive execution of REXX instructions and REXX commands. To invoke this utility, enter the REXX transaction identifier associated with CICRXTRY without any operands.

Where execs execute

REXX execs are executed as part of the CICS task that issues them, within the CICS region. The REXX interpreter is fully reentrant and runs above the 16 megabyte line (AMODE=31, RMODE=ANY).

Locating and loading Execs

The following rules are used to locate and load an exec into storage so it can be started:
  1. Execs loaded into storage using EXECLOAD are searched and if the exec is found, the copy that is loaded by EXECLOAD is used.
  2. The user's current RFS directory, as defined by the REXX CD command, is searched. If found, the exec is loaded and started.
  3. The user's path, as defined by the REXX PATH command, is searched. If found, the exec is loaded and started.
  4. If the user is an authorized user, data sets specified with the ddname of CICAUTH in the CICS startup JCL are searched.. If the exec is found, it is loaded and started.
  5. Data sets specified with the ddnames of CICEXEC and CICUSER, in that order, are searched. If the exec is not found, an error code is returned.

Editing execs

If the REXX Development System is installed, REXX execs can be edited by using the supplied REXX editor. See REXX editor. Also, if REXX execs reside in a z/OS® PDS, they can be edited using the ISPF/PDF editor under TSO (or other compatible editors).

The sequence numbers are not allowed in columns 73 through 80 of REXX execs.

REXX file system

Execs can be stored as members in the VSAM-based REXX File System (RFS), provided with REXX for CICS TS, or in z/OS partitioned data sets. See REXX for CICS TS: File system.

Note: If the file identifier you specified for invoking an exec does not include a file type extension, only RFS file identifiers with a file type of EXEC are searched when you attempt to locate and issue the REXX exec. If the file identifier includes a file type extension, only RFS files with a matching file type are searched (when you attempt to locate and run the exec). For z/OS PDS searches, only the file name is compared to the PDS member name.

Control of exec execution search order

The CD and PATH commands define the search order of user REXX libraries when you attempt to load an exec. After the current directory (set by the CD command) is searched, all directories specified with the PATH command are searched, followed by system PDS libraries specified in the startup JCL for the CICS region. For more detailed information on the search order, see Functions and subroutines.

Adding user-written commands

An exec can be defined so that it can be invoked as a REXX command. The DEFCMD command is used to define REXX user commands. DEFCMD supports commands written in REXX as well as the standard CICS supported languages. See DEFCMD.