ETDEF — Create an entry table descriptor (ETD)

Description

The ETDEF macro builds and modifies the parameter that the ETCRE macro uses to build an entry table. The parameter, called the entry table descriptor (ETD), consists of a header, followed by one or more entries, called ETD entries, each one describing a PC routine. The address of the ETD is input to the ENTRIES parameter on the ETCRE macro.

The TYPE parameter on the ETDEF macro determines which process the ETDEF macro is to perform:

ETDEF TYPE=INITIAL generates the header for the ETD. (Issue this macro once for each ETD.)
ETDEF TYPE=ENTRY generates one ETD entry. (You can issue this macro up to 256 times for each ETD.)
ETDEF TYPE=FINAL terminates the ETD. (Issue this macro once for each ETD.)
ETDEF TYPE=SET,ETEADR replaces the variable fields of an existing ETD entry.
ETDEF TYPE=SET,HEADER changes the number of entries in an existing ETD header.

Related macros

ETDES, ETCRE, ETCON, and ETDIS

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem or Supervisor state
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN or PASN¬=HASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Serialization:	Not applicable
Interrupt status:	None
Locks:	None
Control parameters:	None

Programming requirements

You need to create an ETD at compile time through TYPE=INITIAL, TYPE=ENTRY, and TYPE=FINAL parameters and initialize the information for the entries at execution time through TYPE=SET,ETEADR. Therefore, ETDEF with the TYPE=INITIAL, TYPE=ENTRY, and TYPE=FINAL parameters works like a list form of the macro. However, unlike the execute form of a macro, which changes only the values you specify, the TYPE=SET form of ETDEF completely replaces the variable fields of an ETD entry, taking the default values for any parameters you omit, and leaves constant fields as initialized. This information describes the two forms separately.

Although ETDEF is the preferred programming interface, if you have an existing ETD and you want to update the parameters (for example, change the user parameter), you might choose to use the IHAETD mapping macro instead of ETDEF. If you change an existing ETD, without using any of the function of MVS/SP Version 3, you can use IHAETD with the format number of “0”. The format of IHAETD is in z/OS MVS Data Areas in the z/OS Internet library under "ETD".

Note: When changing code to use ETDEF in place of the IHAETD mapping macro, be sure to specify PC=BASIC so that the PC does not become a stacking PC. If you want to change an existing PC routine to a stacking PC, be sure to change the PT instruction in the PC routine to a PR.

Restrictions

None.

Register information

The ETDEF macro does not use any registers, except for those you use to specify parameters.

Performance implications

None.

TYPE=INITIAL, TYPE=ENTRY, and TYPE=FINAL parameters

The ETDEF macro with the TYPE=INITIAL, TYPE=ENTRY, and TYPE=FINAL options works like a list form of a macro.

Syntax

This form is described as follows:

Syntax	Description

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

␢	One or more blanks must precede ETDEF.

ETDEF

␢	One or more blanks must follow ETDEF.

TYPE=INITIAL	Valid Parameters: RELATED
TYPE=ENTRY	Required Parameters: PROGRAM or ROUTINE, AKM
	EKM, ARR, ASCMODE, EAX, EK, PARM1, PARM2, PC, PKM, SASN, SSWITCH, STATE, RELATED, ASYNCH, CANCEL

TYPE=FINAL	RELATED

,AKM=`key-list`	`key-list`: List of keys or key ranges where a key is a number 0 - 15.

,ARR=`arr`	`arr`: A-type address, or alphanumeric character string enclosed by single quotation marks.

,ARRCOND=NO	Default: ARRCOND=NO
,ARRCOND=YES	Valid only when ARR is also coded.

,ASYNCH=YES	Default: ASYNCH=YES
,ASYNCH=NO	Valid only when ARR is also coded.

,CANCEL=YES	Default: CANCEL=YES
,CANCEL=NO	Valid only when ARR is also coded.

,ASCMODE=PRIMARY	Default: ASCMODE=PRIMARY
,ASCMODE=AR

,EAX=`eax-value`	`eax-value`: Half-word decimal digit.

,EK=`entry-key`	`entry-key`: Decimal digit 0 - 15.

,EKM=`key-list`	`key-list`: List of keys or key ranges where a key is a number 0 - 15.
Note: EKM is required with PKM=REPLACE.

,PARM1=`user-parm1`	`user-parm1`: A-type address or string of up to 4 characters enclosed by single quotation marks.

,PARM2=`user-parm2`	`user-parm2`: A-type address or string of up to 4 characters enclosed by single quotation marks.

,PC=STACKING	Default: PC=STACKING
,PC=BASIC

,PROGRAM=`pgm-name`	`pgm-name`: String of up to 8 alphanumeric characters, optionally enclosed by single quotation marks.

,ROUTINE=`rtn-addr`	`rtn-addr`: A-type address.

,PKM=OR	Default: PKM=OR
,PKM=REPLACE

,RAMODE=31	Default: RAMODE=31
,RAMODE=24
,RAMODE=64

,RELATED=`value`	`value`: Any valid macro parameter specification.

,SASN=OLD	Default: SASN=OLD
,SASN=NEW

,SSWITCH=NO	Default: SSWITCH=NO
,SSWITCH=YES

,STATE=PROBLEM	Default: STATE=PROBLEM
,STATE=SUPERVISOR

Parameters

The parameters are described as follows:

TYPE=INITIAL

Generates the header for the ETD.

TYPE=ENTRY

Generates an ETD entry. The system uses the defaults for any parameters you do not specify on the ETDEF TYPE=ENTRY macro. When you later specify ETDEF TYPE=SET, that macro initializes the entire ETD entry.

TYPE=FINAL

Specifies that the ETD is complete.

,AKM=key-list

Specifies a list of keys (0 through 15) or key ranges, optionally enclosed in parentheses, that identifies the authorized keys in which a problem program can use the PC routine. For example, AKM=(2,(3),5:8,(10:12),15) would authorize keys 2, 3, 5, 6, 7, 8, 10, 11, 12, and 15.

,ARR=arr

Specifies the associated recovery routine (ARR) that receives control if the stacking-PC routine abends. You can use the A-type address of the routine, or the name of the routine (an alphanumeric character string) enclosed in single quotation marks. If you use the name of the program, the program must be on the active LPA queue (FLPA or MLPA) or be in the PLPA or nucleus. The recovery routine will be entered in 31-bit mode. ARR is not valid with PC=BASIC.

,ARRCOND=NO,ARRCOND=YES

Specifies whether or not the ARR is conditional.

ARRCOND=NO, indicates that the ARR is not conditional, which means that the system follows the rules described in "Using ARRs" found in z/OS MVS Programming: Authorized Assembler Services Guide with respect to recording in LOGREC error recording if the ARR is skipped. ARRCOND=YES indicates that no recording in LOGREC error recording is to occur if the ARR is skipped.

Use ARRCOND=YES to avoid having to provide two PCs, one without an ARR for use in an FRR environment, and one with an ARR for use when not in an FRR environment.

ARRCOND is valid only with ARR.

,ASYNCH=YES

,ASYNCH=NO

Specifies whether or not the ARR can be interrupted by asynchronous exits. ASYNCH=YES specifies that the ARR can be interrupted by asynchronous exits. ASYNCH=NO specifies that the ARR cannot be interrupted by asynchronous exits. ASYNCH=YES is the default. ASYNCH is valid only with ARR.

,CANCEL=YES

,CANCEL=NO

Specifies whether or not the ARR can be interrupted by CANCEL/DETACH processing. CANCEL=YES specifies that the ARR can be interrupted by CANCEL/DETACH processing. CANCEL=NO specifies that the ARR cannot be interrupted by CANCEL/DETACH processing. CANCEL=YES is the default. CANCEL is valid only with ARR. To specify CANCEL=NO, one of the following conditions must be true for the stacking PC routine protected by the ARR:

The stacking PC routine runs in supervisor state.
The entry key for the stacking PC routine is a system key.
The stacking PC routine runs with a system key valid for the entry key mask that will either replace or be ORed with the PKM.

,ASCMODE=PRIMARY

,ASCMODE=AR

Specifies that the stacking PC routine will execute in primary ASC mode (ASCMODE=PRIMARY) or in AR ASC mode (ASCMODE=AR). ASCMODE=AR is not valid with PC=BASIC. ASCMODE=PRIMARY is the default.

,EAX=eax-value

Specifies the extended authorization index (EAX) that the stacking PC routine uses. Specify an EAX that is owned by the home address space of the issuer of the ETCRE macro. An EAX of X'0000' means the PC routine is not EAX-authorized. If EAX is not specified, the PC routine has the same EAX as the issuer of the PC instruction. EAX is not valid with PC=BASIC.

,EK=entry-key

Specifies the PSW key (0 through 15) that the PC routine will run in. EK is not valid with PC=BASIC. If you omit EK, the PC routine gets control in the key of the caller.

,EKM=key-list

Specifies a list of keys (0 through 15) or key ranges, optionally enclosed in parentheses, that identify the entry key mask (EKM). When the PC routine is invoked, the keys specified identify either the additional keys that are to be ORed into the PKM (if PKM=OR is also specified or taken as the default) or the keys that should replace the PKM (if PKM=REPLACE is specified). EKM is required when you specify PKM=REPLACE.

,PARM1=user-parm1

Specifies the address or character string to be placed in the first word of the latent parameter area associated with this ETD entry.

Addressability to the latent parameter area is through the current primary address space. The latent parameter address is set in general register 4 as a result of the PC instruction, although AR4 is unchanged by the PC instruction. If the PC routine runs in AR mode, set the access register corresponding to the latent parameter area to zero before the PC routine attempts to use it.

,PARM2=user-parm2

Specifies the address or character string to be placed in the second word of the latent parameter area associated with this ETD entry.

,PC=STACKING

,PC=BASIC

Indicates that this is a stacking PC (STACKING) or not a stacking PC (BASIC). Some parameters apply only to a stacking PC. STACKING is the default.

,PROGRAM=pgm-name

,ROUTINE=rtn-addr

Specifies the PC routine. When you specify PROGRAM, the PC routine must be on the active LPA queue (FLPA or MLPA) or be in the PLPA or nucleus. The same restriction applies also to ROUTINE, unless this is a space-switching PC or the PC is to be used only in the address space that established it. In other words, the PC routine for a space-switching PC can reside in the private area of the address space in which it will run, but the ROUTINE parameter must be used to specify it.

When you specify ROUTINE, you can indicate the AMODE of the PC routine with the RAMODE parameter. When you specify PROGRAM, the system locates the PC routine and determines its AMODE.

On TYPE=ENTRY or TYPE=SET,ETEADR, either PROGRAM or ROUTINE is required.

,PKM=OR

,PKM=REPLACE

Indicates either that the entry key mask (EKM) is ORed with the PSW key mask (PKM) or replaces the current PKM. PKM=REPLACE is not valid with PC=BASIC. PKM=OR is the default.

,RAMODE=31

,RAMODE=24

,RAMODE=64

Specifies the AMODE of the routine specified on the ROUTINE parameter. RAMODE is valid only with ROUTINE. If you specify PROGRAM rather than ROUTINE, the system locates the routine and determines its AMODE. RAMODE=31 is the default.

,RELATED=value

Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.

,SASN=OLD

,SASN=NEW

Specifies whether the stacking PC routine will execute with SASN equal to the caller's PASN (SASN=OLD), or with SASN equal to the PASN of the stacking PC routine (SASN=NEW). SASN=NEW is not valid with PC=BASIC. SASN=OLD is the default.

,SSWITCH=NO

,SSWITCH=YES

Specifies whether or not the PC routine switches address spaces. If SSWITCH=NO is specified, the PC does not switch address spaces. If SSWITCH=YES is specified, the PC routine will execute in the address space of the creator of the entry table with the authority of that address space. SSWITCH=NO is the default.

,STATE=PROBLEM

,STATE=SUPERVISOR

Specifies which state the PC routine will receive control in either problem state (PROBLEM) or supervisor state (SUPERVISOR). The default is STATE=PROBLEM.

An example of using the ETDEF macro follows the description of the TYPE=SET parameter.

TYPE=SET parameter

The ETDEF macro with the SET parameter works similarly to the execute form of a macro with this important distinction: The TYPE=SET form totally replaces all variables in an ETD entry and takes default values for all parameters you omit. The normal execute form of a macro changes only the values you specify.

Constants and reserved fields that are initialized by other TYPE= forms are not updated or changed. To create an entry table in a storage area that is not initialized (for example, one just allocated through a GETMAIN request), you must first move a complete entry table of the proper (or larger) size to that area. The formatted table will provide the constants and indexes. Then, you can use ETDEF TYPE=SET to change the required entry's variable parameters.

Syntax

The form of SET is described as follows:

Syntax	Description

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

␢	One or more blanks must precede ETDEF.

ETDEF

␢	One or more blanks must follow ETDEF.

TYPE=SET,ETEADR=`entry-addr`	Required Parameters: PROGRAM or ROUTINE, AKM
	Valid Parameters: EKM, ARR, ASCMODE, EAX, EK, PARM1, PARM2, PC, PKM, RAMODE, SASN, SSWITCH, STATE, RELATED, ASYNCH, CANCEL
	`entry-addr`: RX-type address or register (1) - (15).

TYPE=SET,HEADER=`header-addr`	Required Parameter: NUMETE
	Valid Parameter: RELATED
	`header-addr`: RX-type address or register (1) - (15).

,AKM=`key-list`	`key-list`: List of keys or key ranges where a key is a decimal digit 0 - 15.

,ARR=`arr`	`arr`: A-type address, register (2)-(12), or alphanumeric character string, enclosed by single quotation marks.

,ARRCOND=NO	Default: ARRCOND=NO
,ARRCOND=YES	Valid only when ARR is also coded.


,ASYNCH=YES	Default: ASYNCH=YES
,ASYNCH=NO	Valid only when ARR is also coded.

,CANCEL=YES	Default: CANCEL=YES Valid only when ARR is also coded.
,CANCEL=NO

,ASCMODE=PRIMARY	Default: ASCMODE=PRIMARY
,ASCMODE=AR

,EAX=`eax-value`	`eax-value`: Half-word decimal digit or register (2)-(12)

,EK=`entry-key`	`entry-key`: Decimal digit 0 - 15.

,EKM=`key-list`	`key-list`: List of keys or key ranges where a key is a decimal digit 0 -15.
	Note: EKM is required with PKM=REPLACE.

,NUMETE=`nbr-of-entries`	`nbr-of-entries`: 2-byte A-type address, decimal number, or register (2)-(12).
	Note: NUMETE is required with HEADER.

,PARM1=`user-parm1`	`user-parm1`: A-type address, register (2)-(12), or string of up to 4 characters enclosed by single quotation marks.

,PARM2=`user-parm2`	`user-parm2`: A-type address, register (2)-(12), or string of up to 4 characters enclosed by single quotation marks.

,PC=STACKING	Default: PC=STACKING
,PC=BASIC

,PROGRAM=`pgm-name`	`pgm-name`: String of up to 8 alphanumeric characters, optionally enclosed by single quotation marks.
,ROUTINE=`rtn-addr`	`rtn-addr`: A-type address or registers (2)-(12)

,PKM=OR	Default: PKM=OR
,PKM=REPLACE

,RAMODE=31	Default: RAMODE=31
,RAMODE=24
,RAMODE=64

,RELATED=`value`	`value`: Any valid macro parameter specification.

,SASN=OLD	Default: SASN=OLD
,SASN=NEW

,SSWITCH=NO	Default: SSWITCH=NO
,SSWITCH=YES

,STATE=PROBLEM	Default: STATE=PROBLEM
,STATE=SUPERVISOR

Parameters

The parameters are described under the TYPE=INITIAL, TYPE=ENTRY, and TYPE=FINAL options, with the following exceptions:

,ARRCOND=NO,ARRCOND=YES

Specifies whether or not the ARR is conditional.

ARRCOND=NO, which is the default, indicates that the ARR is not conditional, which means that if the system skips the ARR because of an incorrect environment, that fact is recorded in LOGREC error recording.

ARRCOND=YES indicates that if the system skips this ARR, that fact will not be recorded in LOGREC error recording. Use ARRCOND=YES to avoid having to provide two PCs, one without an ARR for use in an FRR environment, and one with an ARR for use when not in an FRR environment.

ARRCOND is valid only with ARR.

,NUMETE=nbr-of-entries

Specifies the number of contiguous entries in the ETD. nbr-of-entries is a decimal value from 1 to 256. NUMETE is required with the HEADER parameter. Use it to specify the number of entries you will use. It does not change the physical size of the table, but can be less than the initial size.

TYPE=SET,ETEADR=entry-addr

Specifies the address of the ETD entry. ETDEF TYPE=SET,ETEADR sets all the variable fields in the ETD entry that you generated through ETDEF TYPE=ENTRY macro. ETDEF TYPE=SET,ETEADR will set the ETD entry to the parameters you specify and to the defaults on all parameters you omit. That is, the system uses the default value, not the existing value, for any parameter that you omit.

TYPE=SET,HEADER=header-addr

Changes the size of the ETD. Use TYPE=SET,HEADER to decrease the size of the ETD from the size you originally established on ETDEF TYPE=INITIAL.

ABEND codes

None.

Return and reason codes

None.

Example

Define an entry table that has three entries. The PC routine called PCPGM receives control from a program with PSW key authorization of 8, the PC routine named OTHERTN receives control from a program with PSW authorization keys of 0 through 15, and the third PC routine called PCRTN receives control in PSW authorization key 0. The fourth ETDEF is there to show that the number of entries can be changed with ETDEF SET. (Perhaps, because of some input parameter, only a subset of all possible PC routines are set up. On another invocation of the program, perhaps all entries would be used.) The entries use all defaults other than those on the AKM parameter.

MYPGM   CSECT
        BALR 12,0
        USING *,12
        LOAD  EP=PCPGM
        LR    2,0
        ETDEF TYPE=SET,HEADER=MYETDS,NUMETE=3
        ETDEF TYPE=SET,ETEADR=FIRST,ROUTINE=(2),AKM=8
        ETCRE ENTRIES=MYETDS
        RETURN
         .
         .
         .
*             DATA DEFINITIONS FOR PROGRAM
         .
MYETDS  ETDEF TYPE=INITIAL
FIRST   ETDEF TYPE=ENTRY,ROUTINE=0,AKM=8
SECOND  ETDEF TYPE=ENTRY,PROGRAM=OTHERTN,AKM=0:15
THIRD   ETDEF TYPE=ENTRY,ROUTINE=PCRTN,AKM=0
FOURTH  ETDEF TYPE=ENTRY,ROUTINE=0,AKM=0
        ETDEF TYPE=FINAL
*
*
PCRTN   DS    0H
        .
        .
*     PC ROUTINE CODE
        .
        .
        END   MYPGM

Note that the combination of TYPE=INITIAL, ENTRY, and FINAL is essentially the list form of the macro and TYPE=SET is the execute form.