Description

The SYMREC macro updates a symptom record with system environment information and then logs the symptom record in the logrec data set. The symptom record is a data area in the user's application that has been mapped by the ADSR mapping macro.

As an application detects errors during execution, it stores diagnostic information into the symptom record and issues the SYMREC macro to log the record. The diagnostic information consists of a description of a programming failure and a description of the environment in which the failure occurred.

When the SYMREC macro is invoked, it checks that all the required input fields of the ADSR symptom record are set by the caller. If the required input fields are not set, SYMREC issues appropriate return and reason codes.

The SYMREC macro can be used for authorized and unauthorized programs. Your installation controls which programs can write symptom records and whether to write the symptom record to the logrec data set, the job log, both or neither through an installation-written exit. This exit is called ASREXIT. For further information about ASREXIT, see z/OS MVS Installation Exits. SYMRBLD is a related macro. For more information see z/OS MVS Programming: Assembler Services Guide.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state, and any PSW key.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled or disabled for I/O and external interrupts. If disabled, the input data to SYMREC must be in fixed storage or in disabled reference (DREF) storage.
Locks:	The caller may hold locks, but is not required to hold any.
Control parameters:	Must be in the primary address space.

Programming requirements

The caller must include the ADSR mapping macro to map the symptom record specified on the SR parameter. The caller must fill in this symptom record. For more information on the ADSR mapping macro, see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

Restrictions

Although callers in 24-bit or 31-bit addressing mode can issue the SYMREC macro, the addresses passed to the SYMREC service must be 31-bit addresses.

Input register information

The SYMREC macro is sensitive to the SYSSTATE macro with the OSREL parameter

If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6 parameter (Version 1 Release 6 of z/OS® or later) before issuing the SYMREC macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
Otherwise, the caller must ensure that the following general purpose register contains the specified information:
Register

Contents

13

The address of an 18-word save area

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Reason code
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The standard form of the SYMREC macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede SYMREC.

SYMREC

␢	One or more blanks must follow SYMREC.

SR=`addr`	`addr`: A-type address or register 2-12.

Parameters

The parameters are explained as follows:

SR=addr: Specifies the address of the symptom record. The SR parameter is required.

ABEND codes

None.

Return and reason codes

When SYMREC returns control, registers 15 and 0 contain the following hexadecimal return codes and reason codes, respectively:

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
0000	0000	Meaning: SYMREC completed successfully and the symptom record was recorded. Action: None.
0004	0164	Meaning: Program error. An attempt to write section 1 information from the completed symptom record failed. The area was not accessible to a write request. The entire input record was recorded. Action: Make sure that the storage containing the input symptom record is not released before the SYMREC request completes.
0008	0158	Meaning: Program error. The total length of the input symptom record exceeds the maximum. A partial symptom record was recorded. Action: Correct the length of the symptom record. The maximum length of the symptom record is 1900 bytes. Sections 1, 2, and 2.1 of the symptom record are fixed in length. The length of sections 1, 2, and 2.1 combined is 212 bytes. Therefore, the combined length of sections 3, 4, and 5 must be less than or equal to 1688 bytes.
0008	015C	Meaning: Program error. Optional segments of the input symptom record were not accessible. The record includes the accessible entries of the input symptom record. A partial symptom record was recorded. Action: Verify that all optional sections (sections 4 and 5) of the symptom record are accessible.
000C	0104	Meaning: Program error. The first 2 bytes of the input symptom record do not contain the SR operand. No symptom record was recorded. Action: Verify that the correct address for the input symptom record was provided to the SYMREC service and that the first 2 bytes of the symptom record contain 'SR'.
000C	0108	Meaning: Program error. The input symptom record does not contain the required entries for section 2. No symptom record was recorded. Action: Make sure the following fields have been supplied in section 2 of the symptom record: the length of section 2 and the length/offset of section 2.1 and 3.
000C	010C	Meaning: Program error. The input symptom record does not contain the required entries for section 2.1. No symptom record was recorded. Action: Make sure the following fields have been supplied in section 2.1 of the symptom record: section 2.1 identifier, architecture level of the symptom record, and the component release level or PID release level. Also verify that the length of section 2.1 is correct in section2.
000C	0114	Meaning: Program error. The input symptom record does not contain the required entries for section 3. No symptom record was recorded. Action: Make sure that the primary symptom string contains at least one symptom.
000C	0128	Meaning: Program error. This reason code is set when the input symptom record cannot be referenced. No symptom record was recorded. Action: Verify that the correct address for the symptom record was provided to the SYMREC macro and that this storage is accessible.
000C	012C	Meaning: Program error. All required sections of the symptom record could not be referenced. No symptom record was recorded. Action: Verify that all required sections (sections 1, 2, 2.1 and 3) of the symptom record are accessible.
000C	0134	Meaning: Program error. The input symptom record address is in non-accessible storage. No symptom record was recorded. Action: Verify the input parameter list provided to the SYMREC request.
000C	0144	Meaning: Program error. No symptom record was recorded. One of the following occurred: The caller is in cross memory mode and the home address space is not accessible because it is swapped out or going through address space termination. Action: Make sure that the home address space is non-swappable during the SYMREC request. An address space can be made non-swappable using the SYSEVENT macro. The caller is disabled, but it did not obtain MVS-recognized (valid) disablement. Valid disablement is obtained through a SETLOCK OBTAIN,TYPE=CPU request, available to supervisor state and key 0 callers only. Action: Use the SETLOCK OBTAIN, TYPE=CPU to disable normally.
000C	0F1C	Meaning: Program error. The installation exit ASREXIT prevented the unauthorized caller from writing the symptom record to the logrec data set. No symptom record was recorded. Action: None. The installation has decided that unauthorized programs cannot write to the logrec data set.
0010	0F04	Meaning: Environmental error. There was insufficient space in the LOGREC buffer to accommodate the symptom record. No symptom record was recorded. Action: The request might be successful if retried. If the problem persists, record the return and reason code and supply it to the appropriate system support personnel.
0010	0F08	Meaning: System error. The SYMREC service could not acquire storage for a work area or a copy of the symptom record. No symptom record was recorded. Action: The request might be successful if retried. If the problem persists, record the return and reason code and supply it to the appropriate system support personnel.
0010	0F0C	Meaning: System error. Failure occurred while the symptom record was being moved to the LOGREC buffer. No symptom record was recorded. Action: Record the return and reason code and supply it to the appropriate IBM® support personnel.
0010	0F10	Meaning: System error. The SYMREC service has a logic error. No symptom record was recorded. Action: Record the return and reason code and supply it to the appropriate IBM support personnel.
0010	0F14	Meaning: System error. The SYMREC service has shut itself down. It has exceeded the maximum allowable logic errors for the service routine. No symptom record was recorded. Action: Record the return and reason code and supply it to the appropriate IBM support personnel.
0010	0F18	Meaning: System error. The SYMREC service has shut itself down. It has exceeded the maximum allowable incomplete SYMREC requests for processing. No symptom record was recorded. Action: Record the return and reason code and supply it to the appropriate IBM support personnel.
0014	—	Meaning: System error. SYMREC is not operable. Action: Record the return and reason code and supply it to the appropriate IBM support personnel.