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.

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║
║     ╚╦╝   ║ ╚═►  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