Setting Up

To make its services available to other address spaces through a PC instruction, the service provider sets up the authorization structures and the linkage and entry tables.

To request that the system reserve an authorization index (AX) for the service provider's address space, or an extended authorization index (EAX) for a PC routine, the service provider issues the AXRES macro. The AX or EAX is reserved across the entire system. The home address space at the time the AXRES macro is issued becomes the owner of the AX or EAX:

       LA     2,1
       STH    2,AXCOUNT        REQUEST 1 AX
GETAX  AXRES  AXLIST=AXL,RELATED=FREEAX

See Extended authorization index (EAX), Types of access list entries and EAX-authority to an address space for more information about the EAX.

To set the AX of the service provider's address space to the AX value that MVS™ reserved, the service provider issues the AXSET macro:

SETAX  AXSET  AX=AXVALUE,RELATED=(GETAX,SETAX)

To request that the system reserve a non-system LX for later use, the service provider issues the LXRES macro to reserve a 4-byte LX. A non-system LX allows a service provider to connect to selected users. The home address space at the time the LXRES macro is issued becomes the owner of the LX:

         .
         .
         LA      2,1
         ST      2,LXCOUNT          REQUEST 1 LX
GETLX    LXRES   LXLIST=LXL,RELATED=FREELX
         .
         .

To request that the system provide a non-system extended LX value, issue the following:

         .
         .
         LA     2,1
         ST     2,ELXCOUNT  REQUEST 1 EXTENDED LX
 GETLX   LXRES  ELXLIST=ELXL,RELATED=FREELX
         .
         .

To request that the LX be a reusable extended non-system LX value, issue the following:

         .
         .
       	LA     2,1
       	ST     2,ELXCOUNT  REQUEST 1 EXTENDED LX
GETRLX 	LXRES  ELXLIST=ELXL,REUSABLE=YES,RELATED=FREERLX
         .
         .

To define which PC routines will be available to user, the service provider must issue two macros, ETDEF and ETCRE. The ETDEF macro builds an entry table descriptor (ETD). Each ETD defines a PC routine. The ETCRE macro uses the ETDs as input to build an entry table. The entry table contains ETD entries for each of the PC routines that the service provider is making available to the user. The home address space at the time the service provider issues the ETCRE macro becomes the owner of the entry table.

There are two ways the service provider can use the ETDEF macro:

If all of the information about the PC routine being defined is available at the time the ETDEF macro is assembled, the service provider can statically define an ETD by specifying the TYPE=ENTRY option.
If some of the information about the PC routine being defined is unavailable when assembling the ETDEF macro, the service provider must issue ETDEF twice: once with TYPE=ENTRY, and once with TYPE=SET. TYPE=ENTRY reserves storage for an ETD entry. TYPE=SET initializes the ETD entry, and overrides any options specified on TYPE=ENTRY. For any options the service provider omits on TYPE=SET, the system uses the default values.
Example: if the service provider specifies TYPE=ENTRY with ASYNCH=NO, and then does not specify the ASYNCH parameter on TYPE=SET, the system uses the default of ASYNCH=YES. (See the description of the ETDEF macro in z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG for more information.)

Use this method if any of the input data is unresolved when assembling the ETDEF macro. For example, a program's name may be known at assembly time, but not the address at which it will be loaded.

To define a complete ETD suitable as input to ETCRE, the service provider must issue the ETDEF macro three or more times:

Once to define the beginning of the table
Once for each PC routine to be defined in the table
Once to define the end of the table.

Note: Instead of issuing ETDEF, the service provider has the option to code the data areas that ETDEF builds. IBM® provides a mapping macro, IHAETD, that maps the format 0 ETD. IBM recommends, however, the use of the ETDEF macro.

The following figure shows how to use ETCRE and ETDEF to create an entry table that defines two stacking PC routines. This example works only when the PC routines are located in LPA or in the nucleus.

Figure 1. Using ETDEF to statically define entry table descriptors

********* Executable Instructions
*
         .
         .
CET1     ETCRE ENTRIES=ETDESC,RELATED=(CONET,DISET1,DESET1)
         ST    0,TKVALUE      Save Returned Token
         .
         .
********* Data Constants
*
ETDESC   ETDEF TYPE=INITIAL,RELATED=(CET1)
         ETDEF TYPE=ENTRY,PROGRAM='SERVICE1',SSWITCH=YES,             X
               STATE=PROBLEM,AKM=(0:15),EKM=8,EK=8,PKM=REPLACE
         ETDEF TYPE=ENTRY,PROGRAM='SERVICE2',SSWITCH=NO,              X
               STATE=SUPERVISOR,AKM=(0:15),EKM=(0:15),PKM=OR
         ETDEF TYPE=FINAL

In the previous example, the first ETDEF macro defines the beginning of the entry table definition.

The second ETDEF macro defines a space switch PC routine named Service1. This PC routine receives control in problem state, requires that all input and output parameters be in key 8 storage, and can reference date that is in key 8 storage only. This example of the ETDEF macro shows how to define a stacking PC routine that decreases authority.

The routine is a stacking PC because PC=STACKING is the default.
The STATE=PROBLEM parameter specifies that the PC routine will receive control in problem state.
The parameter AKM=(0:15) specifies that programs running with any PSW key may invoke the PC routine.
The parameter EK=8 specifies that the PC routine will run with PSW key 8.
The parameter PKM=REPLACE specifies that the system is to replace the PSW-key mask with the mask specified by the parameter EKM=8 before invoking the PC routine.

The third ETDEF macro defines a non-space switch PC routine named Service2. This PC routine can reference input/output parameters in any key. This example of the ETDEF macro shows how to define a stacking PC routine that increases authority.

The routine is a stacking PC because PC=STACKING is the default.
The STATE=SUPERVISOR parameter specifies that the PC routine, Service2, will receive control in supervisor state.
The parameter AKM=(0:15) specifies that programs running with any PSW key may invoke the PC routine.
The parameter EKM=(0:15) specifies that the program will run with all PKM bits on.
The parameter PKM=OR specifies that the system is to OR the PSW key mask of the caller with the mask specified by EKM=(0:15) before invoking the PC routine.

The last ETDEF macro defines the end of this entry table definition.

When a PC routine is not in LPA and is not in the nucleus, the service provider will not know the location of the PC routine until it is loaded. Also, the service provider will not know the address of the PC routine's associated recovery routine (ARR) until it is loaded, and will not know the EAX value until the AXRES macro is issued. Therefore, the service provider must create at least part of the entry table definitions dynamically. The following figure shows how the service provider could create the entry table if the PC routine, Service1, and the ARR, ARR1, were loaded into private storage first. The figure shows code for a non-reentrant program. ETDEF TYPE=SET specifies a complete entry replacement. All options are either set or defaulted. Nothing is carried over from the TYPE=ENTRY declaration. Note that, in this example, the service provider uses the AX value, provided through the AXRES macro, as an EAX value.

Figure 2. Using ETDEF to dynamically define entry table descriptors

*
********* Executable Instructions
*
         LA   1,1(0)
         ST   1,AXNUM
         AXRES AXLIST=AXL              GET AN EAX FOR SERVICE1 (THE     X
                                             PC ROUTINE)
         L    4,AXVAL
         LOAD EP=SERVICE1              GET ADDRESS OF SERVICE1
         ST   0,SRV1ADDR               SAVE ADDRESS OF SERVICE1
         LR   2,0
         LOAD EP=ARR1                  GET ADDRESS OF ARR1
         ST   0,ARR1ADDR               SAVE ADDRESS OF ARR1
         LR   3,0
         .
         .
         ETDEF TYPE=SET,ETEADR=ETD1,ROUTINE=(2),SSWITCH=YES,          X
               STATE=PROBLEM,AKM=(0:15),EKM=8,EK=8,PKM=REPLACE,       X
               ARR=(3),EAX=(4)
         .
         .
CET1     ETCRE ENTRIES=ETDESC,RELATED=(CONET,DISET1,DESET1)
         ST    0,TKVALUE               SAVE RETURNED TOKEN
*
********* Data Definition area
*
SRV1ADDR DS F                          ADDRESS OF SERVICE1
ARR1ADDR DS F                          ADDRESS OF ARR1
ETDESC   ETDEF TYPE=INITIAL
ETD1     ETDEF TYPE=ENTRY,ROUTINE=0
ETD2     ETDEF TYPE=ENTRY,PROGRAM='SERVICE2',SSWITCH=NO,              X
               STATE=SUPERVISOR,AKM=(0:15),EKM=(0:15),PKM=OR
         ETDEF TYPE=FINAL
AXL      DS 0F                         AXLIST
AXNUM    DS H                          NUMBER OF AXs REQUESTED
AXVAL    DS H                          RETURNED AX (OR EAX)

The preceding example of the ETDEF macro shows how to define a stacking PC routine that uses an ARR and an EAX:

The parameter ROUTINE=(2) specifies that the PC entry point address is in register 2.
The parameter ARR=(3) specifies that the address of the ARR to receive control if the stacking PC routine ends abnormally is in register 3.
The parameter EAX=(4) specifies that the EAX value for the PC routine is in register 4.

Once the linkage and entry tables have been created, the service provider can construct the PC numbers that identify the PC routines. A PC number is a fullword value formed by combining an LX and an EX.

The LXRES macro returns the LX in the format that's shown below. This format allows the service provider to OR the LX with an EX to form a PC number:

Shown below is an LX that is available only when the LX reuse facility is enabled:

The LXRES macro returns the LX in the format that's shown below. This format allows the service provider to OR the LX with an EX to form a PC number:

          L   2,LXVALUE        LX=PC# WITH EX OF 0
          ST  2,SERV1PC        SAVE EX=0 PC# FOR FIRST SERVICE
          LA  2,1(,2)          CONSTRUCT EX=1 PC#
          ST  2,SERV2PC        SAVE PC# FOR SECOND SERVICE

To make the PC numbers accessible, the service provider can save the address of its SERVBLK by using name/token callable services:

          LA   2,SERVBLK
          ST   2,SERVBLKA
          CALL IEANTCR,(LEVEL,NAME,TOKEN,PERSOPT,RETCODE)
          .
          .
          .
LEVEL     DC   A(IEANT_SYSTEM_LEVEL)
NAME      DC   CL16'SERVBLK'
TOKEN     DS   0XL16
SERVBLKA  DS   A
          DS   XL12
PERSOPT   DC   A(IEANT_NOPERSIST)
RETCODE   DS   F
          IEANTASM             INCLUDE NAME/TOKEN SERVICES          X
                               ASSEMBLER DECLARATION STATEMENTS