VRADATA — Update variable recording area data

Description

The VRADATA macro copies service information into a variable recording area (VRA), usually the system diagnostic work area (SDWAVRA). This information can later be recorded in the LOGREC data set if software errors occur. (See the SETRP macro, RECORD=YES parameter description, for more information on recording the SDWA data area.) The information copied into the VRA using this macro is in a key, length, data format defined by the IHAVRA mapping macro. The key and length are one-byte fields; the data can vary in length. The IHAVRA mapping macro is shown in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ under VRAMAP.

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- or 64-bit
ASC mode:	Primary, secondary, or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold locks, but is not required to hold any.
Control parameters:	None

Programming requirements

If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro before issuing VRADATA. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
You must include the IHASDWA mapping macro as a DSECT in your program if you accept the default for VRAINIT, VRACLEN, VRAMLEN, or if you specify VRAINIT=SDWAVRA. You must also place the address of the SDWA data area into the SDWAREG register (or default register 1) if you accept the default for any of these three parameters.
You must include the IHAVRA mapping macro as a DSECT in your program. If you include the IHASDWA mapping macro, IHAVRA is automatically included.
You can issue VRADATA more than once in a program, but you need to specify VRAINIT, VRACLEN, and VRAMLEN only once for a particular series of updates to the VRA.
If you specify a key on the KEY parameter, but no data on the DATA parameter, the length field for the VRA entry (LEN parameter) is zero. You must be running in the key the SDWA was obtained in. Refer to z/OS MVS Programming: Assembler Services Guide for more information.

Restrictions

None.

Input register information

Before issuing the VRADATA macro, the AR-mode caller must ensure that the following GPRs contain the specified information.

Register: Contents
1: Address of the SDWA if you do not specify the SDWAREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, the caller does not have to place any information into this register.
14: Address of the next available field in the VRA if you do not specify the VRAREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, the caller does not have to place any information into this register.

Before issuing the VRADATA macro, the caller must ensure that the following ARs contain the specified information.

Register: Contents
1: ALET of the SDWA whose address is in GPR 1, only if you do not specify the SDWAREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, the caller does not have to place any information into this register.
14: ALET of the next available space in the VRA whose address is in GPR 14 only if you do not specify the VRAREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, the caller does not have to place any information into this register.

Output register information

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

Register: Contents
0-13: Unchanged
14: Address of the next available space in the VRA for the next invocation of VRADATA if you did not specify the VRAREG parameter on this invocation or any previous invocation; otherwise, unchanged.
15: Used as a work register if you did not specify the WORKREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, unchanged.

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 VRADATA macro is written as follows:

Syntax	Description

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

␣	One or more blanks must precede VRADATA.

VRADATA

␣	One or more blanks must follow VRADATA.

VRAINIT=`vra addr`	`vra addr`: RX-type address, or the symbol SDWAVRA.
	Default: address of SDWAVRA

,VRACLEN=`curr len addr`	`curr len addr`: RX-type address.
or `(curr len addr,0)`	Default: address of SDWAURAL.
,VRAMLEN=`max len addr`	`max len addr`: RX-type address.
	Default: address of SDWAVRAL.

,KEY=`key nmbr`	`key nmbr`: Symbol or decimal digit.

,LENADDR=`data len addr`	`data len addr`: RX-type address.
,LEN=`data len value`	`data len value`: Symbol or decimal digit.
	Default: length of DATA storage.

,DATA=`data addr`	`data addr`: RX-type address, or register (1) - (15).

,SDWAREG=`reg`	`reg`: Symbol or decimal digits 1-15.
	Default: 1

,VRAREG=`(reg,descr)`	`reg`: Symbol or decimal digits 1-15.
	Default: 14
	`descr`: SET or NOTSET
	Default: NOTSET if VRAINIT is specified,
	otherwise SET.

,WORKREG=`reg`	`reg`: Symbol or decimal digits 1-15.
	Default: 15

,TYPE=(LEN,TEST) ,TYPE=(LEN,NOTEST) ,TYPE=(LEN,NOT) ,TYPE=(NOLEN,TEST) ,TYPE=(NOLEN,NOTEST) ,TYPE=(NOLEN,NOT) ,TYPE=(NOL,TEST) ,TYPE=(NOL,NOTEST) ,TYPE=(NOL,NOT)	Default: LEN,TEST

Parameters

The parameters are explained as follows:

VRAINIT=vra addr: Specifies the address of the variable recording area to be initialized and updated. The value in the register specified by the VRAREG parameter is also initialized unless VRAREG=(,SET) is specified. If VRAINIT=SDWAVRA is specified, the SDWA data area is also updated to indicate that the VRA contains data in key-length-data format that is to be displayed in hexadecimal. If VRAINIT is not specified, VRAINIT=SDWAVRA is assumed. All subsequent VRADATA macros use the specified VRAINIT value until you specify another VRAINIT value.
,VRACLEN=curr len addr: Specifies the address of a one-byte field that contains the length of the current VRA. This value changes as information is added in the VRA. If you do not specify VRACLEN, you can obtain the current length of the VRA from the SDWAURAL field of the SDWA.
,VRACLEN=(curr len addr, 0): Specifies that the area containing the length is to be zeroed.
All subsequent VRADATA macros use the specified VRACLEN value until you specify another VRACLEN value.
,VRAMLEN=max len addr: Specifies the address of a two-byte field that contains the maximum length of the VRA. If you do not specify VRAMLEN, the maximum length is obtained from SDWAVRAL.
All subsequent VRADATA macros use the specified VRAMLEN value until you specify another VRAMLEN value.
,KEY=key number: Specifies the key value to be placed in the VRAKEY field of the current VRA entry. The IHAVRA mapping macro (VRAMAP) defines the valid key values.
,LENADDR=data len addr
,LEN=data len value: Specifies the length of the data for the VRA entry. The maximum length is 255 bytes. Omit this parameter unless the DATA parameter is a register value or a displacement plus a register, or if the defined data length must be overridden because it is larger than 255 bytes. For bit string data, use this parameter to indicate how many bytes the bit string occupies. The data length field pointed to by LENADDR must be a two-byte area with the length right-justified in the area.
,DATA=data addr: Specifies the address of the data to be copied into the VRA. The data must correspond to the key specified by the KEY parameter. If you specify DATA, you must specify KEY. You must also specify LEN or LENADDR if DATA has a register value or if the data length is greater than 255 bytes.
,SDWAREG=reg: Specifies a register containing the address of the SDWA data area. You must place the address in this register before invoking VRADATA. The VRADATA macro preserves the contents of this register. If you do not specify SDWAREG, register 1 is the default.
,VRAREG=(reg,descr): Specifies a register to contain the address of the next available field in the VRA and a description of whether or not the register value is already set (SET) or not set (NOTSET). If VRAINIT is specified, the default is NOTSET. If VRAINIT is not specified, the default is SET. If you specify NOTSET or default to it, the system program places the address of the VRA plus the current length in the register before updating the VRA.
After updating the VRA, the system updates the register to point to the next available field in the VRA. If you do not specify VRAREG, register 14 is the default.
,WORKREG=reg: Specifies a work register. Each time you invoke the VRADATA macro, the contents of this register are destroyed. If you do not specify WORKREG, register 15 is the default.
,TYPE=(LEN,TEST)
,TYPE=(LEN,NOTEST)
,TYPE=(LEN,NOT)
,TYPE=(NOLEN,TEST)
,TYPE=(NOLEN,NOTEST)
,TYPE=(NOLEN,NOT)
,TYPE=(NOL,TEST)
,TYPE=(NOL,NOTEST)
,TYPE=(NOL,NOT): Specifies whether (LEN) or not (NOLEN) you want the current length of the VRA stored in the VRALEN area and also specifies whether (TEST) or not (NOTEST) you want the VRA tested to see if it is full before adding the new entry. If you specify TEST, the current length of the VRA must already be in the VRACLEN area.
If you do not need to store the length or test to see if the new entry fits, specify NOLEN and NOTEST. These specifications considerably reduce the amount of code generated by the VRADATA macro. If you do not specify TYPE, the value LEN, TEST is the default.

ABEND codes

None.

Return and reason codes

None.

Example 1

Initialize the SDWA data area to indicate that the VRA contains hexadecimal data, in key, length, data format. Also, move two pieces of data into the SDWAVRA, and indicate that no test of the length of the VRA is needed, (because the data fits in the VRA). The second request indicates that the length used is to be stored in the VRA current length field. The pieces of data are the IHAVRA mapping macro name and the contents of a control block.

VRADATA VRAINIT=SDWAVRA,KEY=VRACBM,DATA=MYCBNAME,       X
        TYPE=(NOLEN,NOTEST)
VRADATA KEY=VRACB,DATA=MYCB,TYPE=(LEN,NOTEST)

Example 2

Initialize a variable recording area that is not the SDWA. Move in a piece of data, specifying its length. (The piece of data is an ASID.)

VRADATA VRAINIT=LRBTUSR,VRACLEN=LRBTCLEN,               X
        VRAMLEN=LBRTMLEN
VRADATA KEY=VRAAID,DATA=(REGA),LEN=ASIDLEN