How to use the DS instruction

Use the DS instruction to:

To reserve storage

If you want to take advantage of automatic boundary alignment (if the ALIGN option is specified) and implicit length calculation, you should not supply a length modifier in your operand specifications. Instead, specify a type subfield that corresponds to the type of area you need for your instructions.

Using a length modifier can give you the advantage of explicitly specifying the length attribute value assigned to the label naming the area reserved. However, your areas are not aligned automatically according to their type. If you omit the nominal value in the operand, you should use a length modifier for the binary (B), character (C), graphic (G), hexadecimal (X), and decimal (P and Z) type areas; otherwise, their labels are given a length attribute value of 1 (2 for G and CU type).

When you need to reserve large areas, you can use a duplication factor. However, in this case, you can only refer to the first area by its label. You can also use the character (C) and hexadecimal (X) field types to specify large areas using the length modifier. Duplication has no effect on implicit length.

Although the nominal value is optional for a DS instruction, you can put it to good use by letting the assembler compute the length for areas of the B, C, G, X, and decimal (P or Z) type areas. You achieve this by specifying the general format of the nominal value that is placed in the area at execution time.

If a nominal value and no length modifier are specified for a Unicode character string, the length of the storage reserved is derived by multiplying by two the number of characters specified in the nominal value (after pairing).

To force alignment

Use the DS instruction to align the instruction or data that follows, on a specific boundary. You can align the location counter to a doubleword, a fullword, or a halfword boundary by using the correct constant type (for example, D, F, or H) and a duplication factor of zero. No space is reserved for such an instruction, yet the data that follows is aligned on the correct boundary. For example, the following statements set the location counter to the next doubleword boundary and reserve storage space for a 128-byte field (whose first byte is on a doubleword boundary).

         DS              0D
AREA     DS              CL128

Alignment is forced whether or not the ALIGN assembler option is set.

To name fields within an area

Using a duplication factor of zero in a DS instruction also provides a label for an area of storage without actually reserving the area. Use DS or DC instructions to reserve storage for, and assign labels to, fields within the area. These fields can then be addressed symbolically. (Another way of accomplishing this is described in DSECT instruction.) The whole area is addressable by its label. In addition, the symbolic label has the length attribute value of the whole area. Within the area, each field is addressable by its label.

For example, assume that 80-character records are to be read into an area for processing and that each record has the following format:

Positions 5-10
Payroll Number
Positions 11-30
Employee Name
Positions 31-36
Date
Positions 47-54
Gross Wages
Positions 55-62
Withholding Tax

The following example shows how DS instructions might be used to assign a name to the record area, then define the fields of the area and allocate storage for them. The first statement names the whole area by defining the symbol RDAREA; this statement gives RDAREA a length attribute of 80 bytes, but does not reserve any storage. Similarly, the fifth statement names a 6-byte area by defining the symbol DATE; the three subsequent statements actually define the fields of DATE and allocate storage for them. The second, ninth, and last statements are used for spacing purposes and, therefore, are not named.

RDAREA   DS         0CL80
         DS         CL4
PAYNO    DS         CL6
NAME     DS         CL20
DATE     DS         0CL6
DAY      DS         CL2
MONTH    DS         CL2
YEAR     DS         CL2
         DS         CL10
GROSS    DS         CL8
FEDTAX   DS         CL8
         DS         CL18

Additional examples of DS statements are shown below:

ONE      DS         CL80          One 80-byte field, length attribute of 80
TWO      DS         80C           80 1-byte fields, length attribute of 1
THREE    DS         6F            6 fullwords, length attribute of 4
FOUR     DS         D             1 doubleword, length attribute of 8
FIVE     DS         4H            4 halfwords, length attribute of 2
SIX      DS         GL80          One 80-byte field, length attribute of 80
SEVEN    DS         80G           80 2-byte fields, length attribute of 2

To define four 10-byte fields and one 100-byte field, the respective DS statements might be as follows:

FIELD    DS              4CL10
AREA     DS              CL100

Although FIELD might have been specified as one 40-byte field, the preceding definition has the advantage of providing FIELD with a length attribute of 10. This would be pertinent when using FIELD as an SS machine instruction operand.


[ Top of Page | Previous Page | Next Page | Contents | Index ]