z/OS Assembler programs, macros and calls

This page shows, with small examples, the program and macro objects that the extension creates and the links it creates for program calls and macro invocations. Each example lists the objects and links it produces.

Programs

A file whose content is a program (an END, CSECT, RSECT or START statement) produces a z/OS Assembler Program object, named after the file, whatever its extension.

LOADED.asm:

LOADED   CSECT
         BR    14
         END

Type	Name
	LOADED

Macros

A file whose content is a MACRO … MEND definition, with no program statement, produces a z/OS Assembler Macro object, named after the file.

MYMACRO.asmacro:

         MACRO
         MYMACRO &REG,&VALUE
         L     &REG,=F'&VALUE'
         MEND

Type	Name
	MYMACRO

Calls to an Assembler program of the same analysis

LOAD EP=

A LOAD EP=name statement is linked like a CALL. LOADER.asm loads LOADED.asm, an Assembler program of the same analysis, so the link goes directly to that program:

LOADER   CSECT
         STM   14,12,12(13)
         LR    12,15
         LOAD  EP=LOADED
         LR    15,0
         BALR  14,15
         LM    14,12,12(13)
         BR    14
         END

Caller type	Caller	Link	Callee type	Callee
	LOADER	call Link		LOADED

In CAST Imaging:

A LOAD EPLOC= statement names its program only at run time: it creates no link.

LINK, XCTL and ATTACH EP=

LINK, XCTL and ATTACH (and their LINKX, XCTLX and ATTACHX forms) pass control to the program named by their EP= operand. LINKED.asm, XCTLED.asm and ATTACHED.asm are Assembler programs of the same analysis:

LINKER   CSECT
         LINK  EP=LINKED,PARAM=(PARM1,PARM2),VL=1
         ATTACH EP=ATTACHED,ECB=TASKECB
         DELETE EP=LINKED
         XCTL  (2,12),EP=XCTLED
PARM1    DS    F
PARM2    DS    F
TASKECB  DS    F
         END   LINKER

Caller	Link	Callee
LINKER	call Link	ATTACHED
LINKER	call Link	LINKED
LINKER	call Link	XCTLED

In CAST Imaging:

DELETE EP= does not pass control to the program: it creates no link.

Operation codes in lower case

The operation codes are read in any case, as HLASM does. LOWCASE.asm calls LOWCALLD.asm, an Assembler program of the same analysis:

lowcase  csect
         call  lowcalld
         br    14
         end   lowcase

Caller type	Caller	Link	Callee type	Callee
	LOWCASE	call Link		LOWCALLD

In CAST Imaging:

Calls to a program of another language or analysis unit

A call to a program that is not an Assembler program of the same analysis goes to a z/OS Assembler Call to Generic Program object. Only one such object is created for each called name, and it is shared by all callers. CALLERA.asm and CALLERB.asm both call SHAREDPGM, which is not part of the analysis:

CALLERA.asm:

CALLERA  CSECT
         STM    14,12,12(13)
         LR     12,15
         CALL   SHAREDPGM
         L      13,4(13)
         LM     14,12,12(13)
         BR     14

CALLERB.asm:

CALLERB  CSECT
         STM    14,12,12(13)
         LR     12,15
         CALL   SHAREDPGM
         L      13,4(13)
         LM     14,12,12(13)
         BR     14

Caller type	Caller	Link	Callee type	Callee
	CALLERA	call Link		SHAREDPGM
	CALLERB	call Link		SHAREDPGM

In CAST Imaging:

The same applies to LOAD EP=, LINK EP=, XCTL EP= and ATTACH EP=. The LOADER.asm and LINKER.asm files shown above also hold these statements, where COBLOAD and COBLINK are not part of the analysis:

         LOAD  EP=COBLOAD,ERRET=NOTFOUND
         LINKX EP=COBLINK

Caller type	Caller	Link	Callee type	Callee
	LINKER	call Link		COBLINK
	LOADER	call Link		COBLOAD

In CAST Imaging:

For EXEC CICS LINK PROGRAM(...) and EXEC CICS XCTL PROGRAM(...), see EXEC CICS commands.

Macro invocations

A statement whose operation code is the name of a macro file of the same analysis is linked to that macro. PGM.asm invokes the macro MYMACRO shown above:

BALAPI   CSECT
         STM    14,12,12(13)
         LR     12,15
         MYMACRO R3,42

Caller type	Caller	Link	Callee type	Callee
	PGM	call Link		MYMACRO

In CAST Imaging:

The program object is named after its file (PGM.asm), not after its CSECT.

Calls from a macro

The calls, LOAD, LINK, XCTL, ATTACH and COPY statements of a macro file are linked from the macro. CALLMAC.asmacro calls MCALLED.asm, an Assembler program of the same analysis, loads MCOBPGM, which is not part of the analysis, and copies MCOPIED.asmacro, a macro file:

CALLMAC.asmacro:

         MACRO
&NAME    CALLMAC
&NAME    CALL  MCALLED
         LOAD  EP=MCOBPGM
         COPY  MCOPIED
         MEND

MCALLED.asm:

MCALLED  CSECT
         BR    14
         END   MCALLED

MCOPIED.asmacro:

         MACRO
&LABEL   MCOPIED
&LABEL   DS    0H
         MEND

Caller	Link	Callee
CALLMAC	call Link	MCALLED
CALLMAC	call Link	MCOPIED
CALLMAC	call Link	MCOBPGM

In CAST Imaging:

For a macro that copies a copy member, see COPY in a macro.

Cross-technology calls

Calls to COBOL, PL/I and other Assembler programs

These links are created by Universal Linker after all technologies have been analyzed. It links each z/OS Assembler Call to Generic Program object to the program of that name: a COBOL program analyzed by the Mainframe Analyzer, a PL/I main procedure analyzed by the PL/1 Analyzer, or an Assembler program of another analysis unit.

In the example of CALLERA.asm above, CALLERA calls SHAREDPGM:

CALLERA  CSECT
         CALL   SHAREDPGM

Depending on what SHAREDPGM is in the application, Universal Linker creates one of these links:

Caller	Link	Callee
SHAREDPGM	call Link	SHAREDPGM
SHAREDPGM	call Link	SHAREDPGM
SHAREDPGM	call Link	SHAREDPGM

In CAST Imaging:

When no program of that name is found, the z/OS Assembler Call to Generic Program object stays unresolved.

Calls from COBOL and PL/I programs to Assembler programs

The analyzer of a COBOL or PL/I program cannot resolve a call to an Assembler program. It links the calling program to an object for the unresolved program: a COBOL program prototype for the Mainframe Analyzer, a PLI Missing Program for the PL/1 Analyzer. Universal Linker then links that object to the Assembler program of that name.

ASMUTIL is an Assembler program of the analysis:

ASMUTIL  CSECT
         BR    14
         END   ASMUTIL

COBPGM1.cbl calls ASMUTIL with a CALL statement:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. COBPGM1.
      *    CALLS THE ASSEMBLER PROGRAM ASMUTIL
       PROCEDURE DIVISION.
           CALL 'ASMUTIL'.
           GOBACK.

PLIPGM1.pli calls ASMUTIL, declared as an Assembler entry:

 /* CALLS THE ASSEMBLER PROGRAM ASMUTIL */
 PLIPGM1: PROCEDURE OPTIONS(MAIN);
    DCL ASMUTIL ENTRY OPTIONS(ASM);
    CALL ASMUTIL;
 END PLIPGM1;

Caller type	Caller	Link	Callee type	Callee
	ASMUTIL	call Link		ASMUTIL
	ASMUTIL	call Link		ASMUTIL

In CAST Imaging:

A COBOL program that loads an Assembler program with EXEC CICS LOAD PROGRAM('ASMUTIL') is linked the same way, through a COBOL program prototype.