IXGSEXIT — Log Stream Subsystem Exit

Topics for This Exit Appear as Follows:

Installing the Exit
Exit Routine Environment
- Linkage Conventions
- Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
- Registers at Entry
Return Specifications
- Registers at Exit

If the log stream owner has special processing considerations, the log stream subsystem exit must be modified.

Note: The log stream subsystem exit can support applications that use QSAM and BSAM (GET and READ) requests in a sequential fashion. The exit cannot support applications that attempt to use other access method services when processing the records maintained in a log stream. If other access method services are required by the application or if the application does not intend to obtain records in a sequential fashion, you will need to update the application to make use of the system logger services. QSAM and BSAM access methods support approximately 32K record sizes. A log stream log block can have record lengths of up to 64K-4. If log blocks (no blocking) or individual records are written with a size greater than what the access methods allow, then applications using the LOGR subsystem will not be able to obtain entire records.

The log stream subsystem exit receives control at six different points in the processing of an application's JCL DD statement that has the SUBSYS=(LOGR,exit_routine_name,...) specification. Each point causes the exit routine to be invoked when the DD with the SUBSYS specification is encountered, with the exception of the GET request. The exit receives control during GET processing once per GET request from the requesting application.

You can use the log stream subsystem exit to:

At the converter exit point:
- Validate the JCL parameters on the DD's SUBSYS keyword.
- Cause system-type messages to be issued to the job's log.
- Cause the job to end processing because of a JCL error.
At the allocation exit point:
- Validate the JCL parameters on the DD's SUBSYS keyword.
- Cause system-type messages to be issued to the job's log.
- Cause the job to end processing because of a JCL error.
- Establish data areas or obtain resources that will be persistent throughout the other exit points.
At the open exit point:
- Connect to the system logger log stream.
- Start the log stream browse session.
At the get exit point:
- Return a record to the requesting application.
At the close exit point:
- End the log stream browse session.
- Disconnect from the system logger log stream.
At the unallocation exit point:
- Cause unneeded log blocks to be deleted from the log stream.
- Disconnect from the system logger log stream.
- Return data areas or resources that were obtained in prior exit event calls.

Installing the Exit

The log stream subsystem exit must be linkedited in its own load module into SYS1.LINKLIB or any APF-authorized library in the LNKLST concatenation. To activate the exit routine, refresh LLA through the MODIFY LLA,REFRESH command.

The name of the exit is determined by the log stream owner and must match the value in the second positional parameter of the SUBSYS=(LOGR,exit_routine_name,...) DD JCL specification for applications that intend to access records from the owner's log stream. The name of the exit must also match its load module and entry point names. It is the responsibility of the log stream owner to provide the exit routine name to applications that will use the exit. If an exit routine name is not specified on the SUBSYS=(LOGR,exit_routine_name,...) statement, IXGSEXIT will be used as a default exit.

Note: To use the log stream subsystem exit, the LOGR subsystem must be activated. See z/OS MVS Setting Up a Sysplex for more information.

Exit Routine Environment

The log stream subsystem exit receives control in the following environment:

Task mode
Enabled for interrupts and unlocked
Primary ASC mode

As Table 1 shows, other environmental factors for the log stream subsystem exit routine are based on the event that causes the routine to be invoked.

Table 1. Environmental factors for the log stream subsystem exit routine
Event	Authorization	AMODE	Cross Memory Mode	Restrictions
Converter	Supervisor state with PSW key 1	31	PASN = HASN, any SASN	The control blocks passed to the exit routine do not reside in the application's address space. The application's address space might even be on a different processor than where converter processing is occurring.
Allocation	Supervisor state with PSW key 1	31	PASN = HASN, any SASN	The control blocks passed to the exit routine reside in the application's address space.
Unallocation	Supervisor state with PSW key 1	31	PASN = HASN, any SASN	The control blocks passed to the exit routine reside in the application's address space.
Open	Supervisor state with PSW key 1	31	PASN = HASN, any SASN	The control blocks passed to the exit routine reside in the application's address space.
Close	Supervisor state with PSW key 1	31	PASN = HASN, any SASN	The control blocks passed to the exit routine reside in the application's address space.
Get	Problem state with PSW key of the application (typically key 8)	31	PASN = HASN, any SASN	The control blocks passed to the exit routine reside in the application's address space.

Linkage Conventions: The log stream subsystem exit is invoked via BALR R14,R15 for each event or purpose.

Exit Recovery: The log stream subsystem exit routine should provide its own recovery. If it does not provide a recovery routine, or if an exit routine error percolates beyond the exit's recovery, the system's ESTAEX recovery routine will get control. The ESTAEX will record information in the SDWA and request an SDUMP.

If the exit abends, the system will not allow the current point to continue. Based on the specific point, an abend in the exit may cause the job or application to end. If the exit abends, however, and the log stream owner provides recovery that returns to the normal return point of the invoking routine, the LOGR subsystem will not cause the job or application to end.

Exit Routine Processing

The processing in the exit depends on which point caused the exit to be invoked.

The exit is invoked with register 1 pointing to a word that contains the address of the common parameter list for the exit (IXGSXCMP). Code your exit routine to check IXGSXCMP_EVENT for the type of call for which it was invoked. The IXGSXCMP parameter list contains common information to all the exit calls. In addition, field IXGSXCMP_SPECIFIC_PTR points to the specific point's parameter list extension.

Converter Call

The log stream subsystem exit receives control during JCL converter processing each time a DD statement containing a SUBSYS=(LOGR,exit_routine_name,...) is encountered. The purpose of this call is to validate the JCL parameters. It is not meant to build any control blocks based on the JCL parameters; because this processing runs in a different address space, possibly on a different system from the actual job processing, any control blocks built during this call would not be accessible during later calls.

Prior to the log stream subsystem exit getting control, the LOGR subsystem validates and checks the syntax of the SUBSYS parameters with the exception of SUBSYS-options2. If there are any errors, an error return code is returned to the converter. Otherwise, the log stream subsystem exit is invoked.

When the log stream subsystem exit routine receives control, it can also validate the input JCL, especially the SUBSYS-options2 parameters. The SUBSYS-options2 parameters are unique to each exit, and so the exit must check for syntax errors.

If there are no errors, the job continues processing. If a parse error occurs, the job ends. If the system provided an error message describing the parse error, the message will be returned so that it can be placed in the job log. If an abend occurs, the job ends.

Allocation Call

The log stream subsystem exit receives control during allocation processing each time a DD statement containing a SUBSYS=(LOGR,exit_routine_name,...) is encountered. The exit can perform similar processing as for the converter call (dynamic allocation does not go through converter processing). You can set field IXGSXCMP_EXIT_TOKEN to be used as input for the other exit calls.

Prior to the log stream subsystem exit getting control, the LOGR subsystem validates and checks the syntax of the SUBSYS parameters with the exception of the SUBSYS-options2. If there are any errors it will return an error return code to allocation. Otherwise it will invoke the log stream subsystem exit routine.

Open Call

The log stream subsystem exit receives control during OPEN processing each time a DD statement containing a SUBSYS=(LOGR,exit_routine_name,...) is encountered.

When the log stream subsystem exit routine receives control, it might ensure that the log stream can be accessed by the current job or application. When a log stream connect is issued using the IXGCONN macro, system logger processing will perform the SAF authorization checking. The xstreamname to be used on the connect can be obtained from field IXGSXCMP_LOGNAME in data area IXGSXCMP.

After the log stream is connected, the log stream subsystem exit can start a browse session. See z/OS MVS Programming: Assembler Services Guide for more information about a browse session. The SUBSYS parameters have been processed by the LOGR subsystem and the values have been corrected in fields in the IXGSXCMP parameter list. If some of these keywords are not specified, defaults were used. Logger can add new parameters on the SUBSYS-options1 set. New parameters that are added to this set are done in a compatible manner. It is up to the exit routine owner to provide additional support to take advantage of the new options. For example, the VIEW= ACTIVE | ALL | INACTIVE options were newly added as maintenance on HBB6608 and higher releases and on JBB7713.

The exit needs to save the log stream connect token and browse token for use on GET exit calls to browse the log stream data. The exit needs to save the browse token for use on GET exit calls.

The name of the routine to process the GET requests can be provided in the IXGSXOCP parameter list. This allows a separate exit routine to be invoked and operate in problem program state and key 8. It might make the exit routine's structure and processing easier to provide a separate routine to handle the GET requests.

When the exit returns to the LOGR subsystem, control returns to OPEN processing. If there are no errors, the job continues. If the request was unsuccessful, DFSMS issues an abend for the open failure.

Get Call

The log stream subsystem exit receives control during GET processing each time a GET request from the requesting application containing a SUBSYS=(LOGR,exit_routine_name,...) is encountered. The intent of this exit call is to allow a log stream owner the ability to return records from a log stream as if they were being obtained from a conventional data set. This is for QSAM or BSAM requests only.

On GET requests, the LOGR subsystem sets up the input parameter list and passes control to the log stream subsystem exit. The log stream subsystem exit receives control in the application's state and key (typically problem state, key 8).

The exit routine obtains log stream blocks, deblocks and formats the logical records, if appropriate, and returns them to the application.

After the exit routine returns, the LOGR subsystem returns control to GET processing with a normal or error return code.

Close Call

The log stream subsystem exit receives control during CLOSE processing each time a DD statement containing a SUBSYS=(LOGR,exit_routine_name,...) is encountered.

When the log stream subsystem exit routine receives control, it might end the log stream browse session established during the Open exit call.

When the exit returns to the LOGR subsystem, control returns to CLOSE processing. If there are no errors, the job continues. If the request was unsuccessful, DFSMS issues an abend for the close failure.

Unallocation Call

The log stream subsystem exit receives control during Unallocation processing each time a DD statement containing a SUBSYS=(LOGR,exit_routine_name,...) is encountered.

The exit might need to invoke other system logger functions prior to disconnecting from the log stream. For example, the exit can invoke the IXGDELET service to delete log stream blocks from the oldest to the block just before a specified blockid. Optionally, all the log stream blocks can be deleted on the request.

The exit should ensure that all resources that were obtained during the other exit calls are returned to the system. For example,

IXGCONN REQUEST=DISCONNECT,STREAMNAME=xstreamname,
        STREAMTOKEN=xstreamtoken,...

The xstreamname to be used on the disconnect can be obtained from field IXGSXCMP_LOGNAME in data area IXGSXCMP. The xstreamtoken is the value returned on the previous log stream connect request for this DD statement.

If the exit used field IXGSXCMP_EXIT_TOKEN as an anchor for keeping persistent data across the exit calls, then the storage should be returned to the system.

If there are no errors, the job continues.

Programming Considerations

If the log stream owner does not have any special processing requirements for handling the SUBSYS parameters and interfacing with the system logger, the system logger default exit routine, IXGSEXIT, may be suitable to satisfy the processing requirements.

You might not want to use IXGSEXIT. You might want to code your own exit routine, for any number of reasons, including:

Data read from the log stream need to be de-blocked. For example, data might now be written to a log stream in log blocks that contains more than one record of data per block. IXGSEXIT returns only one entire block of data to the caller for each read request.
Additional processing features are required. IXGSEXIT supports only the FROM, TO, DURATION, and VIEW keywords of the LOGR subsystem. See z/OS MVS Programming: Assembler Services Guide for more information about the LOGR subsystem keywords.
IXGSEXIT tries again when a system logger service returns a log stream or a resource-temporarily-unavailable condition.

Consider the following scenario, in which you are given three options. You have an application that writes data to one data set per system in a sysplex. Some users of your application have written tools to read the data using QSAM/BSAM.

After installing MVS™ 5.2, you change your application to write to a single log stream instead of to system data sets.

You now have three choices:

Inform your users that they have to write new code and use system logger services to read the data.
Inform your users that they have to change their JCL and use the LOGR subsystem with default exit IXGSEXIT.
Write a log stream subsystem exit with more features than IXGSEXIT, and inform your users to change their JCL to use the LOGR subsystem with your exit.

If you decide to write your own log stream subsystem exit, code the exit routine to be reentrant. A new copy of the exit is loaded into storage from SYS1.LINKLIB for each application that specifies the appropriate SUBSYS parameters to obtain records from a log stream.

Converter Call
The conversion of a job's JCL will take place in a different address space and potentially on a different system image from where the application will run. The exit routine should not attempt to keep persistent data from this invocation of the exit to the other invocations of the exit.
Allocation Call
The allocation invocation of the exit provides a mechanism for the exit to obtain persistent data that can be used in the other invocations of the exit.

Field IXGSSCMP_EXIT_TOKEN can be set by the log stream subsystem exit routine during the allocation call and it will then be input to the next exit call for this DD statement.

It is the responsibility of the exit routine to ensure that the resources it obtains are released. If the exit routine obtains any resources that are not explicitly job related, such as common storage, a resource manager routine may need to be established. If an abnormal memory end occurs, close and unallocation processing do not occur, so the exit routine will not receive control through this exit interface.

Note: Log stream data sets can be concatenated. No special processing by the exit is necessary to handle this other than recognizing that the DDname (field IXGSXAP_DDNAME in the IXGSXAP data area) can be blank. The system automatically goes through open and close functions for each data set although the application does not issue them for each data set.
Open Call
Field IXGSSCMP_EXIT_TOKEN can be used to pass data from the Allocation call to the Open exit routine. It can also be set as output from the Open exit routine to pass data to the subsequent log stream subsystem exit invocations.

It is the responsibility of the log stream subsystem exit to establish the correct connection and references to the log stream.

It is possible that Logger will add new parameters on the SUBSYS-options1 set. New parameters that are added to this set are done in a compatible manner. It is up to the exit routine owner to provide additional support to take advantage of the new options. For example, the VIEW= ACTIVE | ALL | INACTIVE options were newly added as maintenance on HBB6608 and higher releases and on JBB7713.

The exit needs to save the log stream connect token and browse token for use on GET exit calls to browse the log stream data.

An end of file condition may be encountered via a specific return/reason code from the IXGBRWSE API or as a result of the exit routine determining that no data meets the input criteria. If the exit routine returns an error condition on the Open call, then DFSMS will fail/ABEND the DD OPEN request. To avoid the OPEN failure condition, the exit routine could indicate the end of file condition in its persistent data area and use that indication on the first GET call. This allows the program that is attempting to read the log stream data to simply receive an end of file (or end of data) condition vs. an OPEN failure.
Get Call
Any special deblocking or formatting of records from a log stream block needs to be performed during this call.

The GET exit routine should recognize any special conditions established during the Open call exit routine processing.
Close Call
It is possible for an application to not issue an OPEN for a DD that was allocated. In addition, a DD that was opened cannot be explicitly closed by the application. The exit routine must ensure that it recognizes these conditions and returns resources to the system accordingly.
Unallocation Call
When the exit routine is invoked for unallocation, all resources that were obtained by the exit should be returned.

It is the responsibility of the exit routine to ensure that the resources it obtains are released. If the exit routine obtains any resources that are not explicitly job related, such as common storage, a resource manager routine may need to be established. If an abnormal memory end occurs, close and unallocation processing do not occur, so the exit routine will not receive control through this exit interface.

It is possible for an application to not issue an OPEN for a DD that was allocated. In addition, a DD that was opened may not be explicitly closed by the application. The exit routine must ensure that it recognizes these conditions and returns resources to the system accordingly.

Entry Specifications

The LOGR subsystem passes a standard format parameter list and linkage on entry to the log stream subsystem exit routine.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Pointer to a full word field containing the address of the log stream subsystem exit common parameter list (IXGSXCMP). The high-order bit in the full word field pointed to by register 1 is set on ('1'b) to indicate the end of the input parameter list.
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of the exit

The contents of the registers on entry to this exit are: See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the following data areas, which are used as parameter lists: IXGSXCMP, IXGSXCNP, IXGSXAP, IXGSXOCP, IXGSXGP, IXGSXUP, IXGSXMSP, and IXGSXTXT.

Return Specifications

The exit can return information in specific output fields in the parameter list and in register 15 to indicate a return code.

Output Parameter Descriptions, Converter are as follows.

IXGSXCNP_ISSUE_MSG: Issue message indicator. The message contained in the area pointed to by IXGSXCNP_MSG_PTR is to be issued as part of the system messages in the job's log. The message area contains a halfword length field followed by the message text. The length of the message text does not include the 2-byte prefix. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for data area IXGSXMSP.

Output Parameter Descriptions, Allocation are as follows

IXGSXCMP_EXIT_TOKEN: Exit token. The value returned in this field will be provided as input to the next exit call for this DD.
IXGSXAP_ISSUE_MSG: Issue message indicator. The message contained in the area pointed to by IXGSXAP_MSG_PTR is to be issued as part of the system messages in the job's log (during batch allocation). The message area contains a halfword length field followed by the message text. The length of the message text does not include the 2-byte prefix. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for data area IXGSXMSP.
IXGSXAP_INFO_CODE: DD error information code. Passed back to allocation to identify the reason why the allocation for the DD statement failed.

Output Parameter Descriptions, Open are as follows.

IXGSXCMP_EXIT_TOKEN: Exit token. The value returned in this field will be provided as input to the next exit call for this DD statement.
IXGSXOCP_IOEXIT_NAME: Name of the routine to be invoked on GET requests. This routine will be loaded into storage and called for the GET exit processing. The field is initialized with the exit name specified as the second positional parameter on the SUBSYS keyword.

Output Parameter Descriptions, GET are as follows.

IXGSXGP_RETURN_CODE

Return code to be passed to the issuer of the GET request. The following values, in decimal, can be set:

IXGSXGP_OK: 0 - record is returned in the user's area.
IXGSXGP_LOGICAL_ERROR: 8 - logical error was encountered. The record was not returned in the user's area.
IXGSXGP_LOGICAL_ERROR: 24 - the exit had an abend or a system error and could not process the request. Do not continue job processing. The record was not returned in the user's area.

IXGSXGP_ERROR_CODE

Error code used to identify the reason for a non-zero value in IXGSXGP_RETURN_CODE. The following values, in decimal, can be set:

IXGSXGP_NO_ERROR: 0 - no error was encountered. The field is initialized with a zero.
IXGSXGP_END_OF_DATA: 4 - end of data condition was detected. The record was not returned in the user's area.
IXGSXGP_PERM_ERROR: 8 - a permanent error condition was detected.

Output Parameter Descriptions, Close are as follows.

IXGSXCMP_EXIT_TOKEN: Exit token. The value returned in this field will be provided as input to the next exit call for this DD statement.

Output Parameter Descriptions, Unallocation are as follows.

IXGSXCMP_EXIT_TOKEN: Exit token. No longer applicable because unallocation is the last in the series of calls.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register

Contents

0-1

Not relevant

2-14

Restored to contents at entry

15

One of the following return codes:

Return Code: Explanation
Value of 0: Job processing is to continue. An error message may be provided to be put into the system error message portion of the job's log. Refer to specific exit calls for details for these messages.
Value of 4: Job processing is not to continue. An error message may be provided to be put into the system error message portion of the job's log. Refer to specific exit calls for details for these messages.
Value of 20: The exit had an abend or logical error and could not process the request. Job processing is not to continue. An error message may be provided to be put into the system error message portion of the job's log. Refer to specific exit calls for details for these messages.
Value other than 0 or 4: Treated the same as for return code 20.