Log manager domain exit XLGSTRM

There is one exit point, XLGSTRM, in the log manager domain. You can use XLGSTRM to modify a request to z/OS® to create a new log stream. You can change the model log stream name and other parameters before they are passed to z/OS System Logger.

If a log stream connection request from CICS® to z/OS System Logger fails because the log stream is not defined to z/OS, CICS issues a request to z/OS System Logger to create the log stream dynamically, using a model log stream definition.

The model log stream name that CICS passes to z/OS depends on whether the journal name refers to the system log or a CICS general log, as follows:
CICS system logs
&sysname.LSN_last_qualifier.MODEL

&sysname is the z/OS symbol that resolves to the system name of the z/OS image. LSN_last_qualifier is the last qualifier of the log stream name as specified on the JOURNALMODEL resource definition.

If you do not provide a JOURNALMODEL resource definition for DFHLOG and DFHSHUNT, or if you use the CICS definitions supplied in group DFHLGMOD, the model log stream names default to &sysname.DFHLOG.MODEL and &sysname.DFHSHUNT.MODEL.

For example, if a CICS region issues a request to create a log stream for its primary system log, and CICS is running in a z/OS image with a sysid of MV10 and using the default JOURNALMODEL definition, z/OS System Logger expects to find a model log stream named MV10.DFHLOG.MODEL.

If the system name of the z/OS image starts with a numeric character and is less than 8 characters long, CICS prefixes it with a C, so that the model log stream name becomes C&sysname.LSN_last_qualifier. This is because z/OS System Logger rejects log stream names that begin with a numeric. If the system name of the z/OS image starts with a numeric but is already 8 characters long (the maximum), CICS does not add the C prefix, which means that z/OS System Logger will reject the default model log stream name. However, your global user exit program can change the model log stream name.

CICS general logs
LSN_qualifier_1.LSN_qualifier2.MODEL. The defaults for these two qualifiers are the CICS region userid and the CICS region APPLID, but they can be user-defined values specified in a JOURNALMODEL resource definition.

For example, if the CICS region userid is CICSHT## and the APPLID is CICSHTA1, the default model name is CICSHT##.CICSHTA1.MODEL.

The following information is passed to an XLGSTRM global user exit program:
  • The name of the log stream to be defined
  • The default model log stream name
  • A system log flag
  • The z/OS System Logger IXGINVNT parameter list.
Your exit program can amend the model stream name by updating the field pointed to by the UEPMLSN exit-specific parameter. Here is an example of how your exit program can change the model stream name: 
          L     R3,UEPMLSN          R3 = address of stream name
          MVC   0(26,R3),=CL26'NEW.MODEL.NAME'
By updating the field pointed to by the UEPIXG parameter, your exit program can amend the IXGINVNT macro parameter list used by z/OS System Logger to define the log stream. Use the IXGINVNT MF=M form of the macro, which allows the exit to specify the log stream attributes to be used. Here is an example of how your exit program can change the structure name: 
          L     R9,UEPIXG
          IXGINVNT REQUEST=DEFINE,
                TYPE=LOGSTREAM,
                STRUCTNAME=NEW_STRUCTURE,
                MF=(M,(R9),NOCHECK)
     ...
 NEW_STRUCTURE DC CL16'LOG_SYSTEST_009'

You do not need to code the list and execute forms of the IXGINVNT macro, or include the IXGCON or IXGANSAA macros in your exit—these are provided by the CICS code which issues the DEFINE request.

For information about the IXGINVNT service, see the z/OS MVS Programming: Assembler Services Guide.

An XLGSTRM global user exit program can set explicit attributes for the log stream definition, and can also set a return code that causes the log stream definition to be bypassed.

Note: If you want XLGSTRM to intercept the connection of the CICS system logs, you must enable your exit program in a first-phase PLT program.

Example of how to use the XLGSTRM exit

Suppose that 200 CICS regions are running on 20 z/OS images; To avoid having to define explicitly each log stream used by each CICS region, you decide to use model definitions. Log streams will be defined to z/OS dynamically on their first usage, with an XLGSTRM exit program being used to select from alternative model log streams. This is how it might work:
  1. On an initial start of a CICS region, the INITPARM system initialization parameter specifies:
    INITPARM=(Exit_enabler_pgmname=nnn)
    where:
    • Exit_enabler_pgmname is the name of the program that enables the XLGSTRM user exit program.
    • nnn is a number that identifies a group of CICS regions that share the same set of log stream models.
  2. The program that enables the XLGSTRM user exit program issues an EXEC CICS ASSIGN INITPARM command to retrieve the value nnn, and places it in the exit program's global work area.
  3. When the region tries to connect to its system log, because the log stream is not defined the XLGSTRM exit program is invoked. The exit program selects model CICS.DFHLOG.MODELnnn.

Sample global user exit program for XLGSTRM

DFH$LGLS is a sample global user exit program for the XLGSTRM exit point. It shows you how to access and change some of the parameters that are passed to an XLGSTRM exit program. For more information, see Log manager domain sample exit program: DFH$LGLS.