Previous topic |
Next topic |
Contents |
Contact z/OS |
Library |
PDF
IXGSEXIT — Log Stream Subsystem Exit z/OS MVS Installation Exits SA23-1381-00 |
||||||||||||||||||||||||||||||||||||
Topics for This Exit Appear as Follows:
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:
Installing the ExitThe 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 EnvironmentThe
log stream subsystem exit receives control in the following environment:
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.
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 ProcessingThe 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 CallThe 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 CallThe 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. 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 they are the exit's responsibility for syntax checking. 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. Open CallThe 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 CallThe 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 CallThe 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 CallThe 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,
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 ConsiderationsIf 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:
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:
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.
Entry SpecificationsThe 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.
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 SpecificationsThe 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.
Output Parameter Descriptions, Allocation
are as follows
Output Parameter Descriptions, Open are
as follows.
Output Parameter Descriptions, GET are
as follows.
Output Parameter Descriptions, Close are
as follows.
Output Parameter Descriptions, Unallocation
are as follows.
Registers at Exit: Upon return from the exit processing, the register contents must be as follows.
|
Copyright IBM Corporation 1990, 2014
|