BUILD.DOC DISCLAIMER This document file was created by scanning the original document and then editing the scanned text. As much as possible, the original text format was restored. Some format changes were made to insure this document would print on current laser printers using 60 lines per page. The original spelling and grammar has been preserved. 1-Sep-1997 CHAPTER 9 BUILD BUILD is the system generation program for OS/8 that allows you to: o Create an OS/8 monitor system from cassettes or paper tapes. o Maintain and update device handlers in an existing OS/8 system. o Add device handlers supplied by DIGITAL to a new or existing system. o Add your own device handlers to a new or existing system. With BUILD, you use simple keyboard commands to manipulate the device handlers that make up the OS/8 peripheral configuration. BUILD allows you to quickly and easily insert devices not standard on the system. 9.1 OS/8 DEVICE HANDLERS Each OS/8 configuration has certain device handlers available within BUILD when the system is supplied by DIGITAL. The handlers supplied with BUILD depend on the distribution media of OS/8 software, i.e., DECtape (LINCtape), cassettes, or paper tape. These device handlers are detailed for specific distribution media in Tables 9-1, 9-2, and 9-3 (see Appendix (G) for more information). You must activate the device handlers included with BUILD before the OS/8 system can use them. The BUILD commands INSERT, REPLACE, and SYSTEM activate the device handlers. A maximum of 15 handlers, including the system device (SYS) and the default mass storage device (DSK), can be made active. Inactive devices, although included with BUILD, cannot be used on the system until they are made active by the INSERT command. Thus, several system handlers may be supplied with BUILD, but only one may be marked active. All other OS/8-supported device handlers are supplied with every configuration. But if they are not included in the original BUILD, you must load them into BUILD before you can use them. The BUILD command LOAD accomplishes this. See Table 9-4 for a complete list of the device handlers available with OS/8. Two names identify handlers in BUILD. The first is the group name, assigned to an entire group of handlers of the same type. For example, the nonsystem TC08 DECtape handler supplied with a DECtape 9-1 BUILD system, which has four separate internal handlers, has the group name TC. The second name is the permanent device name. This is the name by which OS/8 identifies the physical device. For example, TC08 DECtape unit 3 has the group name TC and the permanent name DTA3. When OS/8 software is supplied on DECtape or LINCtape, BUILD includes the device handlers shown in Table 9-1. Table 9-1 Standard DECtape System Device Handlers ---------------------------------------------------------------------- | | Group | Permanent | | Handler | Name | Name(s) | |--------------------------------------------------------------------| | | | | | TC08 DECtape system handler | TC08 | SYS | | | | | | TC08 nonsystem DECtape | TC | DTA0-DTA3 | | drives 0-3 | | | | | | | | 12K TD8E DECtape system | TD8E | SYS, DTA0, DTA1 | | handler and drives 0 and 1 | | | | | | | | 8K ROM TD8E DECtape system | ROM | SYS, DTA0, DTA1 | | handler and drives 0 and 1 | | | | | | | | TD8E nonsystem DECtape | TD8A | DTA0, DTA1 | | drives 0 and 1 | | | | | | | | TD8E nonsystem DECtape | TD8B | DTA2, DTA3 | | drives 2 and 3 | | | | | | | | RK8E disk system handler | RK8E | SYS, RKB0 | | | | | | RK8E disk nonsystem handler | RK05 | RKA0, RKA1, | | | | RKB0, RKB1 | | | | | | RK8 disk system handler | RK8 | SYS, RKA1 | | | | | | RK8 disk nonsystem handler | RK01 | RKA0, RKA1 | | | | | | LINCtape system handler | LINC | SYS | | | | | | LINCtape nonsystem handler | LNC | LTA0-LTA3 | | | | | | RF08 disk system handler | RF08 | SYS | | | | | | Console terminal (2-page handler) | KL8E | TTY | ---------------------------------------------------------------------- (continued on next page) 9-2 BUILD Table 9-1 Standard DECtape System Device Handlers ---------------------------------------------------------------------- | | Group | Permanent | | Handler | Name | Name(s) | |--------------------------------------------------------------------| | | | | | High-speed I/O simulated on | KS33 | PTR, PTP | | ASR-33 Teletype | | | | | | | | High-speed reader/punch | PT8E | PTR, PTP | | | | | | LP08, LS8E, LV8E line printers | LPSV | LPT | | | | | | TA8E cassette drives 0 and 1 | TA8A | CSA0, CSA1 | | | | | | PDP-12 scope | VR12 | TV | ---------------------------------------------------------------------- The handlers supplied with a DECtape or LINCtape system are on the System Tape #2 (AL-4712C-BA). To include extra handlers in BUILD, mount this tape and use the LOAD command. 9.1.1 Cassette Systems When OS/8 software is supplied on cassettes, the device handlers shown in Table 9-2 are included in BUILD. Table 9-2 Standard Cassette System Device Handlers ---------------------------------------------------------------------- | | Group | Permanent | | Handler | Name | Name(s) | |--------------------------------------------------------------------| | | | | | RK8E disk system handler | RK8E | SYS, RKB0 | | | | | | RK8 disk system handler | RK8 | SYS, RKA1 | | | | | | RF08 disk system handler | RF08 | SYS | | | | | | DF32 disk system handler | DF32 | SYS | | | | | | Console terminal (2-page handler) | KL8E | TTY | | | | | | High-speed I/O simulated | KS33 | PTR, PTP | | on ASR-33 Teletype | | | ---------------------------------------------------------------------- (continued on next page) 9-3 BUILD Table 9-2 (Cont.) Standard Cassette System Device Handlers ---------------------------------------------------------------------- | | Group | Permanent | | Handler | Name | Name(s) | |--------------------------------------------------------------------| | | | | | High-speed reader/punch | PT8E | PTR, PTP | | | | | | TA8E cassette drives 0 and 1 | TA8A | CSA0, CSA1 | | | | | | LP08, LS8E, LV8E line printers | LPSV | LPT | ---------------------------------------------------------------------- These handlers are present on the system cassette AR-4588C-BA. To include extra handlers in BUILD, build an OS/8 system, use MCPIP to move specific device handlers onto the system device, then use the BUILD command LOAD. MCPIP is discussed in detail in Chapter 18. 9.1.2 Paper Tape Systems When OS/8 software is supplied on paper tape, the device handlers shown in Table 9-3 are included in BUILD. Table 9-3 Standard Paper Tape System Device Handlers ---------------------------------------------------------------------- | | Group | Permanent | | Handler | Name | Name(s) | |--------------------------------------------------------------------| | | | | | RK8E disk system handler | RK8E | SYS, RKB0 | | | | | | RK8 disk system handler | RK8 | SYS, RKA1 | | | | | | RF08 disk system handler | RF08 | SYS | | | | | | DF32 disk system handler | DF32 | SYS | | | | | | Console terminal (2-page handler) | KL8E | TTY | | | | | | High-speed I/O simulated | KS33 | PTR, PTP | | on ASR-33 Teletype | | | | | | | | High-speed reader/punch | PT8E | PTR, PTP | | | | | | TA8E cassette drives 0 and 1 | TA8A | CSA0, CSA1 | | | | | | LP08, LS8E, LV8E line printers | LPSV | LPT | ---------------------------------------------------------------------- 9-4 BUILD Two binary paper tapes provide other OS/8 handlers not included in BUILD: AK-4660C-BA contains the file-structured handlers; AK-4671C-BA contains character-oriented handlers. These tapes contain handlers that you can load into core using the BUILD command LOAD. The BUILD device handler tapes are composed of separate segments, with a short length of leader/trailer code between them. (All of these handlers are in the special format described in BUILD Device Handler Format in this section.) Table 9-4 contains a list of the handlers that are included on the tapes. The handlers are listed in the order in which they appear on the tapes. The TC08 handler is the first segment on handler tape #1, and the KL8E terminal handler is the first segment on handler tape #2. The segments should be either labeled or separated for easier use. To utilize a binary handler file, place the desired segment into the paper tape reader. Use the BUILD command LOAD to load that segment as follows: $LOAD PTR[:] Type a colon (:) after the device name if you _ ^ loaded BUILD from an OS/8 system device. The ^ $ allows time to place the tape in the reader. Type any keyboard character to load the tape. When the $ reappears, the handler has been loaded into BUILD's table. Type the BUILD command PRINT to verify that the handler has been loaded. Table 9-4 OS/8 Device Handlers ---------------------------------------------------------------------- | | | | File Name | | | | | on DECtape, | | | Group| Permanent | LINCtape, or| | Handler | Name | Name(s) | Cassette | |--------------------------------------------------------------------| | | | | | | TC08 DECtape system handler | TC08 | SYS, DTA0 | TC08SY.BN | | | | | | | 12K TD8E DECtape system | TD8E | SYS, DTA0, DTA1 | TD8ESY.BN | | handler | | | | | | | | | | 8K ROM TD8E DECtape | ROM | SYS, DTA0, DTA1 | ROMMSY.BN | | system handler | | | | | | | | | | LINCtape system handler | LINC | SYS, LTA0 | LINCSY.BN | | | | | | | RK8E disk system handler | RK8E | SYS, RKA0, RKB0 | RK8ESY.BN | | | | | | | RK8 disk system handler | RK8 | SYS, RKA0, RKA1 | RK08SY.BN | ---------------------------------------------------------------------- (continued on next page) 9-5 BUILD Table 9-4 (Cont.) OS/8 Device Handlers ---------------------------------------------------------------------- | | | | File Name | | | | | on DECtape, | | | Group| Permanent | LINCtape, or| | Handler | Name | Name(s) | Cassette | |--------------------------------------------------------------------| | | | | | | RF08 disk system handler | RF08 | SYS | RF08SY.BN | | | | | | | DF32 disk system handler | DF32 | SYS | DF32SY.BN | | | | | | | TD8E DECtape drives 0 and 1 | TD8A | DTA0, DTA1 | TD8EA.BN | | | | | | | TD8E DECtape drives 2 and 3 | TD8B | DTA2, DTA3 | TD8EB.BN | | | | | | | TD8E DECtape drives 4 and 5 | TD8C | DTA4, DTA5 | TD8EC.BN | | | | | | | TD8E DECtape drives 6 and 7 | TD8D | DTA6, DTA7 | TD8ED.BN | | | | | | | TC08 DECtape drives 0-7 | TC | DTA0-DTA7 | TC08NS.BN | | | | | | | LINCtape drives 0-7 | LNC | LTA0-LTA7 | LINCNS.BN | | | | | | | RK8E disk nonsystem handler | RK05 | RKA0-3, RKB0-3 | RK8ENS.BN | | | | | | | RK8 disk nonsystem handler | RK01 | RKA0-RKA3 | RK08NS.BN | | | | | | | RF08 disk nonsystem handler | RF | RF, NULL | RF08NS.BN | | | | | | | DF32 disk nonsystem handler | DF | DF | DF32NS.BN | | | | | | | RX01SY disk system handler | RX8E | SYS | RX01SY.BN | | | | | | | RX01NS disk nonsystem | RX01 | RXA0, RXA1 | RX01NS.BN | | handler | | | | | | | | | | VT50 VT-50 input handler | VT | LST | VT50.BN | | | | | | | LQP line printer handler | LQP | LPT | LQP.BN | | | | | | | Octal block DUMP handler | DUMP | DUMP | DUMP.BN | | | | | | | RX78B disk nonsystem | RX01 | RXA2, RXA3 | RX78B.BN | | handler (for VT-78 only) | | | | | | | | | | Console terminal (2-page | KL8E | TTY | KL8E.BN | | handler) | | | | ---------------------------------------------------------------------- (continued on next page) 9-6 BUILD Table 9-4 (Cont.) OS/8 Device Handlers ---------------------------------------------------------------------- | | | | File Name | | | | | on DECtape, | | | Group| Permanent | LINCtape, or| | Handler | Name | Name(s) | Cassette | |--------------------------------------------------------------------| | | | | | | Console terminal (1-page | AS33 | TTY | ASR33.BN | | handler) | | | | | | | | | | High-speed I/O simulated on | KS33 | PTR, PTP | LSPT.BN | | ASR-33 Teletype | | | | | | | | | | High-speed reader/punch | PT8E | PTR, PTP | PT8E.BN | | | | | | | LP08, LS8E, LV8E line | LPSV | LPT | LPSV.BN | | printers | | | | | | | | | | Anelex 645 line printer | L645 | LPT | L645.BN | | | | | | | Card reader | CR8E | CDR | CR8E.BN | | | | | | | BATCH handler | BAT | BAT | BAT.BN | | | | | | | PDP-12 scope | VR12 | TV | VR12.BN | | | | | | | TU10 magnetic tape drives | TM8E | MTA0-MTA7 | TM8E.BN | | 0-7 | | | | | | | | | | TA8E cassette drives 0 and 1| TA8A | CSA0, CSA1 | CSA.BN | | | | | | | TA8E cassette drives 2 and 3| TA8B | CSA2, CSA3 | CSB.BN | | | | | | | TA8E cassette drives 4 and 5| TA8C | CSA4, CSA5 | CSC.BN | | | | | | | TA8E cassette drives 6 and 7| TA8D | CSA6, CSA7 | CSD.BN | ---------------------------------------------------------------------- 9.2 CALLING AND USING BUILD BUILD is distributed as both a binary paper tape or cassette and as a core image file (BUILD.SV) on the system DECtape or LINCtape. You should load and save the binary BUILD file on the system device when you build the initial system (see OS/8 System Generation Notes). To ____________________________ use the BUILD.SV file on the system device, type the following command in response to the dot the OS/8 Keyboard Monitor prints: .RUN SYS BUILD _ 9-7 BUILD NOTE It is important that you specify the RUN command, rather than the R command, when loading BUILD into core. This will allow the use of the SAV command without specifying SAVE arguments. BUILD responds by printing a $, signaling that it is ready to accept commands. BUILD uses a keyboard monitor similar to the one contained in the OS/8 system. Text is input from the terminal and interpreted by BUILD. Table 9-5 lists the special characters that are available for editing. Table 9-5 BUILD Editing Characters ---------------------------------------------------------------------- | Character | Function | |--------------------|-----------------------------------------------| | | | | ALT MODE key | Terminate command; begin command | | | execution. No carriage return/line feed is | | | generated. | | | | | CARRIAGE RETURN | Terminate command; begin command | | | execution. Also generate carriage | | | return/line feed combination. | | | | | CTRL/C | Terminate command; return immediately to | | | the OS/8 Keyboard Monitor. | | | | | CTRL/O | Terminate printing; return control to | | | BUILD. | | | | | CTRL/U | Ignore line; the line may be typed again. | | | | | LINE FEED key | Examine contents of the command line. | | | | | RUBOUT key | Delete the last typed character from the | | | command. | ---------------------------------------------------------------------- The standard characters permitted in a BUILD command line are: A-Z, 0-9, SPACE, PERIOD, =, COMMA, COLON, HYPHEN Typing any other character causes the error message: SYNTAX ERROR ____________ 9-8 BUILD 9.3 BUILD COMMANDS The commands available in BUILD are: ALTER INSERT BOOT LOAD BUILD NAME CORE PRINT CTL QLIST DCB REPLACE DELETE SYSTEM DSK UNLOAD EXAMINE VERSION The general format of the command string is: $command args where command represents a legal command from the list and args represents a file name, device, group name, or other argument associated with the command. You can type the command in full or abbreviate it to the first two characters. For example: $PRINT and $PR are the same. If you attempt to issue an illegal command, BUILD replies by printing the illegal command preceded by a ?. Thus the illegal command ERASE would appear: $ERASE _ ?ERASE ______ $ _ 9.3.1 The Hyphen Construction Certain BUILD commands (DELETE, INSERT, REPLACE) allow the use of the hyphen construction to specify more than one permanent name. These permanent names must be four characters long and must differ only in the last character. You can insert permanent names that meet this restriction with the hyphen construction, so long as the last characters form a sequence of consecutive ASCII characters. For example, if you wish to delete DECtape handlers DTA0, DTA1, DTA2, and DTA3, type: $DELETE DTA0,DTA1.DTA2,DTA3 _ 9-9 BUILD or you can use the hyphen construction and type: $DELETE DTA0-3 _ 9.3.2 PRINT Syntax: $PRINT or $PR Function: Prints detailed list of the BUILD devices tables. The following example shows five handlers. RF08: SYS ____________ RK8E: *SYS *RKB0 ___________________ KL8E: *TTY ____________ PT8E: PTR *PTP ___________________ LPSV: LPT ____________ Group names are printed first in each line, followed by a colon. Following the group name is the list of permanent names available with each group. If one of the permanent names in a group is SYS, then this handler can be a system handler. An OS/8 system must have just one system handler. Some system handlers have other coresident handlers. Any handler that is active is marked with an asterisk to the left of its permanent name (RKB0, TTY, PTP in the printout), and the devices will be included in the new OS/8 system (i.e., these handlers were inserted with the INSERT, SYS, or REPLACE commands. Other commands are available for removing, loading, and deactivating handlers). The preceding printout indicates that RK8E is the system device. The handler RK8E:RKB0 is also marked as being active. After printing the list of available handlers, the PRINT command might also print some additional information. If, for example, you specified RK8E:RKB0 with the DSK command, the following is printed: DSK=RK8E:RKB0 _____________ If you specified the core command to restrict the core to 12K, the message: CORE=2 ______ is printed, indicating that field 2 is to be the highest core field available to the OS/8 system. 9-10 BUILD 9.3.3 QLIST Syntax: $QLIST or $QL Function: List the active permanent names on the system. No * is printed and the system device is the only group name printed. For example: $QLIST _ PTR DTA3 RK08:SYS LPT DTA4 9.3.4 LOAD Syntax: $LOAD activename or $LOAD dev:filename Function: Use LOAD to load a new device handler into BUILD. This handler can be one supplied by DIGITAL or one you have written. See the OS/8 ____ Software Support Manual (DEC-S8-OSSMB-A-D) for instructions on writing _______________________ device handlers. This handler is input into BUILD as a binary file or image. If you are running BUILD stand-alone, e.g., to create an initial OS/8 system, the LOAD command has the form: $LOAD activename where activename is the permanent name of an input device handler that the INSERT, REPLACE, or SYSTEM command has made active. It must be a handler for a non-file structured device. For example, to load a new handler from a binary paper tape with the PTR handler already in BUILD, type: $LOAD PTR _ If you are running BUILD under control of OS/8, the LOAD command has the form: $LOAD dev:filename where dev is an input device handler that exists in the current OS/8 system. (These are not the same as the handlers that BUILD marks active.) If no dev: is specified, DSK: is assumed. If dev: is non-file structured (i.e., paper tape), you may omit the filename. The filename has the form: 9-11 BUILD name.extension Filename is the binary file of the new handler to be loaded. The default extension is .BN. If you use no extension, you may omit the dot (.). Example: $LOAD DTA3:HANDLR.03 Load a file named HANDLR, with an _ extension of 03, from DTA3. You may specify several files that you are loading on one line. Separate the files by commas. You must specify a device for each file, or DSK will be assumed. If multiple files are specified, each file must contain a separate handler to be loaded. For example: $LOAD DTA3:FILE1,DTA5:FILE2 _ Once you have successfully issued the LOAD command, the new device handlers become available for further manipulation. The new handlers will appear in the PRINT output, but will not be marked as active. 9.3.5 INSERT Syntax: $INSERT gname,pname Function: After a LOAD command has made a handler or group of handlers available for insertion into the OS/8 system, use the INSERT command to make particular entry points active. The INSERT command uses two arguments; gname and pname. Gname is the group name of the handler, for example, the gname for TC08 DECtape is TC. Pname is the permanent name by which the device is currently known to BUILD. See Table 9-4 for a complete list of permanent device names. TC08 DECtape thus has the group name TC and the permanent names DTA0-DTA7. Examples: $IN KL8E,TTY _ $IN TC08,SYS _ If you specified no permanent name (and no :), the first name in the device group is assumed. For example: $INSERT TC _ would assign DTA0 as the permanent name. You can insert several handlers in the same group into the same 9-12 BUILD command by separating the permanent names with commas. For example: $IN TC,DTA0,DTA3,DTA7 _ If several permanent names (each four characters long) differ only in the last character, you can insert them simultaneously with the hyphen construction so long as the last characters form a sequence of consecutive ASCII characters. Example: $INSERT TC,DTA2-5 _ is the same as $INSERT TC,DTA2,DTA3,DTA4,DTA5 _ and $INSERT RK01,RKA0-2 _ is the same as $INSERT RK01,RKA0,RKA1,RKA2 _ If the permanent name specified is not part of the group name specified, or if the group name does not exist, the following message is printed: name NOT FOUND ______________ If disk is the device you are inserting, you can follow the group name with a construction of the form: pname=n Where n is a digit in the range 1 to 7 and represents the number of platters available. Use this option for the RF08 and DF32 disks. For example: $IN RF,RF=2 _ If you specify no such option, =1 is assumed. If n is too large for the device specified, the following message is printed: ?PLAT _____ 9.3.6 DELETE Syntax: $DELETE aname 9-13 BUILD Function: DELETE takes a device that is currently marked as active and makes it inactive. (Active devices are marked with an * in the PRINT command output and are printed by the QLIST command.) The argument for DELETE is the permanent name of the device. You can obtain the current permanent name from the PRINT or QLIST output. The major function of DELETE is to make device slots available to BUILD. For example, assume that the QLIST command output is: DTA0 DTA1 RK8E:SYS RKB0 TTY LPT CSA0 CSA1 CSA2 CSA3 ___________________________________________________ If the following command is issued to BUILD: $DELETE CSA0,CSA1,CSA2,CSA3 _ CSA0, CSA1, CSA2, and CSA3 will no longer be permanent devices, and the slots used by the TA8A and TA8B device groups will be made available to BUILD. The QLIST output after the above command will be: DTA0 DTA1 RK8E:SYS RKB0 TTY LPT _______________________________ Note, as previously explained, that you can use the hyphen construction in DELETE to remove a sequence of devices. Therefore, you can type the command to make the cassette handlers inactive as follows: $DELETE CSA0-3 _ 9.3.7 REPLACE Syntax: $REPLACE pname=gname, pname1 Function: REPLACE combines the functions of DELETE and INSERT to delete one device and activate another in a single step. The arguments for REPLACE are: pname The permanent name of the device to be deleted. (Same as the argument of the DELETE command.) gname, pname1 The group name and permanent name of the particular device to be inserted into the system (see INSERT for more details). Example: 9-14 BUILD Assume the PRINT output is: PT8E: *PTP *PTR ___________________ CR8E: *CDR ____________ RK05: RKA0 RKB0 RKA1 RKB1 __________________________________ Use REPLACE to delete the card reader (CDR) and to insert the RK05 group handler for RKA0: $REPLACE CDR=RK05,RKA0 _ The output of PRINT after this REPLACE is: PT8E: *PTP *PTR ___________________ CR8E: CDR ____________ RK05: *RKA0 RKB0 RKA1 RKB1 __________________________________ Use the hyphen construction with REPLACE to delete and insert more than one device handler. For example, assume you are replacing the LINCtape handlers LTA0, LTA1, LTA2, and LTA5 with DECtape handlers DTA0, DTA1, DTA2, and DTA5. The following command accomplishes this: $REPLACE LTA0-2,LTA5=TC,DTA0-2,DTA5 _ 9.3.8 UNLOAD Syntax: $UNLOAD gname, or $UNLOAD gname, pname Function: Use UNLOAD to delete a handler group (gname) or a permanent name (pname) from the BUILD system. (This differs from DELETE, which does not physically eliminate a device.) Use UNLOAD primarily when the NO ROOM error occurs during a LOAD command. For example, assume you are removing the entire group of LINCtape handlers. Type the command: $UNLOAD LNC _ This command unloads the LINCtape handler LNC and all permanent names (LTA0, LTA1, LTA2, LTA3, etc.) associated with it. To remove a particular permanent name from BUILD, e.g., DTA3, type: $UNLOAD TC:DTA3 _ This command unloads only the entry point name. To remove several permanent names, but not the entire group, use the 9-15 BUILD UNLOAD command, with commas separating the permanent names. For example: $UNLOAD TC:DTA0, DTA2 _ You cannot use the hyphen construction with the UNLOAD command. 9.3.9 NAME Syntax: $NAME pname=pname1 Function: The NAME command allows you to alter the device name that will be used by OS/8. The first argument, pname, must be the current name of a device marked active in the PRINT output. Pname1 is the name you wish to call this device. You may use only 4-character device names in the NAME command. If you enter longer names, all characters beyond the first four are ignored. After you use the NAME command, pname1 becomes the current permanent name; pname is unknown to BUILD. Example: Assume that the PRINT output is: TC : *DTA0 *DTA1 DTA2 DTA3 __________________________________ RK8E: *SYS *RKB0 ____________________ KL8E: *TTY ____________ PT8E: *PTP *PTR ___________________ To change the paper tape reader so that it is recognized by the permanent name READ, use the following command: $NAME PTR=READ _ The output from PRINT would then be: TC : *DTA0 *DTA1 DTA2 DTA3 __________________________________ RK8E: *SYS *RKB0 ____________________ KL8E: *TTY ____________ PT8E: *PIP *READ ____________________ If the permanent name specified as pname is not a currently active device, the message: pname NOT FOUND _______________ is printed. If his message appears, check the PRINT output to determine the correct permanent name. 9-16 BUILD 9.3.10 ALTER Syntax: $ALTER gname, loc=newvalue Function: The ALTER command allows you to change locations in device handlers. The arguments are: gname Group name of the handler. loc Alter relative octal location. If the handler is a 1-page handler, loc must be an octal number in the range 0-0177. If it is a 2-page handler, loc must be an octal number in the range 0-0377. newvalue An octal number specifying the new contents of the location specified by loc. If you do not enter =newvalue, BUILD prints the old value of loc followed by a slash. You can then enter newvalue or type a carriage return to retain the old value. 9.3.11 EXAMINE Syntax: $EXAMINE gname, loc Function: EXAMINE allows you to examine, but not modify, a location within a device handler. See the ALTER command. 9.3.12 DSK Syntax: $DSK=gname,pname or $DSK=aname Function: Use the DSK command to specify which device you are designating as DSK, the default storage device for OS/8. If you use the first form of the command, i.e., $DSK=gname,pname 9-17 BUILD the gname is the group name of the device, and pname is the permanent name. For example: $DSK=TC08:DTA0 _ assigns DTA0 as the device called DSK. When you issue the DSK command, you need not enter the permanent name. However, you must enter the permanent name via an INSERT, REPLACE, or SYSTEM command before you issue the BOOT command. If you are the second form of the command, i.e., $DSK=aname aname must be a permanent name BUILD marks as active. For example, the following command specifies the already active device RKA0 as the default device DSK: $DSK=RKA0 _ If you enter no DSK command, or if you issue the command without an argument, i.e., $DSK= _ or $DSK _ BUILD specifies SYS as DSK when you issue a BOOT command. 9.3.13 CORE Syntax: $CORE n Function: You use the CORE command to specify the highest core field available to the OS/8 system being built. The n is an octal number in the range 0 to 7. If n is 0 or omitted, or if you do not use the CORE command, the built system will use all of the available core. If n specifies more core than is available, the following message is printed: ?CORE _____ The value of n for the available core sizes is as follows: 9-18 BUILD Value of n Core __________ ____ 0 all available core 1 8K 2 12K 3 16K 4 20K 5 24K 6 28K 7 32K For example, a system that is to use only 24K of a 32K system requires the following CORE command: $CORE 5 _ 9.3.14 DCB Syntax: $DCB aname or $DCB aname=newvalue Function: The DCB command allows you to examine or modify the DCB word associated with a permanent name (see Section 9.5 for information on DCB words). The DCB word is the first word that appears after the permanent name in a description (from the handler header information words). Aname must be the permanent name of a device currently marked as active in the PRINT output. Example: $DCB DTA4=6160 _ changes the DCB of DTA4 so that this handler becomes a read-only device. You could also type this command as: $DCB DTA4 _ 4160/6160 _____ 9.3.15 CTL Syntax: $CTL aname=loc Function: 9-19 BUILD The CTL command allows you to modify the control word that appears after the DCB word in the handler header block. For example: $CTL LTA3=24 _ changes the entry point of the LTA3 handler to relative location 24. 9.3.16 VERSION Syntax: $VERSION or $VE Function: The VERSION command prints BUILD's version number on the terminal. 9.3.17 SIZE Syntax: $SIZE aname or $SIZE aname=new value aname must be the permanent name of a device currently marked as active. Example: $SIZE= RF08=1777 _ changes the length of the RF08 handler to 1777. Function: The SIZE command modifies word ten of a handler header block. Word ten specifies the size, in blocks, of a single platter on a system device. 9.3.18 SYSTEM Syntax: $SYSTEM sname=n Function: The SYSTEM command specifies devices that are system handlers or that are coresident with system handlers. The number n reflects the number 9-20 BUILD of platters included in the system device (valid only for multiple platter RF08 and DF32 disks). (Table 9-7 lists the available system handlers and their associated values for n.) The argument sname must be one of the legal device system names. If it is not, BUILD prints: ?SYS ____ thereby requesting a new system specification. Action is not taken on the SYSTEM command until you give the BOOTSTRAP command, so you may respecify a device with SYS. The system device used is the last one issued prior to the BOOT command. Specifying a new system device is not always necessary. For example, if you wish to insert new peripheral handlers, then this command is not needed. If you do not issue it, the OS/8 resident system is not affected beyond having altered device tables. BUILD includes the SYSTEM command only so it will be compatible with older versions of BUILD. You can specify the system device with the INSERT command. For example, the command: $SYS RF08=2 _ is the same as the command: $INSERT RF08,SYS=2 _ If the device specified in the SYS command is not the current system device, you will have an opportunity to have a zero directory placed on your new system device. If the system device is the same as the current system device, no new directory will result. 9.3.19 BUILD Syntax: $BUILD or $BU Function: You use the BUILD command only when building an initial OS/8 system from cassettes or paper tape. When you type the BUILD command, BUILD prints: LOAD OS/8: _________ to which you must respond by typing the device that contains the new OS/8 monitor, e.g., LOAD OS/8: CSA0 __________ 9-21 BUILD BUILD then loads and writes the various parts of OS/8 onto the system device. After writing OS/8, BUILD prints: LOAD CD: ________ to which you respond with the appropriate device, or with a carriage return to specify that the device is the same as the one specified in the LOAD OS/8: message. BUILD loads the Command Decoder and writes it onto the system device. Do not use the BUILD command at any time other than while building an initial OS/8 system. When you type this command, OS/8 assumes that you are building a new OS/8 system. It automatically zeroes the system device directory. Refer to the OS/8 System Generation Notes ____________________________ for instructions on building an initial system. 9.3.20 BOOTSTRAP Syntax: $BOOTSTRAP or $BO Function: BOOTSTRAP is the command that finally implements all the changes that you made with BUILD. BOOT rewrites all relevant Monitor tables and device handlers to reflect the updated system status. The devices BUILD had marked active now become device handlers in the system. Before you type a BOOTSTRAP command, you must specify the system device with either the SYSTEM or INSERT command. If no SYS is specified, the message: SYS NOT FOUND _____________ is printed. If the system device specified is different from the current system device, BUILD copies the system from the current system device to the new system device. After the copy is complete, BUILD asks: WRITE ZERO DIRECT? __________________ to determine whether a new (zero) directory is to be written on the new system device. If the reply is YES, the system will place a zero directory on the device. Any other reply causes the system to retain the old directory. 9-22 BUILD NOTE Exercise care if you want the old directory retained. The directory must be one of an OS/8 system device. After you answer this question, BUILD updates the system and prints: SYS BUILT _________ . _ Control returns to the Keyboard Monitor. When the BOOTSTRAP command has performed its functions and the Keyboard Monitor is once again active, save the copy of BUILD just used. This way, an image of the current system status is preserved, and you can use the saved copy of BUILD again. When it is used again, the devices initially marked active remain marked active. To save BUILD, type: .SAVE SYS BUILD _ in response to the dot printed by the Keyboard Monitor. This assumes that you originally loaded BUILD into core with a RU or RUN command. 9.4 BUILD ERROR MESSAGES The following is a list of error messages that may appear when using BUILD. These messages usually indicate a syntax or user error. Table 9-6 BUILD Error Messages ---------------------------------------------------------------------- | Message | Explanation | |--------------------|-----------------------------------------------| | | | | ?BAD ARG | No device name was included in the LOAD | | | command. | | | | | ?BAD INPUT | An error was detected in the binary file; | | | it is not a proper input for the LOAD | | | command. | | | | | ?BAD LOAD | An attempt was made to load a binary | | | handler that is not in the correct format. | | | | | ?BAD ORIGIN | The origin in a binary file is not in the | | | range 200-577. | ---------------------------------------------------------------------- (continued on next page) 9-23 BUILD Table 9-6 (Cont.) BUILD Error Messages ---------------------------------------------------------------------- | Message | Explanation | |--------------------|-----------------------------------------------| | | | | ?CORE | A CORE command specified more memory than | | | is physically available, or the BOOT | | | command was issued on an 8K system with a | | | 2-page system handler active. Two-page | | | system handlers require at least 12K of | | | core to be present on the OS/8 system. | | | | | ?DSK | The device specified in a DSK command is | | | not a file structured device. | | | | | ?HANDLERS | More than 15 handlers, including SYS and | | | DSK, were active when a BOOT command was | | | issued. | | | | | I/O ERR | An error occurred while reading from an | | | input device during a LOAD command. | | | | | ?NAME | A device or file name was not designated in | | | a command that requires one to be present. | | | | | NO ROOM | Too many device handlers were present on | | | the system when a LOAD or BUILD command was | | | typed. The UNLOAD command must be used to | | | remove a handler before another can be | | | loaded. | | | | | name NOT FOUND | The device or file name designated in the | | | command was not found. | | | | | ?PLAT | The =n in a SYS command is too large for | | | the device specified, e.g., RF08=5. | | | | | ?SLOTS | More than eight groups of non-system | | | handlers were inserted. Each slot may have | | | more than one entry point. To correct, | | | delete GNAMES until there are eight or | | | fewer groups of nonsystem handlers. | | | | | ?SYNTAX | An illegal character was typed in a BUILD | | | command line. The line must be retyped. | ---------------------------------------------------------------------- (continued on next page) 9-24 BUILD Table 9-6 (Cont.) BUILD Error Messages ---------------------------------------------------------------------- | Message | Explanation | |--------------------|-----------------------------------------------| | | | | ?SYS | One of the following conditions exists: | | | | | | a. A permanent name in a SYS command was | | | not a system handler or coresident with | | | one. | | | b. A BOOT command was issued when two or | | | more system handlers were active. | | | c. A BOOT command was issued when an | | | active handler that must be coresident | | | with a SYS handler did not have the | | | system handler active. | | | | | SYS ERR | An I/O error occurred with a system | | | handler. The computer halts. Press CONT | | | to retry or restart the BUILD procedure | | | from the beginning. Do not assume that a | | | valid OS/8 system remains in core. | | | | | SYS NOT FOUND | No active handler with the name SYS was | | | present when a BOOTSTRAP command was | | | issued. | ---------------------------------------------------------------------- 9.5 BUILD DEVICE HANDLER FORMAT Use the BUILD command LOAD to load device handlers not provided by BUILD into core. They can then be inserted into the OS/8 system. The format of the input to load is a binary file containing the handler as well as a header block that contains information pertaining to the devices included in that file. You should code the handler in PAL8 machine language. The structure of the source for a BUILD device handler is: *0 HEADER BLOCK *200 BODY OF DEVICE HANDLER The origins at 0 and 200 are vital to BUILD. The *0 is an important part of the header block. If you omit this, you cannot load. The *200 is also necessary for loading. If the handler contains an origin outside the range 200-577, BUILD generates an error message and then aborts the load. 9-25 BUILD 9.5.1 Header Block The header block contains the following information: Word 1: -X, where X is the number of separate handlers contained in this file. Thus a handler for TC08 has the first word equal to -10(octal). Words 2-9: Descriptor block for the first handler in the group. Words 10-17: Descriptor block for second handler in the group. . . . . . . Descriptor block for the last handler in the group. If the handler is a system handler, the length of the bootstrap and the bootstrap itself follows. Thus, each handler in the group must have an eight-word block describing its characteristics. If more than twelve handlers are in a group, an error generates during the LOAD. 9.5.2 Descriptor Block Each eight-word descriptor block contains the following information: Words 1,2: Device type name. This name is the group name, or type, of all the handlers in this group. It is usually designated by the DEVICE pseudo-op. Example: DEVICE RK8 Words 3,4: OS/8 device name. This is the name (permanent name) by which the particular device will be recognized in the OS/8 system. The NAME command can alter it. Example: DEVICE RKA0 Word 5: Device Control Block. This word reflects the type of device, in accordance with Table 9-7. Bits 9-11 specify the maximum number of platters on the device (0=1). Example: 4050 9-26 BUILD Word 6: Entry point word. This word must contain the entry point offset in bits 5-11 (see Section 9.5.4). Bit 0 should be a 1 if the handler is a two-page handler. Bit 1 should be a 1 if the entry point is SYS. Bit 2 should be a 1 if the entry point is coresident with SYS. Example: 0020 Word 7: Must be 0. Word 8: Must be 0, except for a system handler that uses it to specify the block length of the device as a negative number. As an example, consider the handler for the nonsystem RK05 handlers. This file contains four separate handlers; the source code would appear as follows: *O -4 /4 DEVICES DEVICE RK05; DEVICE RKA0; 4050; 0020; ZBLOCK 2 DEVICE RK05; DEVICE RKB0; 4050; 0021; ZBLOCK 2 DEVICE RK05; DEVICE RKA1; 4050; 0022; ZBLOCK 2 DEVICE RK05; DEVICE RKB1; 4050; 0023; ZBLOCK 2 *200 (HANDLER BODY) The device type of the group is RK05 (Words 1-2). The permanent device names are RKA0, RKB0, RKA1, RKB1. Since each device is RK05, the device control block (DCB) word for each is identical. The entry point word indicates where the entry point for that particular device occurs relative to the top of the page. Thus, in the above example, RKA0 enters at the 20th location from the top of the page, RKB0 at the 21st, etc. It is vital that this information is accurate. If errors exist in this data, unpredictable results occur when you generate the system. 9.5.3 Breakdown of DCB Word The DCB word for a device provides specific information that is used in the OS/8 Monitor. Table 9-7 details its structure. 9-27 BUILD Table 9-7 DCB Word ---------------------------------------------------------------------- | Bit | Meaning | |---------------|----------------------------------------------------| | | | | 0 | 1 if file structured device | | | | | 1 | 1 if read-only device (e.g., PTR) | | | | | 2 | 1 if write-only device (e.g., LPT) | | | | | | Device Type | | | | | 3-8 | 00 = console terminal | | | 01 = high-speed paper tape reader | | | 02 = high-speed paper tape punch | | | 03 = card reader | | | 04 = line printer | | | 05 = RK8 Disk | | | 06 = RF08 (1 platter) | | | 07 = RF08 (2 platter) | | | 10 = RF08 (3 platter) | | | 11 = RF08 (4 platter) | | | 12 = DF32 (1 platter) | | | 13 = DF32 (2 platter) | | | 14 = DF32 (3 platter) | | | 15 = DF32 (4 platter) | | | 16 = TC08 DECtape | | | 17 = LINCtape | | | 20 = TM8E magnetic tape | | | 21 = TD8E DECtape | | | 22 = BAT - BATCH handler | | | 23 = RK8E disk | | | 24 = NULL - NULL handler | | | 25 = RX01 diskette | | | 26 = Unused | | | 27 = TA8E cassettes | | | 30 = PDP-12 scope | | | 31-35 = Unused by DIGITAL | | | 36 = Dump Handler | | | 37 = Unused by DIGITAL | | | 40-77 = Reserved for user-written handlers | | | | | 9-11 | Used only by OS/8 Monitor | ---------------------------------------------------------------------- Whenever you insert a device into OS/8, follow this structure to obtain correct results. 9-28 BUILD 9.5.4 Entry Point Offset Word 6 of each device descriptor block specifies the relative entry point of that particular handler. Devices supplied by DIGITAL have a fixed set of entry prints, described below. Use care when coding new device handlers for insertion into the system. The entry point offset for the new handler must not be the same for any other file structured device in the system. For example, OS/8 currently uses relative entry points 7-24 for file structured devices. No new handler should have entry points at 7 to 24 of the page. If this occurs, the system may perform incorrectly. Current file device and entry point offsets appear below: Device Entry Relative to Top of Page ______ _____________________________ TC08 DECtape 10-17 TD8E DECtape 10-17 LINCtape 10-17 System device 7 RK8/RK8E disk 20-23 RF/DF disk 24 RXA0 30 RXA1 34 Thus, the user-coded file devices should use entry points other than 7-24, 30, 34. If you add a new file structured user device to the system, alter the device-length table in PIP to permit zeroing of the device directory. To do this, use ODT as follows: .GET SYS PIP .ODT 136nn/0000 xxxx ^C (user types CTRL/C) .SAVE SYS PIP The nn represents the two-digit device Table 9-7 indicates. The xxxx is the negative of the last block number on the device. Both nn and xxxx are octal numbers. For example, if you assign the new device a code of 40 (currently the first unused entry, and the last OS/8 block on the device was block 1000, PIP would charge as follows: .GET SYS PIP _ .ODT _ 13640/0000 7000 ____ ^C .SAVE SYS PIP _ 9-29 BUILD 9.6 CREATING A SYSTEM HANDLER When you create a new system handler, observe the following restrictions: o The length of a bootstrap must be greater than or equal to 21 (octal) locations. You must pad a bootstrap shorter than 21 locations, otherwise BUILD results are unpredictable. o The length of the bootstrap must be less than or equal to 177 (octal) locations. o If the system handler is a one-page handler, only the first 47 (octal) locations of the bootstrap are significant. The remaining locations are ignored and not written on the system device. Also, no handler may have more than 12 (octal) entry points. o If a system handler is two pages long, relative location 12 of the first page must contain a 3. The second page loads into location 27600 and is stored in block 66 of SYS:. 9-30