Understanding TECH Help! Data Structures

  In TECH Help!, data structure layouts are described using easy-to-use
  conventions.  Structure and field names in DOS and BIOS data structures
  are arbitrary, so we have used some conventions that make them more
  meaningful.  The name of each field is started with a few letters which
  describe the size and type of the data it represents:

          b    = byte
          w    = word (16-bit, unsigned)
          l    = long (dword)
          r    = multi-byte record (structure or bit field)
          sz   = ASCIIZ▲ string

  To indicate that a field is a pointer (an address), the field name begins
  with a p.  To indicate a far pointer (a 32-bit segment:offset address),
  the field name begins with pf.  For instance,:

          p    = pointer
          pf   = far pointer (32-bit, segment:offset address)
          pfr  = far pointer to a structure
          pfsz = far pointer to an ASCIIZ string

  When an a is used as a leading qualifier, the field is an array, or list
  of identical elements.  For instance:

          ab   = multiple-element array of bytes
          aw   = array of 16-bit words

  Finally, the field name itself is given, starting with an uppercase
  letter.

█▌Sample Structure▐█
  Here's an example of a multiple-byte data area:

SampleDataRec
  Offset Size Contents
  ▀▀▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  +0       1  bFieldByte   an 8-bit (BYTE) field
  +1       2  wFieldWord   a 16-bit (WORD) field
  +3       4  lFieldDword  a 32-bit (DWORD) field
  +7       9  abTextField  a 9-byte array of bytes
 +10H      4  pfrNext      a 32-bit far pointer to a structure
 +14H     12  szTextField  a 12-byte field containing an ASCIIZ▲ string
          32               size of a SampleDataRec structure

 The offset and size are the most important; the field names are arbitrary.
 Offsets are given in hex▲, with an H suffixed where relevant.
 Sizes are given in decimal.

 As the last line, the total size of the structure is given in bytes.

 When deemed important, additional information about each field is
 described in the topic.  For instance,

  bFieldByte  a one byte field
  wFieldWord  a two-byte field.  As with all 16-bit values, the first byte
              is the low byte and the next is the high byte of the value.
 lFieldDword  a 4-byte field, used as a 32-bit (long) value
 abTextField  a multi-byte field.  Words such as "blank-padded" mean that
              any unused part of the field contains spaces.
     pfrNext  a 32-bit address of a structure.  As with all 32-bit
              addresses, the first two bytes are the offset and the next two
              bytes are the segment.
 szTextField  an ASCIIZ string.  The string is terminated with a NUL (00H)
              and bytes following that NUL are not used.

█▌Sample Bit Record▐█
  Here's an example of a one-byte record that contains bit-fields:

SampleBitRec
╓7┬6┬5┬4┬3┬2┬1┬0╖
║c│0 0│drv│0│d│v║
╙╥┴─┴─┴─┴─┴─┴╥┴╥╜  bit mask
 ║     ╚╦╝   ║ ╚═►  0:  01H perform verification
 ║      ║    ╚═══►  1:  02H "dirty" (has been modified)
 ║      ╚════════►3-4:  18H drive ID: 00=A, 01=B, 10=C, 11=D
 ╚═══════════════►  7:  80H calibration needed

   Notes: ■ Where a 0 appears in the diagram, that bit is reserved and has
            no (documented) meaning.

          ■ Other bits may contain a letter or short word in this color.
            That is simply a mnemonic to help you see at a glance what the
            bits mean.

          ■ The mask value is the digital value of that bit.  For instance,
            assuming the above record is in AL, your program could use...

              AND AL,80H
              CMP AL,80H
              JE  BitWasSet

            ...or perhaps...

              TEST AL,80H
              JNZ  BitWasSet

            ...to test the "calibration needed" bit (bit 7).  To set that
            bit, use...

              OR   AL,80H

See Also: (fns that use the structure are listed here)
          Using TECH Help!
          Data Structures
                                    -♦-