Language Environment coding requirements for assembler language applications

Assembler language programs are classified as either conforming or non-conforming with respect to Language Environment®. Conformance depends on the linkage and register conventions observed, rather than the assembler used.

A Language Environment-conforming assembler language routine is defined as one that is coded using the CEEENTRY and associated Language Environment macros.

Conformance governs the use of assembler programs by call from an HLL program. Both conforming and non-conforming assembler language subroutines can be called either statically or dynamically from C, C++, COBOL or PL/I. However, there are differences in register conventions and other requirements for the two types. For example, to communicate properly with Language Environment-conforming assembler language routines, you must observe certain register conventions on entry to the assembler language routine, while it is running, and on exit from the assembler language routine.

Rules for mixing languages, including assembler language, are discussed in Mixing languages in Language Environment.

64-bit addressing mode is not supported for Language Environment-conforming assembler language programs.

For more detailed information, or for explanations of the terms used in this section, see z/OS Language Environment Programming Guide.

Conforming MAIN programs

If you are coding a new assembler language MAIN program that you want to conform to the Language Environment interface, or if your assembler language routine calls Language Environment services, observe the following:

Use the macros provided by Language Environment. For a list of these macros, see z/OS Language Environment Programming Guide.
Ensure that the CEEENTRY macro contains the option MAIN=YES. ( MAIN=YES is the default).
Translate your assembler language routine with *ASM XOPTS( LEASM) or, if it contains CICS commands, with *ASM XOPTS( LEASM NOPROLOG NOEPILOG).

Conforming subroutines

If you are coding a new assembler language subroutine that you want to conform to the Language Environment interface, or if your assembler language routine calls Language Environment services, observe the following:

Use the macros provided by Language Environment. For a list of these macros, see z/OS Language Environment Programming Guide.
Ensure that the CEEENTRY macro contains the option MAIN=NO. ( MAIN=YES is the default).
Translate your assembler language routine with *ASM XOPTS(NOPROLOG NOEPILOG) if it contains CICS commands.
Ensure that the CEEENTRY macro contains the option NAB=NO if your routine is invoked by a static call from VS COBOL II. (NAB is Next Available Byte (of storage). NAB=NO means that this field might not be available, so the CEEENTRY macro generates code to find the available storage.)

Register conventions for entry into conforming routines

On entry into a Language Environment-conforming assembler language subroutine, the following registers must contain the following values when NAB=YES is specified on the CEEENTRY macro:

R0: Reserved
R1: Address of the parameter list, or zero
R12: Common anchor area (CAA) address
R13: Caller's dynamic storage area (DSA)
R14: Return address
R15: Entry point address

Language Environment-conforming HLLs generate code that follows these register conventions, and the supplied macros do the same when you use them to write your Language Environment-conforming assembler language routine. On entry to an assembler language routine, CEEENTRY saves the caller's registers (R14 through R12) in the DSA provided by the caller. It allocates a new DSA and sets the NAB field correctly in this new DSA. The first halfword of the new DSA is set to binary zero and the back chain in the second word is set to point to the caller's DSA.

Register conventions while a conforming routine is running

R13 must point to the DSA of the routine at all times while the Language Environment-conforming assembler language routine is running.

At any point in your code where you call another program, R12 must contain the common anchor area (CAA) address, except in the following cases:

When calling a COBOL program.
When calling an assembler language routine that is not Language Environment-conforming.
When calling a Language Environment-conforming assembler language routine that specifies NAB=NO on the CEEENTRY macro.

Register conventions for exit from conforming routines

On exit from a Language Environment-conforming assembler language routine, R0, R1, R14, and R15 are undefined. All the other registers must have the contents that they had upon entry.

The CEEENTRY macro automatically sets a module to AMODE (ANY) and RMODE (ANY). If you are converting an existing assembler language routine to be Language Environment-conforming and the routine contains data management macros coded using 24-bit addressing mode, you should change the macros to use 31-bit mode. If it is not possible to change all the modules in a program to use 31-bit addressing mode, and if none of the modules explicitly sets RMODE (24), you should set the program to be RMODE (24) during the link-edit process.

Non-conforming assembler language routines running under Language Environment

Observe the following conventions when running non-Language Environment-conforming assembler language routines under Language Environment:

R13 must contain the address of the executing routine's register save area.
The first two bytes of the register save area must be binary zeros.
The register save area back chain must be set to a valid 31-bit address (the high-order byte must be zero if it is a 24-bit address).

If your assembler language routine relies on C, C++, COBOL, or PL/I control blocks (for example, a routine that tests flags or switches in these control blocks), check that these control blocks have not changed under Language Environment. For more information, see the Compiler and Run-Time Migration Guide for the language in use.

Non-conforming assembler language routines cannot use Language Environment callable services.