LDOS 5.3.1 for the Model III - HELP/CMD Disassembled

HELP/CMD

Other Navigation

LDOS 5.3.1 HELP/CMD Disassembly - The Help Files (Model III)

HELP/CMD displays the help texts of the /HLP files: DOS/HLP for the commands of the DOS and BASIC/HLP for the statements and functions of Disk BASIC. The command is HELP [filespec [keyword]] [(P,V,B,S)] (M-40-060). HELP DOS LIB displays the text filed under LIB in DOS/HLP; HELP DOS lists the keywords of the file and asks for one; HELP alone lists the HELP files on every drive that is ready and asks for one; HELP followed by an asterisk and a keyword (the manual's HELP *MEMORY) scans every HELP file for the keyword, the global scan. The parameters: P sends the text to the printer as well and does not pause, V does not restore the screen at the end, B stops the blinking of the characters marked in the text, and S (search mode) lists only the keywords that start with the word given. The manual's R parameter is for DOS version 6; this HELP passes over it, and over any other letter, without an error. HELP can also be called from BASIC with CMD"HELP ...".

The file is a load module of 2399 bytes: a record of type 1FH with the text Copyright 1991 MISOSYS, Inc., All rights reserved, nine load blocks for 5200H-5AEFH (2288 bytes), three small blocks that give first values to cells beyond the file (5B18H, 5C90H, 6093H-6098H, 8 bytes) and the transfer address record for 5200H. HIGH$ must be at least 6497H. A HELP file is opened with a record length of 1 and read one byte at a time with @READ through the alternate Register Pairs (DE' the file control block 5AF0H, HL' the byte 5C90H). Its last two bytes hold the offset of its keyword index; the index holds the keywords in alphabetical order, each with bit 7 set on its last letter and followed by the two byte offset of its text, which ends with 0CH. The text is compressed: a byte of 80H or more is a character followed by a space, and a second one straight after it is a run of spaces; 7FH marks a place that blinks.

What HELP Does

About This Page

5200H - Entry: the Memory Test and the Copy of the Command Line

LDOS Ready loads HELP/CMD at 5200H-5AEFH (with three small blocks beyond it at 5B18H, 5C90H and 6093H-6098H) and jumps to 5200H, the transfer address, with Register Pair HL at the rest of the command line after the word HELP and the spaces after it. The command is HELP [filespec [keyword]] [(P,V,B,S)], or HELP followed by an asterisk and a keyword for the global scan (M-40-060). HIGH$ must be at least 6497H, 1024 bytes above 6097H, the first byte after the file's cells; else Not enough Memory for HELP and @ABORT. Index Register IY points at the two flag bytes at 5AE5H for the whole program. The command line up to its 0DH is copied to 5B19H, so that the category and keyword prompts can later put a new line in the same place.

5236H - The First Word of the Line

Register Pair HL goes over the spaces of the line at 5B19H. The line is taken from here again when an answer to the category prompt has been typed (5718H). An empty line, or one that starts with an asterisk, goes to 531DH with the pointer on the stack: there 57C1H finds the asterisk and starts the global scan with the word after it. A line that starts with an opening parenthesis has only parameters. Anything else is the file specification.

5251H - The Parameters

The letters inside the parentheses are taken one at a time, made capitals with RES 5: P (output to the printer as well, IY+00H bit 7 set), V (no restore of the screen, bit 6 cleared), S (search mode, bit 4 set) and B (no blinking, bit 5 cleared). Each letter must be followed by 0DH, a closing parenthesis or a comma (58B8H), else Parameter Error. Any other character, a comma or a letter such as R, is passed over without an error. A closing parenthesis or 0DH ends the list. Bit 6 and bit 5 are set in the file (60H at 5AE5H), so the screen is restored and the marked characters blink unless V or B is given.

5299H - The HELP File and the Keyword

The word at Register Pair HL is taken by @FSPEC into the file control block at 5AF0H; a word that is not a file specification is dropped and HELP lists the files on line. The first characters of the line taken, at most 8, are copied from the specification in the control block to 5B10H for the heading Directory for HELP file. Then the keyword: during the global scan it is already at 5B59H; otherwise it is the next word of the line, up to 0DH or an opening parenthesis, with small letters made capitals in place. It is copied to 5B59H, one space at its end is dropped, and it gets 0DH; IY+00H bit 1 says a keyword was given. A keyword may hold a space, as DEBUG EXT does in DOS/HLP.

531DH - Save the Screen, Open the File, Find the Index

Unless V was given (IY+00H bit 6 clear) or the screen is already saved (bit 0), the 1024 bytes of video memory 3C00H-3FFFH are copied to 5C91H-6090H and the cursor address of the video device control block (4020H-4021H) to 5AECH-5AEDH, so that 5734H can put them back at the end. With no file named, HELP lists the HELP files on line (579DH). Else the default extension HLP is added (@FEXT) and the file is opened with a record length of 1 and the buffer 5B90H; a file that does not open also leads to the list. The last two bytes of a HELP file hold the offset of its keyword index: @PEOF moves to the end, two @BKSP move back two bytes, and 58D8H reads the word and moves there with @POSN.

5379H - Look Up the Keyword in the Index

Without a keyword, or in search mode, HELP goes to the directory of the file (5580H). Else the keyword at 5B59H is made capitals (again) and compared with the index, which holds each keyword with bit 7 set on its last letter, followed by the two byte offset of its text. The keywords of the index are in alphabetical order, so the search ends at the first keyword that sorts after the one asked for: then, or at the end of the file, the keyword is not there and the directory is displayed instead (the manual: the list of all keywords displays again). Register C = 01H marks the last letter of the index keyword being compared.

53DAH - Display the Text of a Keyword

The keyword was found: the two bytes after it are the offset of its text, and the file is moved there. The screen is cleared, the keyword is displayed as the first line, and with P the banner and the keyword go to the printer as well. Then the text is read byte by byte up to its 0CH. The text is compressed: a byte of 80H or more is a character (without bit 7) followed by a space, and a second such byte straight after it (IY+01H bit 0 set) is a run of that many spaces; 7FH marks the place where the cursor is as one that blinks; 8DH at the bottom line is a line end (54C8H). Every character goes through 54B6H, which stops at the bottom of the screen.

5456H - Send a Character to the Printer

With P (IY+00H bit 7) every character displayed is also printed through ROM 003BH. 5AEEH counts the columns of the printer line from 01H: when it reaches 41H, 64 characters printed, a 0DH is printed first. A 0DH sets the count back to 01H.

5481H - A Plain Character, or a Run of Spaces

A byte below 80H is displayed as it is. When the last byte before the bottom line was 8DH (IY+01H bit 1, set by 54D6H), a space is displayed first. A byte of 80H or more straight after a character with a space is a run of spaces: Register B = the byte without bit 7, one more after an 8DH; each space goes through the test of the bottom of the screen.

54B6H - The Bottom of the Screen

Register A = the byte about to be displayed, Register Pair HL = the cursor address. While the cursor address is below 3FBFH the routine returns at once. From 3FBFH on, the last place of line 15 and line 16, a 0DH or 0AH (and an 8DH that does not follow a character with a space) ends the screen there, and so does a character when the cursor is at 3FFEH: the character is kept at 5AEFH (00H for the line end) and 54E8H waits for a key. The CALL is then answered by 5571H with the byte in Register A, or the byte is dropped and the text read on (5579H).

54E8H - The End of a Screen: Blink and Wait

Register A = 0CH at the end of the text, 00H for a line end, or the byte held back. The blink table gets 0000H at its end. Without P, the places of the table are made to blink: each entry's character and the one kept in it are swapped, the keyboard is scanned (ROM 002BH) and ROM 0060H waits about 0.38 second (BC = 6400H, 30 T-states a count at 2.03 MHz), until a key is pressed. With no entries the program waits for a key with ROM 0049H, only when the cursor is on the last line. BREAK (01H) ends HELP. Else the screen is cleared (1CH, 1FH) and the text goes on; at the end of the text the prompt follows (56DDH).

5580H - The Directory of a HELP File

Shown when no keyword was given, when the keyword is not in the file, and in search mode. During the global scan a file without the keyword is simply passed over (5872H). The screen is cleared, the banner and Directory for HELP file : with the name kept at 5B10H are displayed (and printed with P). Then the index is read from its start: each keyword is collected at 5B19H, Register C its length, and padded with spaces to the next 16 column place. A keyword of up to 15 characters takes one column of 16; a longer one goes on to the next multiple of 16 (5665H). In search mode only the keywords whose first letters are the word given are shown (58FBH). The last line of the screen is kept for the prompt: when a keyword would reach 3FBFH, IY+01H bit 2 says the directory goes on, and the prompt follows.

5665H - A Keyword Longer than 15 Letters

Register C = the length, Register Pair HL = the cursor address. The keyword fits the line when the column count, from the low byte of the cursor address, does not reach a multiple of 64 within Register C places; it is then padded to the next multiple of 16 after it (Register C grows by the padding). A keyword that does not fit starts a new line (56BDH). When the screen would be full, the keyword is held back at 5B19H (IY+01H bit 2, and bit 3 for one that needs a new line, with Register Pairs DE and BC on the stack) and displayed on the next screen.

56CCH - The End of a Screen of the Directory, and the Prompt

Register A = FFH when the last keyword has been displayed: the jump at 5785H is then pointed at 5788H, which does not display it again. With P the next screen follows without a prompt (5765H). The prompt is Press <BREAK>,<ENTER> or type keyword, or during the global scan Press <BREAK> to exit or <ENTER> to continue Global Scan (5860H). The answer is taken by ROM 0040H at 5B59H, 53 characters at most: BREAK ends HELP, ENTER alone shows the next screen of the directory (or the directory again from its start), and a keyword is looked up in the same file (5363H). The category prompt of 57FAH enters at 56F3H with Register Pair HL = 5B19H and Register B = 08H: its answer is a new command line (5236H).

5722H - The End of HELP

BREAK, ENTER at the category prompt, a parameter error and a read error end here. The HELP file is closed when one was opened. Unless V was given the screen is copied back from 5C91H and the cursor address put back into 4020H-4021H. When 402DH, @EXIT, does not hold C3H (no program such as BASIC has put a JP there, so HELP was typed at LDOS Ready), three 1BH codes move the cursor up three lines, so that the HELP command itself is written over (the manual: the screen is restored less the help command). The printer line is ended and HELP goes to @EXIT.

575EH - ENTER Alone: the Next Screen of the Directory

When the directory has more (IY+01H bit 2), the screen is cleared and the listing goes on: the keyword held back is displayed at the top through the jump at 5785H (5696H, or 5788H when it was already displayed); one that needed a new line (IY+01H bit 3) is placed again by 5665H with the Register Pairs pushed at 56B9H. Without more, the directory starts again from the beginning (5580H). At the category prompt this way reads the file named last, or none: 55B6H then ends with Source File Read Error, which the restored screen covers again unless V was given.

579DH - The HELP Files on Line

When no file was named, or the file named does not open. The list is built at 6095H: for each drive 0-7 that @CKDRV finds ready, @DODIR with Register B = 03H (the records of the files whose extension matches the mask) puts 18 bytes of the directory record of each /HLP file into the list and ends it with FFH. The mask, HLP, is copied to the place of each FFH before the next drive; the address after the last FFH becomes the start of the blink table (6093H). The word on the stack is then taken back: when it points at an asterisk the global scan starts (580CH). Else the screen shows the banner, Help Categories presently on line are: and the 8 characters of each name, four to a line (a column of 16), and the category prompt.

580CH - The Global Scan

HELP, an asterisk and a keyword: the keyword after the asterisk is copied to 5B59H up to its 0DH, and IY+00H bit 3 is set. For each entry of the list at 6095H the screen is cleared, Global Search in File: and the name are displayed at the top (the name at 3C18H), the name is copied to 5B19H and opened as a new file specification at 5299H, which takes the keyword already at 5B59H (52C9H). The address of the next entry is kept on the stack. A file without the keyword is closed and the next one tried (5872H); after a text the prompt asks for BREAK (end) or ENTER (go on). After the last entry: End of Global Scan and the category prompt. Each name is opened without a drive, so @OPEN takes the first drive that has a file of that name.

588BH - Small Routines

588BH displays the space of an 8DH held over from the bottom line; 589BH copies the mask HLP; 58AAH finds the end of the file list; 58B8H tests the end of a parameter letter; 58CFH sets the alternate Register Pairs for the file; 58D8H reads a two byte offset and moves the file there; 58EBH reads one byte of the file; 58FBH compares a keyword of the directory with the word of search mode.

591BH - The Error Messages

A parameter error and a read error display their text and end HELP through 5722H (BIT 5 of IY+00H is cleared on the way, which only stops the blinking); too little memory ends at @ABORT before anything was changed.

5936H - The Texts

The screen codes and the texts of HELP: 1CH puts the cursor home, 1FH clears to the end of the screen, 0AH starts a new line, 03H ends a text for @DSPLY without being sent, 0DH ends a text after it has been sent.

5AE5H - The Flags and the Cells of the File

Index Register IY points at 5AE5H. IY+00H: bit 0 the screen is saved, bit 1 a keyword was given, bit 2 a file was named (open), bit 3 the global scan, bit 4 search mode (S), bit 5 blinking (cleared by B), bit 6 restore the screen (cleared by V), bit 7 the printer (P). IY+01H: bit 0 the last byte was a character with a space, bit 1 an 8DH at the bottom line, bit 2 the directory goes on, bit 3 a keyword waits for a new line.

5AF0H - The Work Areas Beyond the File

The file control block, the name, the line buffer, the keyword, the sector buffer, the byte read, the copy of the screen, the pointer to the blink table and the list of the HELP files. The three one, one and six byte load blocks of the file give 5B18H, 5C90H and 6093H-6098H their first values.