HLASM DSECT: Mapping Data Structures with Dummy Sections

A DSECT (Dummy Section) defines the layout of a data structure without allocating any storage. It is HLASM's equivalent of a C struct or a COBOL record description. DSECTs are used to map input records, work areas, parameter lists, and z/OS control blocks.

What Is a DSECT?

A CSECT allocates real storage that becomes part of the load module. A DSECT defines field names and offsets but generates no object code. The storage is allocated elsewhere (in a CSECT, obtained with GETMAIN, or passed by the caller).

hlasm

EMPRECRD DSECT
EREMPNO  DS    CL6              Employee number (6 bytes)
ERNAME   DS    CL25             Employee name (25 bytes)
ERDEPT   DS    CL4              Department code (4 bytes)
ERSALARY DS    PL5              Salary in packed decimal (5 bytes)
ERFLAGS  DS    X                Status flags (1 byte)
ERRECLEN EQU   *-EMPRECRD       Length of entire record = 41

No storage is allocated. EREMPNO, ERNAME, etc., are displacement constants from the start of the DSECT.

Using a DSECT

To use a DSECT, load the address of the actual data into a register and declare a USING:

hlasm

MAINPROG CSECT
         STM   14,12,12(13)
         LR    12,15
         USING MAINPROG,12
*
* Read a record into INAREA
         GET   INFILE,INAREA
*
* Map the DSECT over the input area
         LA    10,INAREA        Register 10 = address of input record
         USING EMPRECRD,10      Map DSECT fields via reg 10
*
* Now access fields by name
         CLC   EREMPNO,KEYVALUE     Compare employee number
         BE    FOUND
         CP    ERSALARY,=P'50000'   Compare salary
         BH    HIGHEARNER
*
         DROP  10                   Release the DSECT USING
*
INAREA   DS    CL41             Input area (same length as DSECT)
KEYVALUE DC    CL6'100001'

Mapping z/OS Control Blocks

IBM provides DSECT mappings for all z/OS control blocks via system macros:

hlasm

* Map the CVT (Communications Vector Table)
         L     3,16             Address of CVT is at absolute address 16
         USING CVT,3            Map CVT fields
         L     4,CVTJESCT       Load address of JES control table
         DROP  3
*
* CVTDSECT macro generates the CVT DSECT
         CVT   DSECT=YES        Include IBM-supplied CVT mapping

Common z/OS control block macros: CVT, TCB, RB, ASCB, PSATOLD, IHAPSA.

Nested DSECTs

DSECTs can reference other DSECTs for nested structures:

hlasm

* Order header record
ORDHDR   DSECT
OHDOCNO  DS    CL8              Order number
OHDATE   DS    CL8              Order date
OHCUST   DS    CL6              Customer number
OHNITEMS DS    H                Number of line items
OHFIRST  DS    0CL0             First line item (length 0 — just an offset)

* Order line item
ORDITEM  DSECT
OILINENO DS    H                Line number
OIPARTNO DS    CL10             Part number
OIQTY    DS    PL3              Quantity
OIPRICE  DS    PL5              Unit price
OIITMLEN EQU   *-ORDITEM        Item record length = 20

EQU — Equate

EQU assigns a name to a constant value. Commonly used for register names and flag values:

hlasm

* Register equates (industry standard)
R0       EQU   0
R1       EQU   1
R2       EQU   2
R3       EQU   3
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15

* Flag bit equates
FL_INIT  EQU   X'80'            Initialized flag
FL_OPEN  EQU   X'40'            File open flag
FL_EOF   EQU   X'20'            End of file flag

* Using register equates in code
         LR    R12,R15          More readable than: LR 12,15
         OI    FLAGS,FL_OPEN    Set open flag

DSECT for Parameter Passing

DSECTs are the standard way to define parameter lists:

hlasm

* Define the parameter list structure
MYPARMS  DSECT
PMFLAG   DS    X                Processing flags
         DS    3X               Reserved (alignment)
PMPTR1   DS    A                Address of first operand
PMPTR2   DS    A                Address of second operand
PMRSLT   DS    A                Address of result area
PMPARLEN EQU   *-MYPARMS        Parameter list length = 13

* In the calling program
         LA    1,PARMLIST       Register 1 = parameter list address
         CALL  MYSUBRTN
PARMLIST DS    0A
PARMFLAG DC    X'00',3X'00'
PMPTR1V  DC    A(OPERAND1)
PMPTR2V  DC    A(OPERAND2)
PMRSLTV  DC    A(RESULT)

Frequently Asked Questions

Q: What is the difference between a DSECT and an ORG redefinition? Both map field names over storage. ORG repositions the location counter within a CSECT, redefining the same storage with different names. DSECT creates a completely separate name space with no allocated storage. DSECTs are preferred because they are reusable (you can USING the same DSECT over multiple storage areas), clearly separate the structure definition from its usage, and can be defined in a copy library or macro.

Q: Can a DSECT have its own base register separate from the main program? Yes — this is the whole point. A DSECT's fields are resolved using a different base register than the main program. You typically use registers 2–10 for DSECTs and register 12 for the main program base. This lets you simultaneously access the main program's data (via reg 12) and a mapped record area (via, say, reg 10) without interference.

Q: How do I know the offset of a field within a DSECT? After assembly, the listing shows the offset of each DS/DC statement from the start of the DSECT. You can also use EQU *-DSECTNAME to define a named constant equal to the current offset. For IBM system control blocks, the offsets are documented in z/OS Data Areas reference manuals and are also embedded in the generated DSECT mappings (look for equates like CVTPTR EQU X'00').

Part of HLASM Mastery Course — Module 15 of 22.