Start of change

IMS Fast Monitor User Exit (FASTMON)

The IMS Fast Monitor User Exit (FASTMON) provides access to the IMS Monitor data. The FASTMON exit is called during IMS initialization, IMS termination, and at IMS monitor call points for registered SLOG codes, regardless of whether the IMS Monitor is on or off.

The IMS Fast Monitor (FASTMON) user exit provides a similar exit point as the IMSMON user exit does. However, the FASTMON exit is optimized to minimize performance usage, in exchange for certain functional restrictions. The FASTMON user exit:
  • Not refreshable;
  • Cannot use user exit callable services;
  • Has a simple register interface for the WRITE call.

All defined FASTMON user exits are called whenever the IMS monitor module DFSMNTR0 is called for a monitor event when any FASTMON or IMSMON user exit has registered interest for the specific SLOG code.

This topic contains Product-sensitive Programming Interface information.

Subsections:

About this routine

Defining the routine

The FASTMON user exit is specified by an EXITDEF statement with TYPE=FASTMON in the DFSDFxxx USER_EXITS section. You can specify a single exit module name or a list of module names for this user exit. The exits are loaded at IMS control region initialization and persist until IMS termination.

The FASTMON exits are not refreshable.

When the FASTMON and the IMSMON user exits are both defined, the FASTMON user exits are called before the IMSMON user exits in the order that the exits are listed in the EXITDEF parameter. After all the FASTMON exits are called, the IMSMON exits are called in the same order.

Calling the routine

Each FASTMON user exit is called for initialization (function code 1), write (function code 2), and termination (function code 3) functions. When the FASTMON exit is called for initialization or termination functions, it is passed with the address of a monitor exit parameter list (MONEXPL), which is defined in macro DFSLOGP. When the FASTMON exit is called for a write function, the SLOG parameter list that was passed to IMS monitor is passed to the FASTMON exit.

A FASTMON user exit can be dynamically enabled or disabled. When it is called for initialization, MONEXFPT in DSECT MONEXPL points to a byte in storage which is used to enable or disable the exit. Refer to section Enabling and disabling exit for WRITE function calls below for further details.

Circumstances where the routine is not called

Under rare circumstances, the FASTMON exit is not called and one of DFS4573E, DFS4588E, or DFS4570E message is issued:
  • IMS is unable to obtain an AWE for a BCB FUNC=GET call.
  • IMS is unable to obtain a BCB block for the parameter list for the exit.
  • IMS is unable to obtain the storage for the SLOG interest array that is used by user exit services to check whether at least one exit is interested in a particular SLOG code.
  • IMS is unable to obtain the storage for setting up the FASTMON exit list.

All these circumstances are storage shortage issues where small amounts of storage (a few hundred bytes at most) cannot be obtained.

Table 1. IMS Fast Monitor exit routine attributes
Attribute Description
IMS environments DB/DC, DBCTL, DCCTL
Naming convention Any name can be used. Refer to Exit routine naming conventions for guidelines on routine names.
Binding Follow the guidelines in Routine binding restrictions.
Including the routine You must specify EXITDEF=(TYPE=FASTMON, EXITS=(exit_names)) in the EXITDEF parameter in the USER_EXITS section of the DFSDFxxx member. The module must be included in an authorized library in the JOBLIB, STEPLIB, or LINKLIST concatenation.
IMS callable services This exit does not support IMS callable services.
Sample routine location IMS.SDFSSMPL (member name DFSFMON0)

Contents of the registers when the exit is called

The contents of the registers vary depending on the function the FASTMON exit is called for:

When a FASTMON exit is called for an INIT or TERM function:
Register
Contents
R0
A(SCD)
R1
A(MONEXPL) (defined in the DFSLOGP macro)
R13
A(save area) in an IMS save area set. The exit might save its caller’s registers in this save area set, but must not modify the save area’s forward and backward chain pointers.
R14
Return address
R15
Exit entry point address
When a FASTMON exit is called for a WRITE function:
Register
Contents
R0
A(SCD)
R1
A(SLOG parmlist) (DSECT SLOGPRM, defined in the DFSLOGP macro) with the low X'00000001' bit set as a flag to tell the exit that it is the WRITE call
R13
A(save area) in an IMS save area set. The exit might save its caller’s registers in this save area set, but must not modify the save area’s forward and backward chain pointers.
R14
Return address
R15
Exit entry point address
Note: The SCD and the SLOG parameter lists are classified as DMTI (diagnosis, modification, and tuning information). Any fields in the SCD or the SLOG parameter lists are subject to change, addition, or deletion at any time (both between IMS releases and via maintenance).

The WRITE call function for the FASTMON exit can run in any address space that is associatedthat is with an IMS control region (IMS control, DLI/SAS, or dependent region). The exit might be given control in cross-memory mode to either control or DLI. The caller’s ITASK ECB might have an outstanding event on it and must not be modified or used for any WAIT/POST type processing.

Differentiating between an INIT/TERM call and a WRITE call

The FASTMON user exit can differentiate between an INIT/TERM call and a WRITE call by using the low bit of register 1:
INIT/TERM
The low bit is zero and R1 points to a MONEXPL.
WRITE
The low bit is one, and R1 points to an SLOG parameter list.
Note that when the low bit of R1 is set (WRITE call), the user exit must clear the low bit before using the value in R1 to address the SLOG parameter list. The following is an example of how to check the R1 value and clear the flag:
           TML   R1,X'0001'  Is this a WRITE call?
           JNO   INITTERM    No, init/term; R1 -> MONEXPL
           NILL  R1,X'FFFE'  Yes, clear flag; R1 -> DFSSLOG
*                                               
* Process WRITE call - R1 = A(DFSSLOG)          
*                                               
           USING SLOGPRM,R1  Address SLOG parmlist
           . . .                                
           J     ENDPROC     Done with processing
*                                               
* Process INIT/TERM call - R1 = A(MONEXPL)      
*                                               
INITTERM DS    0H                               
           USING MONEXPL,R1  Address monitor exit parmlist
            . . .                               
ENDPROC  DS    0H

Exit routine parameter list

The IMS Fast Monitor exit routine parameter list is mapped by DSECT MONEXPL in macro DFSLOGP.

Table 2. Parameter list for the IMS Fast Monitor user exit types

Field name

Offset

Length

Usage

Description
MONEXTYP X'00' X'01' Input Function code in decimal:
1
IMS initialization.
3
Termination.
MONEXFL1 X'01' X'01' Input Flag byte 1. This field is only defined when MONEXVRS is 3 or greater.

Bit definitions:

X'80' (MONEXFST) - Monitor exit that is called is FASTMON exit.
  X'02' X'02' None Reserved.
MONEXVRS X'04' X'04' Input Parameter list version. The current version number is 3.
MONEXECB X'08' X'04' Input Not applicable to FASTMON; the value is 0.
MONEXPRM X'0C' X'04' Input Not applicable to FASTMON; the value is 0.
MONEXTBL X'10' X'04' Output Used only in initialization calls. Address of the array where the exit registers interest in certain SLOG codes. Note that this field is set to x'FFFFFFFF' if IMS cannot obtain storage for the table. In this case, the FASTMON exit will be called for every monitor SLOG code. This field is 0 for WRITE and TERM calls.
MONEXCST X'14' X'08' Input Not applicable to FASTMON; the value is 0.
MONEXXEC X'1C' X'04' Input Not applicable to FASTMON; the value is 0.
MONEXFPT X'20' X'04' Input Pointer to a byte storage (see 'Enabling and disabling exit for WRITE function calls' section). This field is only defined when MONEXVRS is 3 or greater and applies only to the FASTMON user exit type.

Registering Interest in SLOG codes

When the exit is called during monitor initialization (function code 1), the exit must register which SLOG codes it would like to be called for. The exit registers the interest by moving the character 'Y' in an array (field name MONEXTBL). The array is passed to the offset that corresponds to the SLOG code that the exit is interested in. For example, if the exit wants to register an interest in SLOG code x'50', it moves the character 'Y' to the location that MONEXTBL + x'50' points to. If IMS cannot get storage for the array to pass to the exit, the field MONEXTBL contains x'FFFFFFFF'. The exit does not need to register interest in any SLOG codes because the exit is called for all SLOG codes.

Refer to the sample exit in IMS.SDFSSMPL(DFSFMON0) for an example of how to register interest in SLOG codes for the INIT call.

An exit must not modify any other places in the array other than moving a 'Y' in the slot that represents the SLOG codes that it is interested in. Because all exit routines for the IMSMON and FASTMON exit types are passed in the same array, moving something instead of a 'Y' in a slot would unregister another exit's interest in that SLOG code if that exit also puts a 'Y' there.

The FASTMON exit and the IMSMON exit share one interest array. If one of the exits registers interest for an SLOG code, both exits get called.

The FASTMON exit can only add subcodes to the interest array.

Enabling and disabling exit for WRITE function calls

DSECT MONEXPL provides a pointer to a byte used to enable and disable the exit for the subsequent WRITE function calls.

MONEXFPT is defined in DSECT MONEXPL and is a pointer to a byte in key 7 common storage that can be used to enable and disable monitor write calls (MONEXWRT) to the FASTMON user exit. If a user exit wants to dynamically enable and disable calls to itself, it can save the MONEXFPT pointer that is passed from the initialization call and update the byte pointed to it to control calls for write.

Valid values for this byte are:
MONEXWRE
Write calls enabled
MONEXWRD
Write calls disabled

IMS initializes the value of the byte to MONEXWRE, so no use of this pointer is necessary if the exit does not support dynamic enable or disable.

When you enable or disable the FASTMON exit for WRITE function calls, be aware that:
  1. Always check whether MONEXVRS is equal to or greater than MONEXV3 before you reference this field – This field is only present when the parameter list version (MONEXVRS) is 3 (MONEXV3) or higher.
  2. Always check whether the pointer is 0 before using it to access the byte – This pointer is only passed on the initialization call (MONEXINT) and only for the FASTMON exit type.
    Attention: There is no dynamic enable or disable for the IMSMON exit. The value is 0 for the IMSMON exit type.
  3. The byte is only used to control calls to the exit for monitor write (MONEXWRT). The termination call (MONEXTRM) is made regardless of the byte's setting.
  4. The storage that contains the control byte is freed when IMS terminates. If you are updating the byte asynchronously to your FASTMON exit execution, you must ensure that IMS is still active. Failure to do so can result in storage overlays.
  5. If you set this byte to anything instead of MONEXWRE or MONEXWRD, the monitor exit remains enabled. However, future changes might alter this behavior:
    • Set the byte that is pointed to by MONEXFPT or MONEXWRD to disable monitor write calls to the FASTMON user exit.
      Note: Because the monitor might be called in parallel under many different IMS transaction control blocks (TCBs), the user exit might still be called for a short period of time after the byte is set to MONEXWRD due to timing conditions.
    • Set the byte that is pointed to by MONEXFPT or MONEXWRE to enable monitor write calls to the FASTMON user exit.
      Note: When calls to the user exit are currently disabled, this must be done by a process outside of the user exit itself.
End of change