IEFDOIXT — Edit / Check A Caller's Dynamic Output Text Units Exit

Topics for This Exit Appear as Follows:

Dynamic output is a system service that users can invoke by issuing the OUTADD or OUTDEL macro. Dynamic output allows an installation to specify the output characteristics of a sysout data set dynamically as an alternative to specifying these characteristics on the OUTPUT JCL statement. For more detailed information about using dynamic output, see z/OS MVS Programming: Authorized Assembler Services Guide.

IEFDOIXT is the dynamic output installation exit. You can use IEFDOIXT to:
  • Edit the text units. For example, you can use this exit to limit requests for COPIES to be less than or equal to 50.
  • Detect requests for unsupported devices or features.
  • Correct requests for unsupported devices or features by issuing installation-defined reason codes. These reason codes help the invoker of dynamic output diagnose problems that the exit detected.

Installing the Exit Routine

The IBM-supplied version of IEFDOIXT resides in SYS1.LINKLIB. You can replace IEFDOIXT in SYS1.LINKLIB with your own version or place your version of IEFDOIXT in an authorized library somewhere else in the search order prior to SYS1.LINKLIB. For more details on the search order for load modules, see z/OS MVS Programming: Assembler Services Guide.

For general instructions on installing an exit routine, see Link editing an Installation Exit Routine into a Library.

Exit Routine Environment

IEFDOIXT receives control in the following environment:
  • Enabled for interrupts.
  • In supervisor state with PSW key 1 and must return control in the same state and key.
  • In AMODE 31 and RMODE ANY.
  • In the caller's address space.
  • With no locks or resources held (other than storage obtained via GETMAIN and an ESTAE) when it calls IEFDOIXT.
  • Under a type 3 SVC. See z/OS MVS Programming: Authorized Assembler Services Guide for a description of the restrictions in this environment.

Exit Recovery: IEFDOIXT runs under dynamic output's recovery environment. If recovery for dynamic output gets control during exit routine processing, dynamic output returns to its invoker and sets return and reason codes to indicate that the exit abnormally terminated.

Exit Routine Processing

Each time that you invoke dynamic output via the OUTADD or OUTDEL macro, it links to the IEFDOIXT installation exit. When IEFDOIXT completes its processing, it returns control to dynamic output. If no errors are detected, dynamic output then creates or deletes the output descriptor.

Dynamic output passes the exit a copy of the input from the caller of dynamic output. Before calling the exit, dynamic output performs the following verification of the caller's input data:
  • Dynamic output references the input data in the key of the caller that issued the OUTADD or OUTDEL macro. If a protection exception (0C4 ABEND) occurs when the data is referenced, dynamic output passes control back to the caller, and the installation exit does not get control.
  • Dynamic output verifies the text units. If the text units are not valid, dynamic output reports the problem as being that the parameter list is not valid. In general, dynamic output does not differentiate between text unit errors that the caller causes and those that the exit causes. In addition, because the exit works on a copy of the caller's parameter list, the caller can not recognize the changes that the exit has made to the text units. For this reason, the exit must ensure that text units are updated correctly.

If dynamic output determines that there is an error in the caller's input data, the installation exit does not receive control. If dynamic output verifies the caller's input data, the installation exit receives a copy of the data. This input data includes the fixed parameter list (DOCNP), the text units and a text unit pointer list with pointers to the copied text units. The exit also receives 500 bytes of storage so that it can update the caller's text unit pointers and text units.

In the exit routine, you can read or make valid alterations to the data passed to the exit. You can omit text units by zeroing their text unit pointers. You can add text units, as well as the text unit pointers for the new text units, in the work area provided. Concatenate the new text unit pointers to the end of the passed text unit pointer list, which is contiguous with the work area. If you add new text unit pointers, reset the high-order bit that indicates the last text unit pointer.

The exit should set the values of registers 0, 1 and 15 on return to dynamic output. The value of register 15 indicates whether dynamic output is to cancel or proceed with the request. Registers 1 and 0 are used for the exit to optionally pass diagnostic information to the dynamic output caller. For specification of the registers on return from the exit, see Return Specifications, and z/OS MVS Programming: Assembler Services Guide.

Upon return from the exit, dynamic output performs the following verification of the registers returned by the exit and the data areas passed to the exit:
  • Dynamic output verifies the contents of registers 0, 1, and 15. If the register contents are not valid, or if the return code in register 15 is an 8, dynamic output denies the user's request and returns a reason code that identifies the problem.
  • Dynamic output verifies the fixed parameter list (DOCNP) and reports any problems with the parameter list by setting the appropriate return and reason codes. Because dynamic output also verifies DOCNP before linking to the exit routine, unique error return and reason codes are issued to help differentiate between errors in DOCNP which the caller causes, and errors that the exit routine causes.
  • Dynamic output verifies the text units. If the text units are not valid, dynamic output reports the problem as being that the parameter list is not valid. Dynamic output does not differentiate between text unit errors that the caller causes and those that the exit causes. In addition, because the exit works on a copy of the caller's parameter list, the caller can not recognize the changes that the exit has made to the text units. For this reason, the exit should make changes to the text units very carefully.

    When the exit alters the text units to contain negative values in the number of parameters field or in the length of parameter field, the results are unpredictable. Dynamic output only checks these fields before calling the exit routine. It is the exit's responsibility to make sure that it does not pass negative values in these fields. It also is essential that the exit does not cause an OUTADD request to contain no text units.

If no errors are detected, the output descriptor is created or deleted.

Programming Considerations

Code the IEFDOIXT routine to be reentrant.

The copy of the caller's input data, the text unit pointers and the 500-byte work area that are passed to the exit are in key 1 storage, subpool 229. This storage is pageable and fetch protected.

The IBM-supplied exit routine only zeroes the contents of registers 0, 1, and 15. It restores the other registers and returns control to dynamic output.

The exit is an authorized exit, so you must follow standard security and integrity procedures.

Dynamic output links to IEFDOIXT. The LINK macro does not restore the register contents, so you must be sure that you restore the contents of registers 2-13 before returning to dynamic output.

Tracing IEFDOIXT's Input and Output

You can use the generalized trace facility (GTF) to trace IEFDOIXT's input and output, when the GTF identifier for dynamic output is active. The GTF identifier for dynamic output is user event F62.

Each GTF trace record is prefixed with a 24-byte field that uniquely identifies the creator of the trace record and the trace record's sequence number. The format of the 24-byte field is as follows:
(Hex)
Contents
X'00'
‘TCB ’ (EBCDIC representation)
X'04'
TCB address of the task that invoked the SVC
X'08'
‘SVRB’ (EBCDIC representation)
X'0C'
SVRB address for this invocation of the SVC
X'10'
‘SEQ#’ (EBCDIC representation)
X'14'
Sequence number of trace record. That is, 1 indicates the first trace record of the input to IEFDOIXT, 2 indicates the second trace record, and so on.
Each GTF trace record can have a maximum length of 256 bytes. The following is a description of the GTF trace records for IEFDOIXT:
  • The first trace record contains a character string header (starting at offset X'18') that indicates whether the data being traced is IEFDOIXT's input or output.
  • The second trace record contains the following information:
    (Hex)
     Contents
    X'18'
    ‘ DOCNP->’
    X'20'
    Pointer to copy of DOCNP
    X'24'
    ‘ WORKAREA START->’
    X'38'
    Pointer to the start of IEFDOIXT's workarea
    X'3C'
    ‘ WORKAREA END->’
    X'4C'
    Pointer to the end of IEFDOIXT's workarea
  • The third record through the second-to-last record contains the data area that was passed to IEFDOIXT. This includes the copy of the SVC caller's parameters and the installation workarea. More than one trace record is issued if the data area exceeds the maximum length of one trace record (256 bytes).
  • The last record contains a character string that indicates the end of the trace data.

See z/OS MVS Diagnosis: Tools and Service Aids for information on using GTF.

Entry Specifications

Dynamic output passes three address parameters to the installation exit routine.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register
Contents
0
Not applicable
1
Address of three consecutive fullwords. Each fullword is a pointer; the first fullword points to the parameter list (DOCNP), the second fullword points to the beginning (first byte) of the 500-byte work area that the exit can use, and the third fullword points to the end (last byte) of the work area. Figure 1 shows the parameter structure.
2-12
Not applicable
13
Not applicable
14
Return address
15
Not applicable
Figure 1. IEFDOIXT Input Parameter Structure
ieae4ig2

Parameter Descriptions: Register 1 contains the address of a pointer list that consists of three contiguous fullwords in storage. The first fullword points to the address of the fixed parameter list, the DOCNP, which is mapped by macro IEFDOCNP (data area DOCNP). For a mapping of the DOCNP data area, see z/OS MVS Data Areas in the z/OS Internet library.

Return Specifications

IEFDOIXT returns control to dynamic output and passes back a return code, a reason code and, optionally, a key in error.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register
Contents
0
The contents of register 0 depend on the return code that the exit routine places in register 15.
  • If the return code is zero, register 0 must contain a zero.
  • If the return code is 8, register 0 may contain a zero or an installation-defined reason code with a value between X‘6000’ and X‘7FFF’.
1
The contents of register 1 depend on the return code that the exit places in register 15.
  • If the return code is zero, set register 1 to zero.
  • If the return code is 8, register 1 can contain either an erroneous text unit key in the two low-order bytes, or zero. The two high-order bytes must always contain zeroes.
2-13
Restored to contents at entry
14
Return address
15
Contains one of the following return codes:
Return Code
Description
0
The request is to be processed.
8
The request is to be denied. The values in register 0 and 1 are set accordingly and returned to the dynamic output caller in those registers.