LOGEDIT: Log edit user exit (DFSFLGE0 and other LOGEDIT exits)

This topic contains Product-sensitive Programming Interface information.

After the message is edited, the message-related record is then logged. Even though the altered record is logged, IMS processes the original version of the message. After a subsequent restart, IMS processes the edited version of the message. If restart reschedules an edited message, the transaction might fail because of the edits.

Subsections:

• About this routine
• Restrictions
• Communicating with IMS

About this routine

You can write a log edit exit routine that is called before each message-related log record is written to the log. The exit overlays segments of the record data with other data. The record types that are presented to the exit are controlled through the LOGEDIT statement in the LOGGER section of the DFSDFxxx PROCLIB member. If you want to use the REFRESH USEREXIT command to add the LOGEDIT user exit, you must have selected log records to edit when IMS initialized. If no records were selected, message DFS4586E is issued and the LOGEDIT user exit is not added.

The user exit cannot directly edit log data. Instead, it returns an offset and length where data is to be changed and the address of a replacement. IMS overwrites the actual record starting at the specified offset for the specified length using the data at the address indicated for replacement data.

The user exit can specify that no alterations are to be made. Or, after specifying an edit, it can indicate that further edits are needed in the same record.

If the offset or length that is specified extends outside the data portion of the record, no editing occurs, and the user exit is notified on the next call. The user exit can assess the situation, but no further editing of the record is allowed. After the user exit returns, it is called for the next record.

This user exit is optional. No default user exit and no samples are provided. The following table shows the attributes of the log edit user exit.

//LINKIT JOB 1,MSGLEVEL=1 
//LINK EXEC PGM=IEWL,PARM=RENT 
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(20,20))
//SYSPRINT DD SYSOUT=A
//SYSLMOD DD DSN=IMS.SDFSRESL,DISP=SHR
//OBJIN DD DSN=IMS.USERLIB,DISP=SHR
//SYSLIN DD *
  INCLUDE OBJIN(DFSFLGE0)
  MODE AMODE(31),RMODE(ANY)
  NAME DFSFLGE0(R)
//

Attributes of this routine

The log edit user exit must be written as reentrant. The user exit receives control running in 31-bit addressing mode and must return control in that mode. It is called in TASK mode, with no locks held, and in non-cross memory, non-AR mode. In an online IMS environment, the log edit user exit runs in key 7, supervisor state, in the IMS control region address space.

Calling this routine

Restrictions

The log edit user exit is subject to the following restrictions:

• This user exit should not modify any storage other than the parameter lists and associated work areas.
• All addresses, entry register contents, and parameter list contents can change from one call of the LOGEDIT user exit to the next call. One call should not depend on addresses from a prior call. The sole exception is the content of the work area indicated by SXPLAWRK, which will persist across calls.
• This user exit can call only z/OS® services that it is authorized to call. It must not call any internal IMS services.

Communicating with IMS

IMS communicates with this user exit through the entry registers, a parameter list, and the exit registers.

Content of Registers on Entry

Standard exit parameter list

This user exit uses the Version 6 standard exit parameter list. The address of the work area passed to this user exit in SXPLAWRK will be the same each time that this user exit is called.

If your LOGEDIT user exit can be called in an enhanced user exit environment, additional user exit routines might be called after your routine. When your user exit routine finds a transaction upon which to act, it can set SXPL_CALLNXTN in the byte that SXPLCNXT points to. This tells IMS to not call additional exit routines.

Function-specific parameter list on entry

The following table shows the content of the function-specific parameter list. The address of this parameter list is in the standard IMS user exit parameter list field SXPLFSPL.

LGEXVERA points to LGEXVER, described in the following table:

LGEXTYPA points to LGEXCTYPE, described in the following table:

As shown in the preceding table, some fields apply only to the record edit call.

• LGEXRCDA points to a copy of the log record. It does not point into a log buffer.
• LGEXEINA points to the edit instructions area mapped by LGEXEI (included in LCDSECT). These fields are described in the following table.
• LGEXFBKA points to the feedback field, described in Table 6:

The user exit cannot actively edit log data. Instead, it returns an offset and length where data is to be changed and the address of a replacement. IMS overwrites the actual record starting at the specified offset for the specified length using the data at the address indicated for replacement data.

The edit instruction area is cleared before each record edit call. IMS edits the record only if LGEXEDIT is set on return to IMS. If the user exit needs to make another change in the same record, it must also set LGEXHOLD to have the same record presented again. The previous edit does not appear in the record image. IMS changes only the actual record.

Contents of registers on exit

Before returning to IMS, the user exit must restore all registers except for register 15, which must contain the following: