SMF User Exit

The SMF user exit can be used to add a user-define detail section to the Adabas SMF record. The user exit is a separate load module whose name is provided by the ADARUN UEXSMF parameter.

The SMF user exit may not incur any TCB waits, for example, from I/O and WTORs. A wait will delay all nucleus activity.

The exit is invoked in AMODE 31 and Primary ASC mode using BASR R14,R15 and must return in the same addressing and ASC mode with registers R2-R13 unaltered. The user exit should have these registers set on entry:

  • R13 - Standard Format-1 Savearea

  • R14 - Return address

  • R15 - Entry address

  • R1 - The address of a parameter list mapped by macro SMFEXPL.

Adabas expects the following registers to be set on the return from the user exit:

  • R15 - The address of a detail secton of one or more instances to be included in the SMF record if R0 is not equal to zero.

  • R0 - The number of instances of the detail section whose address is in R15. A value of zerio will inhibit adding a detail section.

  • R1 - The length of each instance of the detail section whose address is in R15, if R0 is not equal to zero.

The parameter list is mapped by macro SMFEXPL. Here is the DSECT of the SMF user exit parameter list: 

SMFEXPL 	 DSect	,	
SMFEXPLA	 DS	   A	          Address of 1-byte Action code 
SMFEXPAI	 Equ	   c'I'	        Initialize environment
SMFEXPAT	 Equ	   c'T'	        Terminate environment
SMFEXPAG	 Equ	   c'G'	        Generate detail section
SMFEXPLD	 DS	   A	          Address of 4-byte detail section
                              mnemonic (c’USER’)
SMFEXPLB	 DS	   A	          Address of Build Area buffer
SMFEXPLS	 DS	   A	          Address of 4-byte buffer length
SMFEXPLC	 DS	   A	          Address of a read-only copy of 
                              SMF record base header, SDS and
                              ID sections
SMFEXPLU	 DS	   A	          Address of doubleword for use by the exit
                              Zero on first call, never
                              altered by Adabas
SMFEXPLL	 Equ	  *- SMFEXPL	 Length of SMFEXPL

The action code in SMFEXPLA specifies why the exit was entered. Code I (Initialize Environment) occurs once during nucleus initialization and before any SMF records have been written. The exit may wish to allocate a workarea for its own use. Code T (Terminate Environment) occurs once during nucleus termination, after all SMF records have been written. The exit may wish to free any storage it acquired. Code G (Generate SMF Record) occurs once each time an SMF record is generated.

The user exit is given a doubleword in which it can pass information from one invocation to another. It is initialized to zeros and never altered by ADASMF. This is a good place to convey information between invocations such as the address of a workarea.

The user exit is given a read-only copy of the basic SMF record with header, self-defining and product ID sections. When the action code is G (Generate), the exit can determine from the subtype in the header section whether it is invoked for an initialization, interval, or termination record.

The user exit is given an area that it may use to build its detail section. The initial contents on each invocation are undefined. The length of the buffer is specified by SMFEXPLS. It is 128KB in the current release but is subject to change in future releases. Check the buffer length parameter before using it. If detail section instances are built in this area, return its address in R15.

The maximum size of a single user detail section instance is that which fits into a single SMF record. The maximum length of an SMF record is fixed by z/OS as 32,756. The space available for a single instance is 32,756 less the sizes of the header, self-defining, and product ID sections as specified in the ASMFREC macro DSECTs. In this release, the SMF record allows 32,434 bytes maximum for any detail section instance, but this is subject to change in future releases.

You may wish to pass information between the SMF user exit and other exits running in the nucleus or other programs running in the same system. The z/OS name/token services are a good way to exchange information such as the address of a common data area. Refer to z/OS MVS Programming: Assembler Services Guide, IBM document number SA22-7605 for more information.