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 MVS™ to create a new log stream. You can change the model log stream name and other parameters before they are passed to the MVS system logger.

If a log stream connection request from CICS® to the MVS system logger fails because the log stream is not defined to MVS, CICS issues a request to the MVS system logger to create the log stream dynamically, using a model log stream definition.

The model log stream name that CICS passes to MVS 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 MVS symbol that resolves to the system name of the MVS 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 an MVS image with a sysid of MV10 and using the default JOURNALMODEL definition, the MVS system logger expects to find a model log stream named MV10.DFHLOG.MODEL.

If the system name of the MVS 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 the MVS system logger rejects log stream names that begin with a numeric. If the system name of the MVS image starts with a numeric but is already 8 characters long (the maximum), CICS does not add the “C” prefix, which means that the MVS 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 MVS 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 the MVS 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.