In addition to the REXX language instructions and built-in functions, and the TSO/E external functions and REXX commands that are provided for writing REXX execs, TSO/E provides programming services for REXX processing. Some programming services are routines that let you interface with REXX and the language processor.

In addition to the TSO/E REXX programming services that are described in this chapter, TSO/E also provides various routines that let you customize REXX processing. These are described beginning in TSO/E REXX customizing services. TSO/E also provides replaceable routines that handle system services. The routines are described in Replaceable routines and exits. Whenever you invoke a TSO/E REXX routine, there are general conventions relating to registers that are passed on the call, parameter lists, and return codes the routines return. General considerations for calling TSO/E REXX routines highlights several major considerations about calling REXX routines.

The REXX programming services TSO/E provides are summarized below and are described in detail in the individual topics in this chapter.

IRXJCL and IRXEXEC Routines: IRXJCL and IRXEXEC are two routines that you can use to run a REXX exec in any MVS™ address space. Both IRXEXEC and IRXJCL are programming interfaces to the language processor.

You can use IRXJCL to run a REXX exec in MVS batch by specifying IRXJCL as the program name (PGM= ) on the JCL EXEC statement. You can also invoke IRXJCL from a REXX exec or a program in any address space to run a REXX exec.

You can invoke IRXEXEC from a REXX exec or a program in any address space to run a REXX exec. Using IRXEXEC instead of the IRXJCL routine or, in TSO/E, the EXEC command processor to invoke an exec provides more flexibility. For example, you can preload the exec in storage and then use IRXEXEC to run the exec. Exec processing routines - IRXJCL and IRXEXEC describes the IRXJCL and IRXEXEC programming interfaces in more detail.

External Functions and Subroutines, and Function Packages: You can extend the capabilities of the REXX programming language by writing your own external functions and subroutines that you can then use in REXX execs. You can write an external function or subroutine in REXX. For performance reasons, you can write external functions and subroutines in either assembler or a high-level programming language and store them in a load library. You can also group frequently used external functions and subroutines into a function package, which provides quick access to the packaged functions and subroutines. When a REXX exec calls an external function or subroutine, the function packages are searched before load libraries or exec data sets, such as SYSEXEC and SYSPROC. See Search order for a description of the complete search order.

If you write external functions and subroutines in any programming language other than REXX, the language must support the system-dependent interfaces that the language processor uses to invoke the function or subroutine. If you want to include an external function or subroutine in a function package, the function or subroutine must be link-edited into a load module. External functions and subroutines, and function packages describes the system-dependent interfaces for writing external functions and subroutines and how to create function packages.

Variable Access: TSO/E provides the IRXEXCOM variable access routine that lets unauthorized commands and programs access and manipulate REXX variables. Using IRXEXCOM, you can inspect, set, or drop variables. IRXEXCOM can be called in both the TSO/E and non-TSO/E address spaces. Variable access routine - IRXEXCOM describes IRXEXCOM in detail.

Maintain Host Command Environments: When a REXX exec runs, there is at least one host command environment available for processing host commands. When an exec begins running, an initial environment is defined. You can change the host command environment using the ADDRESS instruction (see ADDRESS).

When the language processor processes an instruction that is a host command, it first evaluates the expression and then passes the command to the active host command environment for processing. A specific routine defined for the host command environment handles the command processing. TSO/E provides several host command environments for execs that run in non-TSO/E address spaces and in the TSO/E address space (for TSO/E and ISPF). Commands to external environments describes how you issue commands to the host and the different environments TSO/E provides for MVS (non-TSO/E), TSO/E, and ISPF.

The valid host command environments, the routines that are invoked to handle command processing within each environment, and the initial environment that is available to a REXX exec when the exec begins running are defined in a host command environment table. You can customize REXX processing to define your own host command environment and provide a routine that handles command processing for that environment. TSO/E REXX customizing services describes how to customize REXX processing in more detail.

TSO/E also provide the IRXSUBCM routine that lets you access the entries in the host command environment table. Using IRXSUBCM, you can add, change, and delete entries in the table and also query the values for a particular host command environment entry. Maintain entries in the host command environment table - IRXSUBCM describes the IRXSUBCM routine in detail.

Trace and Execution Control: TSO/E provides the trace and execution control routine, IRXIC, that lets you use the HI, HT, RT, TS, and TE commands to control the processing of REXX execs. For example, you can invoke IRXIC from a program written in assembler or a high-level language to control the tracing and execution of execs. Trace and execution control routine - IRXIC describes the IRXIC routine in detail.

Get Result Routine: TSO/E provides the get result routine, IRXRLT, that lets you obtain the result from a REXX exec that was invoked using the IRXEXEC routine. You can also use IRXRLT if you write external functions and subroutines in a programming language other than REXX. IRXRLT lets your function or subroutine code obtain a large enough area of storage to return the result to the calling exec. The IRXRLT routine also lets a compiler runtime processor obtain an evaluation block to handle the result from a compiled REXX exec. Get result routine - IRXRLT describes the IRXRLT routine in detail.

SAY Instruction Routine: The SAY instruction routine, IRXSAY, lets you write a character string to the same output stream as the REXX SAY keyword instruction. SAY instruction routine - IRXSAY describes the IRXSAY routine in detail.

Halt Condition Routine: The halt condition routine, IRXHLT, lets you query or reset the halt condition. Halt condition routine - IRXHLT describes the IRXHLT routine in detail.

Text Retrieval Routine: The text retrieval routine, IRXTXT, lets you retrieve the same text that the TSO/E REXX interpreter uses for the ERRORTEXT built-in function and for certain options of the DATE built-in function. For example, using IRXTXT, a program can retrieve the name of a month or the text of a syntax error message. Text retrieval routine - IRXTXT describes the IRXTXT routine in detail.

LINESIZE Function Routine: The LINESIZE function routine, IRXLIN, lets you retrieve the same value that the LINESIZE built-in function returns. LINESIZE function routine - IRXLIN describes the IRXLIN routine in detail.