Subsystem interface

The subsystem interface is a mechanism by which the z/OS® operating system communicates with its underlying subsystems at certain critical points in its processing.

CICS® is required to be defined as a formal z/OS subsystem for the following purposes:
  • Multiregion operation (MRO)
  • Shared database support
  • Console message handling

Functional overview

A z/OS subsystem consists of two control blocks and a set of functional routines, all resident in common memory. The control blocks are:
SSCT
The subsystem communication table, which contains the 4-character name of the subsystem and a pointer to the SSVT.
SSVT
The subsystem vector table, which contains a list of the subsystem function codes that the subsystem supports, and the addresses of the functional routines that support them.

The subsystem is active when the SSCT contains a nonzero pointer to the SSVT, and inactive when the pointer is zero.

Subsystem definition

Each subsystem is defined to z/OS by an entry in an IEFSSNxx member of SYS1.PARMLIB. (See the z/OS MVS Initialization and Tuning Guide.) Each subsystem can be defined with an initialization routine and some initialization parameters. The CICS subsystem is defined with an initialization routine of DFHSSIN, and an initialization parameter that specifies the name of an additional member of SYS1.PARMLIB, which contains further CICS-specific subsystem parameters. These parameters specify whether the console message handling facility is required.

When the recommended initialization routine DFHSSIN is specified, the CICS subsystem is initialized during the main scheduler initialization phase of the z/OS IPL. The CICS-specific subsystem parameters are read from SYS1.PARMLIB, and the subsystem vector table is created. The supporting subsystem function routines are loaded into common memory and their addresses are stored into the subsystem vector table. If everything is successful, the CICS subsystem is made active by storing the address of the subsystem vector table in the subsystem communication table.

Design overview: Console message handling

At startup, a CICS region that supports console message handling notifies the CICS subsystem of its existence, by using the CICS SVC to issue a subsystem interface call for the ‘generic connect’ function with a CONNECT subfunction. The subsystem notes the creation of the new region and, if this is the first such CICS region to become active, invokes a service of z/OS console support called “subsystem console message broadcasting”. The message broadcasting service causes all subsequent console messages to be broadcast to all subsystems that have expressed an interest in receiving them, including the CICS subsystem. This z/OS service can also be activated by other products, for example, NetView.

If the message broadcasting service has been activated, either by CICS or by another product, the CICS subsystem examines all messages issued by WTO macros in any address space, but it intercepts and modifies only the following:
  • Messages beginning with “DFH” that are issued under any CICS TCB, including those CICS regions that do not have console message handling support.

    These messages are reformatted to contain the CICS applid for the region in a standard position in the message.

    Because the CICS subsystem receives control after JES has recorded a console message in the job’s message log, messages in the job log do not appear to be reformatted. The messages are only reformatted on the operator consoles and in the z/OS system log.

    If the original message is a long one, inserting the CICS applid can cause the message to exceed the maximum length for a z/OS console message. In this case, the original message is suppressed (that is, does not appear on the console), and the reformatted message is issued using the z/OS multiple-line console message service to split the message text over several lines. Both the original message and perhaps several instances of the reformatted multiple-line message appear in the job log, but only one copy of the reformatted message is displayed on the console.

  • Messages that redisplay, on operator consoles or in the z/OS system log, MODIFY commands that are directed toward CICS and contain signon passwords for the CESN transaction.

    These messages are reformatted with the passwords replaced by asterisks, so that the original passwords are not exposed.

As each TCB terminates, it issues an ‘end of task’ subsystem call, which is broadcast to all active subsystems. Likewise, as each address space terminates, it issues an ‘end of memory’ subsystem call, which is also broadcast to all active subsystems. When it receives either of these calls, the CICS subsystem first calls the end-of-memory routine in DFHIRP; then, if the terminating address space is known by the subsystem, it invokes the ‘generic connect’ function with a DISCONNECT subfunction.

The DISCONNECT subfunction notes the termination of the CICS address space and, if this is the last CICS containing console message handling support to terminate, notifies the “subsystem console message broadcasting” support that the CICS subsystem is no longer interested in receiving broadcast console messages. Nevertheless, if another product has kept console message broadcasting active, the CICS subsystem continues to reformat messages from CICS regions that do not have console message handling support.

Control blocks

DSECT Function
DFHSABDS The CICS subsystem anchor block (SAB). This is used to contain global subsystem-related information that is common to all CICS regions in the z/OS image. It is used to record the options specified in the DFHSSInn member of SYS1.PARMLIB. It contains a pointer to a bit map that records which z/OS address spaces contain an active CICS. It also contains the address of the subsystem control table extension (SCTE) used by IRC, and the address of the z/OS status tracking information used by XRF.
IEFJSCVT The subsystem communication table (SSCT). This is a z/OS control block. There is one SSCT for each subsystem, including the primary job entry subsystem (JES) as well as CICS.
IEFJSSVT The subsystem vector table (SSVT). This is a z/OS control block. There is one SSVT for each active subsystem. It contains a lookup table for determining which function codes are supported by the subsystem, and a list of the entry points for all the supporting function routines.
Figure 1 shows these control blocks.
Figure 1. Control blocks associated with the subsystem interface
Diagram showing the control blocks listed in the table, and their relationships to each other.

Modules

Module Function
DFHSSIN Subsystem initialization routine for the CICS subsystem. Reads in subsystem parameters from member DFHSSInn of SYS1.PARMLIB, creates SSVT, loads function modules into z/OS common storage.
DFHSSEN End-of-task and end-of-memory functional module. Calls DFHIRP’s EOT/EOM routine. Issues ‘generic connect’ if terminating region or job-step task is in the CICS address space map.
DFHSSGC The generic connect functional module. CONNECT subfunction sets the bit for the current address space in the address space map. If this is the first CICS region to start, it invokes IEAVG700 to initiate message broadcasting. DISCONNECT subfunction unsets the bit for the current address space in the address space map. If this is the last CICS region to finish, it invokes IEAVG700 to terminate message broadcasting.
DFHSSMGP Message routine for DFHSSIN.
DFHSSMGT Message table for DFHSSIN.
DFHSSWT Router module for the console message handler. Calls DFHSSWTO for messages beginning with DFH. Calls DFHSSWTF for messages that echo MODIFY commands.
DFHSSWTF Suppresses passwords from the echoed copies of MODIFY CICS commands that contain signon passwords.
DFHSSWTO Inserts the applid into all DFH messages issued under a TCB with a valid AFCB.

Exits

There are no user exits in the subsystem interface support.

Trace

No tracing is performed by the subsystem interface support.

External interfaces

Module DFHSSIN invokes the z/OS module IEEMB878 to read its initialization parameters from SYS1.PARMLIB.

Module DFHSSGC invokes the z/OS module IEAVG700 to start and stop console message subsystem broadcasting.

Modules DFHCSVC and DFHSSEN use the IEFSSREQ interface to communicate with the CICS subsystem.