Previous Contents  

APPENDIX C: THE INCLUDE FILES

The programs in this book make extensive use of a library of standard code sections. These sections are inserted into the program source by the INCLUDE command developed in Chapter 6. This appendix contains the complete source text of these included code sections and documents them.

The Subroutines

The interface to each subroutine is documented in Table C-1. For example, the subroutine CmpBD takes an integer in the BC register, another in the DE register, and returns a setting of the machine flags. It preserves all the registers except for A and the flags.

The Include Files

The code sections are organized into six files. Each file has a filetype of ".INC" and a filename meant to suggest the kind of code sections it contains. Each file contains a number of named units. Each unit contains one or more subroutines. Table C-2 lists all the subroutines, showing for each the name of the file and the smallest section that contains it. Look up the subroutine name "CmpBD," for example. It is in the file ARITHLIB.INC, which is displayed in listing C-1. The CmpBD subroutine is contained in the unit of the same name. If the CmpBD subroutine is to be part of a program, the program must have a line containing the command "#include Arithlib.inc,CmpBD."

As noted in Chapter 6, the INCLUDE command allows named units to be nested within each other. The include files here are organized to take advantage of that fact. Often when the code in one unit calls upon code from another unit, the second unit is simply contained within the first one. This nesting of units is conceptually economical, but it makes it hard to document the relationship between units. After a number of experiments with tables more elaborate than Table C-1, I decided that the nesting of units could only be documented graphically.

Each of the six file listings in this appendix is preceded by a Figure that shows how the named units are nested within the file. For an example, turn to Listing C-3. It displays the code of the units in PUTSUBS.INC, and it is preceded by a Figure C-3 that shows relationships of those units graphically.

PUTSUBS contains six named units. Each one is shown in Figure C-3 as a rectangular outline. The name of a unit is shown outside its outline, at the upper left corner. The names of the subroutines contained in the unit are shown within the outline. The subroutine names end in colons. For instance, the PutCommon unit contains the code of three subroutines: PutBlank, PutCRLF, and PutString.

PutXX, one of the units in PUTSUBS, is nested inside another one (PutXXXX). If a program includes the PutXXXX unit, it will automatically include a copy of PutXX as well, because the smaller unit is part of the larger one.

The PutDecimal section doesn't contain another unit, but it does include another unit. This is indicated by a broad arrow followed by a file and unit name. Figure C-3 shows that within the code of PutDecimal there is a statement "#include Arithlib.inc,UnpackBCD." Within the code of PutXX there is an include for unit HexDisplay of file ARITHLIB. The Figure also shows that the Put9999 unit has two include commands—one for UnpackBCD from ARITHLIB, and one for PutXXXX from the PUTSUBS file.

As you can see from this discussion, the Figures contained in the listings of this appendix document a number of aspects of the files far more concisely than could be done by words or tables. With them you can answer such questions as "What is included with section so-and-so?" and "If unit X is included, does unit Y need to be included also?"