HLASM Environment: JCL, ASMA90, and Your First Assembly Program

Writing and running an HLASM program on z/OS involves three steps: writing the assembler source, invoking the assembler (ASMA90) via JCL, and linking and running the resulting object module. This module walks through each step with a working example.

The HLASM Toolchain

Source (.asm)  →  ASMA90 Assembler  →  Object Deck  →  Linkage Editor  →  Load Module  →  Execute

• ASMA90 — the HLASM assembler program. It translates HLASM source into an object deck
• IEWL / IEWBLINK — the z/OS Linkage Editor. It resolves external references and builds a load module
• Load module — the executable stored in a partitioned dataset (PDS) ready to run

Your First HLASM Program

This program loads the value 42 into register 3 and returns to the caller:

FIRST    CSECT
         STM   14,12,12(13)       Save caller's registers
         LR    12,15              Set up base register
         USING FIRST,12           Tell assembler our base
         LA    3,42               Load 42 into register 3
         L     14,12(13)          Restore return address
         LM    0,12,20(13)        Restore registers 0-12
         BR    14                 Return to caller
         END   FIRST

Key points:

• CSECT — Control Section. Marks the start of the program
• STM 14,12,12(13) — Save registers 14 through 12 (wrapping around) into the caller's save area
• LR 12,15 — Copy register 15 (entry point address) to register 12 (our base register)
• USING FIRST,12 — Tells the assembler that register 12 holds the address of label FIRST
• LA 3,42 — Load Address: loads the immediate value 42 into register 3
• BR 14 — Branch to address in register 14 (return to caller)
• END FIRST — Marks the end of the source and specifies the entry point

JCL to Assemble and Link

//ASSEMBLE JOB (ACCT),'HLASM FIRST',CLASS=A,MSGCLASS=X
//*
//ASM     EXEC PGM=ASMA90,
//        PARM='OBJECT,NODECK,NOESD,NORLD,NOXREF'
//SYSLIB   DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=SYS1.MODGEN,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//SYSOBJECT DD DSN=&&OBJ,UNIT=SYSDA,SPACE=(CYL,(2,1)),
//             DISP=(NEW,PASS)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
FIRST    CSECT
         STM   14,12,12(13)
         LR    12,15
         USING FIRST,12
         LA    3,42
         L     14,12(13)
         LM    0,12,20(13)
         BR    14
         END   FIRST
/*
//*
//LINK    EXEC PGM=IEWL,
//        PARM='LIST,XREF,MAP'
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//SYSLMOD  DD DSN=MY.LOADLIB(FIRST),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSN=&&OBJ,DISP=(OLD,DELETE)
//*
//RUN     EXEC PGM=FIRST
//STEPLIB  DD DSN=MY.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*

Understanding the Assembly Listing

ASMA90 produces an assembly listing that shows:

• The source statement
• The machine code generated (in hexadecimal)
• The location counter offset

LOC  OBJECT CODE  ADDR1 ADDR2  STMT   SOURCE STATEMENT
000000 90ECD00C           00000C    2  STM   14,12,12(13)
000004 18CF                         3  LR    12,15
000006 18FF                         4  USING FIRST,12
000008 4130002A                     5  LA    3,42

The LOC column shows the offset from the start of the CSECT. OBJECT CODE is the hexadecimal machine instruction.

Common ASMA90 PARM Options

HLASM Source Dataset Conventions

On z/OS, HLASM source is typically stored in a PDS with:

• Record format: FB (Fixed Block)
• Logical record length: 80
• Block size: 3200 (or larger)

Columns 1–71 contain the HLASM statement. Column 72 is used for continuation. Columns 73–80 are the sequence number field (informational only).

Frequently Asked Questions

Q: What is the difference between ASMA90 and the older Assembler H? ASMA90 is IBM's current HLASM assembler product (product number 5696-234). Assembler H was its predecessor on System/370. ASMA90 adds structured programming macros (IF/ELSE/ENDIF, DO/ENDDO), improved diagnostics, Unicode support, and optimised code generation. All Assembler H source assembles correctly under ASMA90 — the migration is purely a JCL change.

Q: What does the USING directive do? USING label,register tells the assembler which register holds the address of a given label at runtime. The assembler uses this information to generate correct base-displacement addresses for all references to labels within range of that register. Without a USING, the assembler cannot generate addresses and will produce errors. Every HLASM program must establish at least one base register.

Q: What is a CSECT? CSECT (Control Section) marks the beginning of a relocatable section of code or data. A program can have multiple CSECTs — the linker places them consecutively in the load module. The first CSECT in a program is typically the main code section. The name on the CSECT becomes the entry point name used in JCL.

Part of HLASM Mastery Course — Module 2 of 22.