ASREXIT — SYMREC Authorization Exit

Topics for This Exit Appear as Follows:

Installing the Exit Routine
Exit Routine Environment
- Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
- Registers at Entry
- Parameter List Contents
Return Specifications
- Registers at Exit
Coded Examples of the Exit Routine

To allow unauthorized programs to write symptom records to the logrec data set (or to a job log or to both) through the use of the SYMREC macro, the SYMREC authorization exit, ASREXIT, must be in effect.

IBM® provides the following sample ASREXIT routines for your installation's use:

ASREXT0 allows all unauthorized programs to write symptom records to SYS1.LOGREC.
ASREXT1 allows only unauthorized programs that reside in APF-authorized libraries to write symptom records to SYS1.LOGREC.

If one of these IBM-supplied routines serves the needs of your installation, use it instead of coding your own routine (see Coded Examples of the Exit Routine). If you plan to code your own routine, ASREXT0 and ASREXT1 appear in SYS1.SAMPLIB. You can refer to them as examples when coding your routine.

You can use the ASREXIT interface to:

Allow all or only particular unauthorized programs to write symptom records to SYS1.LOGREC.
Cause unauthorized programs to write symptom records to a job log instead of, or in addition to, SYS1.LOGREC.

If you do not install the ASREXIT routine, MVS™ will not allow unauthorized programs to write symptom records to SYS1.LOGREC.

For information on the SYMREC macro, see z/OS MVS Programming: Assembler Services Guide.

Installing the Exit Routine

The exit must be linkedited with the name ASREXIT into SYS1.LINKLIB or any library in the LNKLST concatenation. To activate the exit routine, refresh LLA through the F LLA,REFRESH command.

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

Exit Routine Environment

ASREXIT receives control running under the unit of work that invoked the SYMREC service, in the following environment:

In supervisor state with PSW key 0
Enabled or disabled for interrupts
AMODE 31 and RMODE ANY
Primary=home address space of the unit of work that issues the SYMREC request.
SRB or task mode. PSATOLD=0 means SRB mode, and nonzero means task mode.
Note: Whether the exit routine receives control in task or SRB mode is dependent on the unit of work that issues the SYMREC request.

Exit Recovery: ASREXIT should provide its own recovery.

If ASREXIT does not provide a recovery routine, or if an exit routine error percolates beyond the exit's recovery, the system's ESTAEX recovery routine will get control. The ESTAEX will record information in the SDWA and request an SDUMP.

If ASREXIT abends, the system will not allow the symptom record to be written to SYS1.LOGREC. The exit will be invoked for the next unauthorized program that attempts to write symptom records.

Exit Routine Processing

When you install ASREXIT, the system will invoke the exit routine whenever an unauthorized program issues the SYMREC macro to write symptom records to the SYS1.LOGREC data set. The system passes to the exit in register 1 the address of fullword, which contains an address of the SYMREC authorization exit parameter list (mapped by ASREPL). The SYMREC authorization exit parameter list contains the following:

A program name
The job step name
The address of the symptom record
An indication of whether the program originated from an APF-authorized library.

ASREXIT runs under an RB that issues a SYMREC request. The values of the program name and the APF-authorized library indication in the SYMREC authorization exit parameter list are not necessarily those of the RB that issued the SYMREC request. The system obtains the program name and the APF-authorized library indication from the MAJOR CDE pointed to by the oldest RB on the TCB RB chain. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for information on the CDE data area. Based on the program name and the authorized library indication, ASREXIT indicates (by placing a value in the EPLRETC field of the exit parameter list) whether to reject the request or allow the program to write the symptom record to:

SYS1.LOGREC
The job log
Both SYS1.LOGREC and the job log.

If you code an ASREXIT routine, instead of installing one of the two IBM-supplied routines, you will probably use the routine to allow only specific unauthorized programs to write symptom records, or to cause unauthorized programs to write symptom records to their job log instead of, or in addition to, SYS1.LOGREC.

Using the Job Log: If you intend to restrict unauthorized programs from writing symptom records to SYS1.LOGREC, but still want to collect symptom records from unauthorized programs for debugging purposes, code the ASREXIT routine to cause unauthorized programs' symptom records to be written to their job log (by issuing WTOs with routing code 11). Application programmers can then view symptom records in the job log directly, rather than having the system programmer search SYS1.LOGREC for the symptom records.

If you do not install an ASREXIT routine, unauthorized programs cannot write symptom records to a job log.

Programming Considerations

Code the ASREXIT exit routine to be reentrant. A new copy of ASREXIT is loaded into storage from SYS1.LINKLIB for every request to write a SYMREC.

Entry Specifications

The system passes the address of the exit parameter list to ASREXIT.

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

Register: Contents
0: Not applicable
1: Pointer to the address of the exit parameter list
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of the exit

Parameter List Contents: Register 1 contains a pointer to the address of the exit parameter list, the EPL. The EPL contains the program name, job step name, address of the symptom record, and an indication of whether the program resides in an APF-authorized library.

The EPL is mapped by the ASREPL macro (data area ASREPL), which resides in SYS1.MODGEN. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for a mapping of the ASREPL data area.

Return Specifications

ASREXIT indicates to the system whether to cancel the request or allow the symptom record to be written by placing one of the following values in the EPLRETC field of the EPL:

Value

Explanation

X'00'

Write the symptom record to SYS1.LOGREC

X'04'

Write the symptom record to both SYS1.LOGREC and to the job log

X'08'

Write the symptom record to the job log only

X'0C'

Do not write the symptom record. The system returns to the caller both a system return code (X'0C') and reason code (X'F1C') indicating that request was rejected for either of the following reasons:

The exit routine rejected the request.
The exit routine was not installed.

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

Register: Contents
0,1: Not relevant
2-14: Restored to contents at entry
15: Not relevant

Coded Examples of the Exit Routine

IBM provides two SYMREC authorization exit routines for your installation's use, ASREXT0 and ASREXT1.

Use ASREXT0 to allow all unauthorized programs to write symptom records to SYS1.LOGREC. This exit routine always returns a value of X'00' (grant the request).

Use ASREXT1 to allow only unauthorized programs (that is, programs that were not linkedited with authorization code AC=1), that you have installed in an APF-authorized library to write symptom records to SYS1.LOGREC. When it is invoked, ASREXT1 checks to see whether the calling program resides in an APF-authorized library (the system sets the EPLAPFL bit to 1). If EPLAPFL is set to 1, ASREXT1 returns a value of X'00' (grant the request). Otherwise, ASREXT1 returns a value of X'0C' (reject the request).

ASREXT0 and ASREXT1 are provided in SYS1.SAMPLIB. To install either exit routine, you must linkedit the routine with the name ASREXIT into SYS1.LINKLIB or any library in the LNKLSTxx concatenation.

When you assemble ASREXT0 and ASREXT1, ensure SYS1.MODGEN is included in Assembler SYSLIB concatenation.

For more information on APF-authorized libraries, see z/OS MVS Programming: Assembler Services Guide.