## ALP Programming Guide and Reference

[prev][next][parent][TOC]

### RECORD (Define a Record Type Name)

A record is a bit pattern you define to format bytes, words, or dwords for bit-packing. The RecordName becomes a Record-TypeName that can be used create record variables.

Syntax

    RecordName   RECORD   FieldDeclaration   [ ,   [ LineBreak ]   FieldDeclaration   . . . ]

Where FieldDeclaration has the following form:

    FieldName : Width [   =   InitialValue ]

The optional LineBreak entry allows you to end a FieldDeclaration with a comma, enter an optional EndOfLine-Comment followed by a physical NewLine character, then continue the record definition on the next line.

Remarks

The RecordName and FieldName entries are unique globally-scoped Identifier s that must be specified. Upon successful processing of the RECORD definition, the RecordName entry is converted to a Record-TypeName, and all FieldNames are converted to Record-FieldName s.

Each Width entry in a FieldDeclaration is specified as an Expression which must evaluate to an Absolute-ExpressionType. The cumulative value of all Width entries becomes the total RecordWidth and must not exceed 32, the size of a DWORD, the maximum size for a Record-TypeName. The Operand Size of the record becomes 1 (BYTE) if the RecordWidth is from 1 through 8, 2 ( WORD) if the RecordWidth is from 9 through 16, and 4 (DWORD) if the RecordWidth is from 17 through 32. Any other value causes an error. If the total number of bits in the RecordWidth is not evenly divisible by the Operand Size, the assembler right-justifies the fields into the least- significant bit positions of the record.

When a Record-FieldName is referenced in an expression, the value returned is the shift value required to access the field. The WIDTH operator is used on the Record-FieldName to return the width of the field in bits, and the MASK operator is used to obtain the value necessary for isolating the field within the record.

The InitialValue entry contains the default value to used for the field when a record variable is allocated. If the field is at least 7 bits wide, you can initialize it to an ASCII character (for example, FIELD:7='Z').

To initialize a record, use the form:

    [ Identifier ]   Record - TypeName   Expression   [ ,   Expression   . . . ]

The Identifier entry is an optional name for the first byte, word, or dword of the reserved memory. The Record-TypeName defines the format and default field values, and is the RecordName you assigned to the record in the RECORD directive.

At least one Expression entry must be specified; additional entries are optional. The Expression must resolve to a Compound-ExpressionType, which may also be be duplicated by specifying it as a sub-expression of a Duplicated-ExpressionType. Each Compound-ExpressionType represents a single allocated record entry; each explicit sub-expression of the Compound -ExpressionType represents a field value which overrides the default InitialValue for the field given in the record definition.

Example

Define the record fields; begin with the most significant fields first:

    MODULE   RECORD   R : 7 ,       ;   First   field .    " ,   LineBreak "   syntax
                    E : 4 ,       ;   may   be   used   to   split   RECORD
                    D : 5        ;   definition   across   multiple   lines

Fields are 7 bits, 4 bits, and 5 bits; the assembler gives no default value . Most significant byte first, this looks like:

    RRRR   RRRE   EEED   DDDD

To reserve its memory:

    STG _ FLD     MODULE      < 7 , , 2 >     ;   Initializer   is   a   Compound - ExpressionType

This defines R=7 and D=2 and leaves E unknown; it produces 2 bytes, the least significant byte first:

    02   0E

Define the record fields:

    AREA     RECORD     FLA : 8 = ' A ' , FLB : 8 = ' B '

To reserve its memory:

    CHAR _ FLD     AREA   < , ' P ' >

This defines FLA='A' (the default) and changes FLB='P'.

To use a field in the record:

    DEFFIELD     RECORD     X : 3 , Y : 4 , Z : 9
                 .
                 .
                 .
    TABLE        DEFFIELD   10   DUP ( < 0 , 2 , 255 > )
                 .
                 .
                 .
                 MOV   DX , TABLE [ 2 ]
    ;   Move   data   from   record   to   register
    ;   other   than   segment   register
                 AND   DX , MASK   Y
    ;   Mask   out   fields   X   and   Y
    ;   to   remove   unwanted   fields
    ;   The   MASK   of   Y   equals   1E00H
    ;   00011111000000000B   ( 1E00H )   Is   the   value
                  MOV   CL , Y         ;   Get   shift   count
                                  ;     9   is   the   value
                  SHR   DX , CL        ;   Field   to   low - order
                                  ;     bits   of   register ,   DX   is   now
                                  ;     equal   to   the   value   of   field   Y
                  MOV   CL , WIDTH   Y   ;   Get   number   of   bits
                                  ;     in   field   -   4   is   the   value ,
                                  ;     the   WIDTH   of   Y   is   4