The interfaces described in this section reflect what is possible on an MVS/XA system. When determining the attributes and linkage conventions for a program, you should analyze both the program's individual interfaces and its overall interactions with other programs. This section provides specific guidelines for making these determinations.
Control Program Interfaces
With the exception of the TEST command processor, which the TMP loads below 16 megabytes and invokes in 31-bit addressing mode, the IBM-supplied command processors are loaded below 16 megabytes and must receive control in 24-bit addressing mode. Refer to "Testing a Newly-Written TMP or CP -- The TEST Command" for additional information on the TEST command and its services.
The command processor parameter list (CPPL) passed by IBM-supplied control programs resides below 16 megabytes.
User-written TMPs and CPs may execute in either 24- or 3l-bit addressing mode provided they follow the restrictions involved in invoking programs that have 24-bit dependencies. When assigned the AMODE= 31 attribute, they may be loaded above 16 megabytes (RMODE = ANY), and passed input that resides above 16 megabytes.
Service Routine Interfaces
The data type processor (IKJEBEPS) and the ST A interface routine (IKJEHSIR) must be invoked in 24-bit addressing mode. All input passed to these two routines must reside below 16 megabytes.
If a program running in 31-bit addressing mode invokes one of these two routines, the LINK macro should be used to invoke it because LINK does not require the invoking program to switch to 24 .. bit addressing mode. In this case, LINK switches to 24-bit mode on behalf of the invoking program. If a program is loaded above 16 megabytes, it must use LINK to invoke IKJEBEPS or IKJEHSIR.
Chapter 4. MVS/Extended Architecture Considerations
4-3
Macro Interfaces
The following service routines can be invoked in either 24- or 31-bit addressing mode, but all input passed to these routines must reside below 16 megabytes.
These routines execute in 24-bit addressing mode and return control in the same addressing mode in which they are invoked:
IKJEHCIR Catalog information routine IKJEHDEF Default service routine
The following service routines can be invoked in either 24- or 31-bit addressing mode. When invoked in 31-bit addressing mode, these routines may be passed input that resides above 16 megabytes. These routines execute and return control in the same addressing mode in which they are invoked:
IKJDAIR IKJEFF18 IKJEFF19 IKJEFTSR
Dynamic allocation interface routine DAIRFAIL
GNRLFAIL/VSAMFAIL TSO service routine
The following service routines can be invoked in either 24-bit or 31-bit addressing mode. They execute in 31-bit addressing mode and can accept input above or below 16 megabytes. These routines will return control in the same addressing mode in which they are invoked:
IKJEFF02 TSO message issuer routine IKJGETL GETLINE service routine IKJPARS Parse service routine IKJPTGT PUTGET service routine IKJPUTL PUTLINE service routine IKJSCAN Command scan service routine IKJSTCK STACK service routine IKJCT441 CLIST variable access routine
Note that the list source descriptor (LSD) must reside below 16 megabytes. The output line descriptor (OLD) can reside above 16 megabytes.
STAX (specify terminal attention exit routine) may be invoked in either 24- or 31-bit addressing mode. Refer to "Attention Interruption Handling -- The STAX Service Routine" for more information.
Refer to "Passing Control to the TSO Service Routines" later in this book for more detailed descriptions of interfacing with the routines listed in this section.
Figure 4-1 shows the MVS/Extended Architecture rules for the macros discussed in this manual.
Note: In Figure 4-1, a dash (-) indicates that the category does not apply to the macro because the macro does not generate executable code. The addressing mode of the program that accesses the data generated by the macro must agree with the residence of the data.
4-4 TSOjE Guide to Writing a TMP or a CP
(P) May Be Issued by Program (X) May Be Issued In (I) Input May Be
Macro 24-Bit Mode 31-Bit Mode Below 16Mb Above 16Mb
ATTACH X X I,P I,P
CALL X X I,P I,P
CALLTSSR X X P P
ESTAE X X I,P I,P
FESTAE X X I,P I,P
GETLINE X X I,P I,P
GTSIZE X X P P
GTTERM X P
IKJENDP - - P P
IKJIDENT - - P P
IKJKEYWD - - P P
IKJNAME - - P P
IKJOPER - - P P
IKJPARM - - P P
IKJPOSIT - - P P
IKJRLSA X X P P
IKJRSVWD - - P P
IKJSUBF - - P P
IKJTERM - - P P
IKJTSMSG - - P P
LINK X X I,P I,P
LOAD X X I,P I,P
PUTGET X X I,P I,P
PUTLINE X X I,P I,P
RTAUTOPT X X P P
SAM Macros X I,P
SPAUTOPT X X P P
STACK X X I,P I,P
STAE X I,P
STATTN X I,P
STAUTOCP X X P P
STAUTOLN X I,P
STAX X X I,P See section on
STAX.
STBREAK X I,P
STCC X I,P
STCLEAR X I,P
Figure 4-1 (Part 1 of 2). MVS/XA Interface Rules for Macro Instructions
Chapter 4. MVS/Extended Architecture Considerations
4-5
(P) May Be Issued by Program (X) May Be Issued In (I) Input May Be
Macro 24-Bit Mode 31-Bit Mode Below 16Mb Above 16Mb
STCOM X I,P
STFSMODE X I,P
STLINENO X I;P
STSIZE X I,P
STTIMEOU X I,P
STTMPMD X I,P
STTRAN X I,P
TCLEARQ X I,P
TGET X X I,P
TPG X X I,P
TPUT X X I,P
XCTL X X I,P I,P
Figure 4-1 (Part 2 of 2). MVS/XA Interface Rules for Macro Instructions
I
Notes on Figure 4-1I
ATTACH,LINK,LOAD,XCTL
A program may issue the ATTACH, LINK, LOAD, and XCTL macro instructions while executing in either 24- or 3l-bit addressing mode. These system services determine where to load the requested program in storage and in which addressing mode to invoke it based on the program's AMODE and RMODE attributes. Note that LOAD only loads a program; it does not invoke it. LOAD returns the address of the loaded program. The high-order bit of this address reflects the AMODE attribute of the loaded program.
If a program is invoked via a LINK, ATTACH, or XCTL macro, it receives control in the addressing mode specified or allowed by its AMODE
attribute. On the other hand, if a program branches to another program without changing addressing modes via the BASSM or BSM branch instructions, the requested program receives control in whatever addressing mode is active at the time of the branch -- that is, in the addressing mode of the caller.
For more information on these macros, refer to System Macros and Facilities.
CALL
You may use the CALL macro to invoke a program if that program may be invoked in the current addressing mode.
CALLTSSR
The CALLTSSR macro instruction may be issued in either 24- or 3l-bit addressing mode. See "Passing Control to the TSO Service Routines" later in this book for more irformation on issuing the CALL TSSR macro.
4-6 TSO/E Guide to Writing a TMP or a CP
ESTAE,FESTAE, STAE, ESTAI
The EST AE and FEST AE macros may be issued in either 24- or 31-bit addressing mode. Refer to "EST AE/EST AI Exit Routines -- Intercepting an ABEND" for more information. Use of the STAE macro and the EST AI operand on the ATTACH macro to establish recovery exits and routines is not recommended. If they are used, the recovery exits and routines must receive control in 24-bit addressing mode -- that is, the STAE and ATTACH macros must be issued in 24-bit addressing mode.
EST AI
See ESTAE.
FESTAE
See ESTAE.
GETLINE, PUTGET, PUT LINE, STACK
The GETLINE, PUTGET, PUTLINE, and STACK macros can be issued in either 24-bit or 31-bit addressing mode. These routines execute in 31-bit addressing mode and return control in the same addressing mode in which they are invoked. Input passed to these routines may reside above or below 16 megabytes. However, if you use the STACK macro, the list source descriptor (LSD) must reside below 16 megabytes.
IKJTSMSG
The IKJTSMSG macro may be issued by a program loaded below or above 16 megabytes. Refer to "Message Handling" for a description of the standard and extended formats of the input parameter list for IKJEFF02.
LINK
See ATTACH.
LOAD
See ATTACH.
Parse Macros
If the parse service routine is invoked in 31-bit addressing mode, the parse parameter list, mapped by IKJPPL, may reside above 16 megabytes and the parse macro instructions may be issued by a program loaded above 16 megabytes. See Figure 4-1 for a list of the parse macros and their linkage requirements. The IKJRLSA parse macro may be issued in either 24- or 31-bit addressing mode.
PUT GET
See GETLINE.
PUTLINE
See GETLINE.
SAM Macros
The sequential access method (SAM) terminal macro instructions must be issued in 24-bit addressing mode.
Chapter 4. MVS/Extended Architecture Considerations 4-7
STACK
SeeGETLINE.
STAE
See ESTAE.
STAX
A program may issue the STAX macro in either 24- or 31-bit addressing mode. Refer to "Specifying a Terminal Attention Exit -- The ST AX Macro Instruction" for specific restrictions.
SVC 93 (TGET, TPUT, TPG)
SVC93 (TGET, TPUT, and TPG macros) executes in 24-bit addressing mode. All input passed to SVC93 must reside below 16 megabytes.
Programs can invoke TGET, TPUT, and TPG in 24-bit or 31-bit addressing mode.
SVC 94 (Terminal Control Macros)
SVC 94 (terminal control macros) executes in 24-bit addressing mode. With a few exceptions, terminal control macros must be issued in 24-bit
addressing mode. The exceptions are the GTSIZE, RTAUTOPT, SPAUTOPT, and STAUTOCP terminal control macros, which may be issued in 31-bit addressing mode. See Figure 4-1 for a list of the terminal control macros and their linkage requirements.
TGET, TPUT, TPG See SVC 93.
Terminal Control Macros See SVC 94.
XCTL
See ATTACH.