Environment

Review Function Routines/Function Codes, which describes both the general environment on entry to your function routine and other programming considerations that your function routine should take into account.

If you decide to set up your subsystem to handle WTO/WTOR calls, make sure that your function routine is in place before you enable the subsystem to handle SSI function code 9. IBM® recommends that you use the IEFSSVT macro to notify MVS™ that your subsystem should be given control whenever WTO/WTOR calls are made. IEFSSVT macro services are available only to dynamic subsystems. Subsystems that are not dynamic can still use the IEFJSVEC service; see Building the SSVT and Enabling Your Subsystem for New Functions for more information.

WTOs occur frequently on MVS. Function routines should therefore be as efficient as possible. Function routines should never enter a WAIT and should never use system services that have implied WAITs (such as I/O). Entering a WAIT can cause degraded system performance.

Data areas commonly referenced are mapped by the following mapping macros. IBM recommends you include them in your function routine:

IEFSSOBH
IEFJSSIB
IEFSSWT
IHAWQE
IHAORE

The write-to-operator WTO queue element (WQE), mapped by IHAWQE, represents a message.

The operator reply element (ORE), mapped by IHAORE, represents a WTOR.

The function routine receives control in the following environment:

Environment variable	Value
Minimum authorization	Supervisor state with PSW key 0
Dispatchable unit mode	Task
AMODE	24-bit or 31-bit
Cross memory mode	PASN=HASN=SASN
ASC mode	Primary
Interrupt status	Enabled for I/O and external interrupts
Locks	No locks held
Control parameters	The SSOB, SSIB, SSWT, and WQE control blocks reside in storage below 16 megabytes. The ORE control block resides above 16 megabytes.
Recovery	The function routine should provide an ESTAE-type recovery environment. See z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG for more information on these macros. Failure to establish a recovery environment causes the current message to be deleted from the system, if the function routine ends abnormally while processing the message. The function routine's recovery should specify a retry point (address) and return 4 on the SETRP macro before returning to system. The retry point should be used to complete a normal return to the function routine's caller. When the function routine returns to its caller under these circumstances, it should indicate to the system to take no action against the message by setting both register 15 and the SSOBRETN to zero. See Input Register Information for more information about specifying to the system the action that should be taken by your function routine. Note: Although the system supports AMODE=24 SSI routines monitoring function code 9, IBM recommends converting these SSI routines to AMODE=31. In a future release, IBM may change the location of the SSOB, SSIB, SSWT, and WQE control blocks to reside in 31-bit storage.