Assembler language programming restrictions and requirements

Some restrictions and requirements apply to an assembler language program that is used as a CICS® application program.

LEASM option

The following restrictions apply to an assembler language program that is translated with the LEASM option:

Register 2 cannot be used as a code base register.
Register 12 is reserved by Language Environment® (LE) to point to the Language Environment common anchor area (CAA) and so cannot be used at all by the program without being saved and restored as appropriate.
Register 13 must be used as the only working storage base register.
The program cannot be a Global User Exit program (GLUE) or a Task-Related User Exit program (TRUE).
The program must not use, or depend on, any AMODE(24) code.
AMODE(64) programs are not supported.

LENGTH option in EXEC CICS commands

When you specify a LENGTH option for a CICS command, ensure that the way you use in assembler language specifies a valid halfword length. Do not specify a zero length, or a variable that the CICS translator cannot recognize, because this might cause a storage violation or a program check. For more information, see Assembler language argument values.

The following example of a LINK command specifies the length correctly and passes the address of the variable COMMAL to the command processor:

EXEC CICS LINK PROGRAM('PROG2') COMMAREA(COMMA) LENGTH(COMMAL)
...
COMMA DC CL20'This is the COMMAREA'
COMMAL DC H'20'

The following example also specifies the length correctly:

EXEC CICS LINK PROGRAM('PROG2') COMMAREA(COMMA) LENGTH(=AL2(COMMAL))
...
COMMA DC CL20'This is the COMMAREA'
COMMAL EQU *-COMMA

The following example is incorrect because the CICS translator cannot know the type of the variable COMMAL, and passes the value of COMMAL as the address of the halfword field that contains the length. This could provide a random length value, or a program check if the storage at that address is not available.

EXEC CICS LINK PROGRAM('PROG2') COMMAREA(COMMA) LENGTH(COMMAL)
...
COMMA DC CL20'This is the COMMAREA'
COMMAL EQU *-COMMA

31-bit addressing

The following restrictions apply to an assembler language application program that runs in 31-bit addressing mode:

The COMMAREA option is restricted in a mixed addressing mode transaction environment. For a discussion of the restriction, see Using mixed addressing modes.
CICS does not allow the use of HANDLE ABEND LABEL in assembler language programs that do not use the DFHEIENT and DFHEIRET macros. Assembler language programs that use the Language Environment stub CEESTART should either use HANDLE ABEND PROGRAM or a Language Environment service such as CEEHDLR. See Language Environment abend and condition handling for information about CEEHDLR.

The following restriction applies to an AMODE(24) or AMODE(31) assembler language application program that uses 64-bit registers to use 64-bit addressing mode or 64-bit binary operations:

CICS does not always preserve the high-order words of 64-bit registers. You must save them before you invoke a CICS service, and restore them before using the 64-bit registers again.

64-bit addressing

CICS supports the program execution of non-Language Environment AMODE(64) assembler language CICS applications. Your program must use relative addressing. See Developing AMODE(64) assembler language programs. All CICS API commands, except for those listed later in this section, are supported. For information about the CICS API, see CICS API commands.

The following APIs are not supported for AMODE(64) programs:

CICSPlex® SM application programming interface (API)
CICS API commands for use in APPC basic conversations (GDS commands)
Front End Programming Interface (FEPI)
Common Programming Interface (CPI) Communications API
DL/I requests

The following interfaces are not supported for AMODE(64) programs:

CICS DB2® interface
CICS-MQ bridge external interface

The following CICS API commands are provided for use with AMODE(64) programs:

The following CICS API commands, which are related to nonstructured exception handling, are not supported for AMODE(64) assembler language programs:

HANDLE ABEND LABEL(label)
HANDLE AID
HANDLE CONDITION
IGNORE CONDITION
POP HANDLE
PUSH HANDLE

The translator detects use of these commands.

AMODE(64) assembler language programs cannot be invoked by a COBOL, C, C++, or PL/I CALL statement, or by an assembler language CALL macro. However, assembler language application programs can be invoked by COBOL, C, C++, PL/I, or assembler language application programs by using LINK or XCTL commands.

For AMODE(64) assembler language programs, use of the NOHANDLE condition is implied on all EXEC CICS commands. This means that no action will be taken for any condition that results from the execution of that command. You can use the RESP option with any command to test whether any condition was raised during execution of that command. See RESP and RESP2 options and NOHANDLE option.

For AMODE(64) assembler language programs, CICS uses the whole of the 64-bit register. Ensure that all of the register is valid.

A COMMAREA cannot be in 64-bit storage. For more information the COMMAREA, see COMMAREA.

AMODE 64 task-related user exits (TRUEs) are not supported, and AMODE(64) applications cannot invoke a TRUE.

For more information about using 64-bit addressing mode and 64-bit binary operations, see z/OS MVS Programming: Assembler Services Guide.

64-bit residency

CICS does not support 64-bit residency mode (RMODE(64)) and treats any RMODE(64) programs as RMODE(31). That is, RMODE(64) programs are loaded into 31-bit (above-the-line) storage, not 64-bit (above-the-bar) storage.

Access registers

The following restrictions apply to an assembler language application program that uses access registers to use the extended addressability of z/Architecture® systems:

You must be in primary addressing mode when invoking any CICS service. The primary address space must be the home address-space. All parameters passed to CICS must reside in the primary address space.
CICS does not always preserve access registers. You must save them before you invoke a CICS service, and restore them before using the access registers again.

For more guidance information about using access registers, see z/OS MVS Programming: Extended Addressability Guide.

BAKR instructions (branch and stack)

When using BAKR instructions (branch and stack) to provide linkage between assembler language programs, ensure that the linked-to program does not issue EXEC CICS requests. If CICS receives control and performs a task switch before the linked-to program returns by a PR instruction (program return), other tasks might be dispatched and issue further BAKR / PR calls. These calls modify the linkage-stack and result in the wrong environment being restored when the original task issues its PR instruction.

Instructions that cannot be used

You cannot use the following instructions in an assembler language program that is used as a CICS application program:

COM: Identify blank common control section.
ICTL: Input format control.
OPSYN: Equate operation code.

Comments

If you want to add comments against CICS commands, you can do this, in assembler language only, by using a period or a comma as a delimiter after the last argument. For example:

EXEC CICS ADDRESS EIB(MYUEIB),        @F1A

If a period or a comma is used with an EXEC CICS command, the following line must begin between column 2 and column 16, with the continuation character in column 72. The following line cannot start after column 17. If there is no comma or period added, the following line must begin at or after column 2 and end by column 71, with the continuation character in column 72.