z/OS TSO/E REXX Reference
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF

General considerations for calling TSO/E REXX routines

z/OS TSO/E REXX Reference

Each topic in this book that describes the different TSO/E REXX routines describes how to use the routine, including entry and return specifications and parameter lists. The following topics provide general information about calling TSO/E REXX routines.

All TSO/E REXX routines, except for the initialization routine, IRXINIT, cannot run without a language processor environment being available. A language processor environment is the environment in which REXX operates, that is, in which the language processor processes a REXX exec. REXX execs and TSO/E REXX routines run in a language processor environment.

The system automatically initializes a language processor environment in the TSO/E and non-TSO/E address spaces by calling the initialization routine, IRXINIT. In TSO/E, an environment is initialized during logon processing for TSO/E READY mode. During your TSO/E session, you can invoke an exec or use a TSO/E REXX routine. The exec or routine runs in the environment that was created during logon processing.

If you invoke ISPF, the system initializes another language processor environment for the ISPF screen. If you split the ISPF screen, a third environment is initialized for that screen. In ISPF, when you invoke an exec or TSO/E REXX routine, the exec or routine runs in the language processor environment from which it was invoked.

The system automatically terminates the three language processor environments it initializes as follows:
  • When you return to one screen in ISPF, the environment for the second screen is terminated
  • When you end ISPF and return to TSO/E READY mode, the environment for the first ISPF screen is terminated
  • When you log off TSO/E, the environment for TSO/E READY mode is terminated.

In non-TSO/E address spaces, the system does not automatically initialize a language processor environment at a specific point, such as when the address space is activated. When you invoke either the IRXJCL or IRXEXEC routine to run an exec, the system automatically initializes an environment if an environment does not already exist. The exec then runs in that environment. The exec can then invoke a TSO/E REXX routine, such as IRXIC, and the routine runs in the same environment in which the exec is running. Language Processor Environments describes environments in more detail, when they are initialized, and the different characteristics that make up an environment.

You can explicitly call the initialization routine, IRXINIT, to initialize language processor environments. Calling IRXINIT lets you customize the environment and how execs and services are processed and used. Using IRXINIT, you can create several different environments in an address space. IRXINIT is primarily intended for use in non-TSO/E address spaces, but you can also use it in TSO/E. Customization information is described in more detail in TSO/E REXX customizing services.

If you explicitly call IRXINIT to initialize environments, whenever you call a TSO/E REXX routine, you can specify in which language processor environment you want the routine to run. During initialization, IRXINIT creates several control blocks that contain information about the environment. The main control block is the environment block, which represents the language processor environment. If you use IRXINIT and initialize several environments and then want to call a TSO/E REXX routine to run in a specific environment, you can pass the address of the environment block for the environment on the call. When you call the TSO/E REXX routine, you can pass the address of the environment block either in register 0 or in the environment block address parameter in the parameter list if the routine supports the parameter. By using the TSO/E REXX customizing services and the environment block, you can customize REXX processing and also control in which environment you want TSO/E REXX routines to run. For more information, see Specifying the address of the environment block.

The following information describes some general conventions about calling TSO/E REXX routines:
  • The REXX vector of external entry points is a control block that contains the addresses of the TSO/E REXX routines and the system-supplied and user-supplied replaceable routines. The vector lets you easily access the address of a specific routine to invoke the routine. See Control blocks created for a Language Processor Environment for more information about the vector.
  • All calls are in 31 bit addressing mode.
  • All data areas may be above 16 MB in virtual storage.
  • On entry to an external function or subroutine, register 0 contains the address of the environment block. This address should be passed to any TSO/E REXX programming service invoked from the external function or subroutine. Passing the address of the environment block is particularly important if the environment is reentrant because TSO/E REXX programming services cannot automatically locate a reentrant environment. For more information about reentrant environments, see Using the environment block for reentrant environments.
  • For most of the TSO/E REXX routines, you pass a parameter list on the call. Register 1 contains the address of the parameter list, which consists of a list of addresses. Each address in the parameter list points to a parameter. The high-order bit of the last parameter address must be a binary 1. If you do not use a parameter, you must pass either binary zeros (for numeric data or addresses) or blanks (for character data). For more information, see Parameter lists for TSO/E REXX routines.
  • On calls to the TSO/E REXX routines, you can pass the address of an environment block to specify in which particular language processor environment you want the routine to run. For more information, see Specifying the address of the environment block.
  • Specific return codes are defined for each TSO/E REXX routine. Some common return codes include 0, 20, 28, and 32. For more information, see Return codes for TSO/E REXX routines.

Go to the previous page Go to the next page

Copyright IBM Corporation 1990, 2014