LS-DOS 6.3.1 for the Model 4 - SYS1/SYS Disassembled
Page Customization
Page Index
SYS1/SYS
Other Navigation
Introduction/Summary
LS-DOS 6.3.1 SYS1/SYS Disassembly (Model 4)
SYS1/SYS is the system overlay of LS-DOS 6.3.1 that holds the command interpreter, the routine behind the LS-DOS Ready prompt. It is a load module of 1265 bytes in six load blocks: 1E00H-22EEH in the overlay area and the length word at 23FEH-23FFH, with its transfer address at 1E00H. CKMOD@ on the SYS0/SYS page reads it into 1E00H whenever an SVC asks for overlay 3 and it is not already resident, and RST28 calls 1E00H with the request in Register A: 93H @EXIT, A3H @CMNDR, B3H @CMNDI, C3H @FSPEC, D3H @FEXT or E3H @PARAM. Bits 6-4 of the request pick the function (1E00H).
@EXIT goes through CLEANUP (1E41H), which resets the stack to 0380H with the address of @EXIT under it, gives BREAK back to the system, sets the debugger hook from SFLAG$, clears the PAUSE and ENTER bits, bits 0-2 of SFLAG$ and every bit of CFLAG$ but bit 5, and sets LOW$ to 2FFFH. The interpreter (1E8EH) then hands control to an Extended Command Interpreter in SYS13/SYS when EFLAG$ is not zero, or shows LS-DOS Ready and reads a line of up to 79 characters into INBUF$ (0420H). It switches in memory bank 0 and logs the line; a line starting with a period is a comment, one starting with * goes to SYS13/SYS, and one starting with ! is always run as a program. The command name is parsed into the system FCB at 00E0H and looked up in the library command table (1F24H), 39 names that run members of SYS6/SYS, SYS7/SYS and SYS8/SYS, and BOOT; any other name gets /CMD added and is run by @RUN. @CMNDI does the same with a line passed by a program, and @CMNDR runs it without CLEANUP, so that the command returns to the program.
The rest of the overlay is the parser shared with the commands: @FSPEC (205EH) copies a file or device specification into an FCB, passing over the prepositions TO, ON, OVER and USING; @FEXT (20D1H) adds a default extension; @PARSER (2105H) copies one word; @FNDPRM (2157H) looks a word up in a table of the old format (names of six characters) or the enhanced one (a leading 80H, then for each entry a type byte, the name, a response byte and an address word); and @PARAM (21D7H) reads a parameter list in parentheses, with flag, decimal, hexadecimal (X'nnnn') and string values (2242H).
The bytes are those of the LS-DOS 6.3.1 level 1H system diskette. The labels are those of the LS-DOS 6.3.1 source code of SYS1, which assembles to this file byte for byte.
Notes
Two places hide an instruction: 213CH (FEH, a CP 23H that skips the INC HL of the space loop) and 226DH (3AH, an LD A,(FECBH) that skips the SET 7 of a number).
Several operands are changed while SYS1 runs: 1EE6H (the exclamation mark test of TSTEXC), 2145H (PAR6, the mark of an empty word), and 217FH, 219DH and 21B7H, which @FNDPRM sets from the format of each table.
CLEANUP does not look at the return code in Register Pair HL that a program gives to @EXIT. The word at 1E02H points to the library table, and the LIB command reads it while SYS1 is still in the overlay area; the word at 23FEH is the length of the overlay, which SYSTEM (SYSRES) uses to keep a copy in high memory.
LS-DOS 6.3.1 changes visible here: @PARSER passes over the spaces after a word (2138H); @PARAM accepts a list that ends at the end of the line without a closing parenthesis (223AH), clears the response bytes with a shorter loop and sets the value FFFFH with a DEC BC (2229H, 22A5H).
Bugs (listed on the LS-DOS reference page): B11, @FNDPRM (21B2H) does not check that the word ends where a name that fills its field ends, so a command name such as APPENDIX or SETCOMM runs the library command APPEND or SETCOM; B12, a file specification that ends with an exclamation mark at the end of the line leaves Register Pair HL one byte past the 0DH, and one followed by an opening parenthesis loses it (208DH); B13, @PARAM leaves the response bytes as they were when there is no parameter list (21DAH, latent); B14, a file named TO, ON, OVER or USING cannot be given to @FSPEC (209DH, a limit); B15, the signs : ; < = > ? @ and [ \ ] ^ _ ` and the letters W, X, Y and Z are taken as hexadecimal digits in X'nnnn' (22C7H).
Variables
Memory Used by SYS1/SYS
| Address Size | Contents |
|---|---|
| 001EH-001FH 2 bytes | LOW$ Set to 2FFFH by CLEANUP on every @EXIT and @CMNDI (1E73H). |
| 006CH 1 byte | CFLAG$ Bit 1 set by @CMNDR (1E34H), bit 2 set while @KEYIN reads a command (1EA0H, 1EADH), bit 4 tested for library commands only (1EFCH); CLEANUP keeps only bit 5 (1E7FH). |
| 006EH 1 byte | EFLAG$ Not zero when an Extended Command Interpreter is in SYS13/SYS; bits 6-4 are its function (1E8EH). |
| 0074H 1 byte | KFLAG$ Bits 1 (PAUSE) and 2 (ENTER) cleared by CLEANUP (1E65H). |
| 007CH 1 byte | SFLAG$ Bit 7 sets the debugger hook (1E56H), bits 2-0 cleared by CLEANUP (1E6CH), bit 5 (a DO file running) tested by COMMENT (1F08H). |
| 00E0H-00FFH 32 bytes | CFCB$ The system command FCB, into which the command name is parsed (1EC5H). |
| 0420H-046FH 80 bytes | INBUF$ The command line buffer: 79 bytes copied in by @CMNDR and @CMNDI with 03H at 046FH (1E1DH), or read by @KEYIN (1EA3H). |
| 0835H-0836H 2 bytes | OPREG_SV_PTR The save pointer of ENADIS_DO_RAM, reset to 086EH by CLEANUP (1E79H). |
| 199FH 1 byte | @DBGHK The debugger hook: 00H (on) or C9H (off) from SFLAG$ bit 7 (1E5FH); C9H before a library command (1F14H). |
| 1D00H-1D0FH 16 bytes | SBUFF$ The word of each parameter, copied by @PARAM for @FNDPRM (2200H); in page 1DH also the response bits of an old format table (21C3H). |
| 1E02H-1E03H 2 bytes | LIBTBL$ pointer 1F24H, the address of the library command table, read by the LIB command. |
| 1EE6H 1 byte | TSTEXC operand 00H when the command line starts with an exclamation mark (1EDCH). |
| 2145H 1 byte | PAR6 operand Not zero until @PARSER copies a character (2108H, 212EH). |
| 217FH, 219DH, 21B7H 3 bytes | FND2, FND3A and FND5A operands The entry length, the characters to compare after the first and the offset of the word, set by @FNDPRM from the table format (2177H, 216FH, 2173H). |
| 23FEH-23FFH 2 bytes | Overlay length 04EFH, the length of SYS1, read by SYSTEM (SYSRES). |
Routines of Other Files Called
| Address | Routine |
|---|---|
| 03E1H | @DECHEX (SYS0/SYS): decimal text to binary, for a numeric parameter (2264H). |
| 0503H | @LOGER (BOOT/SYS): logs the command line (1EC2H). |
| 052DH | @DSPLY (BOOT/SYS): shows LS-DOS Ready (1E9AH). |
| 0553H | @CKBRKC (BOOT/SYS): clears a pending BREAK (1E2EH, 1E8AH). |
| 0585H | @KEYIN (BOOT/SYS): reads the command line (1EA9H). |
| 0642H | @DSP (BOOT/SYS): the new line before a command runs (1EB9H). |
| 0877H | @BANK (BOOT/SYS): switches in bank 0 (1EBFH). |
| 196FH | @BREAK (SYS0/SYS): gives BREAK back to the system (1E4AH). |
| 1B1DH | @RUN (SYS0/SYS): loads and runs a /CMD program (1EFEH). |
| RST 28H | SYS13/SYS for an ECI (1E96H) or a * line (1ED6H), the libraries SYS6/SYS, SYS7/SYS and SYS8/SYS (1F21H), @IPL for BOOT (1F23H). |
Disassembly
1E00H - SYS1: Entry and the Function Dispatcher
SYS1/SYS is loaded at 1E00H by CKMOD@ (1A7FH on the SYS0/SYS page) whenever an SVC asks for overlay 3 and it is not already resident, and RST28 calls 1E00H with Register A holding the request: 93H @EXIT, A3H @CMNDR, B3H @CMNDI, C3H @FSPEC, D3H @FEXT and E3H @PARAM, sent by the stubs at 1B0BH and 197BH-1987H. Bits 6-4 of the request pick the function. The word at 1E02H points to the library command table, which the LIB command reads while SYS1 is still in the overlay area. @CMNDR and @CMNDI first copy the caller's command line into INBUF$ (0420H); @CMNDR keeps the caller's stack and memory settings, @CMNDI goes through CLEANUP like @EXIT.
1E41H - @EXIT and CLEANUP: Return to the Command Level
@EXIT (SVC 22, request 93H) comes here from 1B0BH, @ABORT through it with Register Pair HL = FFFFH. CLEANUP does not look at Register Pair HL: the return code is lost here. CLEANUP resets the system for the next command: the BREAK vector goes back to the system, the stack is reset to STACK$ (0380H) with the address of @EXIT under the return address, the debugger hook is set from SFLAG$ bit 7, the PAUSE and ENTER bits of KFLAG$ and the three low bits of SFLAG$ are cleared, LOW$ becomes 2FFFH, the pointer of the video memory switch (OPREG_SV_PTR) goes back to its rest value, and CFLAG$ keeps only bit 5. A pending BREAK is cleared last.
1E8EH - The Command Interpreter: LS-DOS Ready
CMDCONT hands control to an Extended Command Interpreter in SYS13/SYS when EFLAG$ is not zero; otherwise it shows LS-DOS Ready and reads a line of up to 79 characters into INBUF$ (0420H) with @KEYIN, with bit 2 of CFLAG$ set while it waits. BREAK at the prompt starts over through @EXIT. CMD3A sends a new line unless the line is a comment (it starts with a period). CMD20, where @CMNDR joins, switches in memory bank 0, logs the line, and then: a comment line asks for the next line (or, while a DO file runs, ends the command); a line starting with * goes to SYS13/SYS function 7; a line starting with ! is run as a program even when its name is a library command; otherwise the name is parsed into the system FCB at 00E0H, looked up in the library table, and run as a library command, or else run with @RUN as a /CMD file.
Store Register A (00H for an exclamation mark, any other value otherwise) into 1EE6H, the operand of the LD A at 1EE5H (TSTEXC).
Load Register A with the operand at 1EE6H, stored at 1EDCH: 00H when the line started with an exclamation mark. The file holds 00H.
1F24H - LIBTBL$: The Library Command Table
The 39 command names of SYS1: 38 library commands, run from the libraries SYS6/SYS, SYS7/SYS and SYS8/SYS, and BOOT, in alphabetical order, in the old format of @FNDPRM: a name of six characters padded with spaces, then a word. In a word with bit 7 set, bits 6-5 pick the library (8000H SYS6, A000H SYS7, C000H SYS8, turned into the requests 88H, 89H and 8AH at 1F17H) and the low byte is the request code of the member entry that CKMOD@ looks for in the library file; a word with bit 7 clear is an address in SYS1 (BOOT, 1F22H). A 00H where the next name would start ends the table (205CH). LIB lists this table, reading its address from 1E02H.
205EH - FSPEC: @FSPEC, Parse a File or Device Specification
@FSPEC (SVC 78, request C3H) copies a specification from the text at Register Pair HL into the FCB at Register Pair DE, in capitals: a name of up to 8 characters, then optional parts in this order: /extension (3), .password (8), :drive (1) and the exclamation mark that asks for the end of file to be written to the directory on every write. The text in the FCB ends with 03H (ETX). A device is * and two characters. When the word parsed is one of the prepositions TO, ON, OVER or USING, it is dropped and the next word is parsed into the same FCB. The return is Z with Register A = 00H for a valid specification, Register Pair HL after it (at the next word when spaces follow); NZ with Register A = the character that stopped it for an error. The command interpreter uses it for the command name (1EDFH).
20D1H - FEXT: @FEXT, Insert a Default Extension
@FEXT (SVC 79, request D3H) looks at the text in the FCB at Register Pair DE: if the name, read from its second character for up to nine letters and digits, ends in a slash, the file has an extension and nothing changes. Otherwise the rest of the text from the character that ended the name (a period, a colon, an exclamation mark or the 03H) is moved four bytes up and /ext, the three characters at Register Pair HL, is put in. Register Pair DE returns the FCB; Register Pair BC and, when the extension is inserted, Register Pair HL are changed. The command interpreter uses it to add /CMD to a program name (1EF5H).
2105H - @PARSER: Copy One Word into a Buffer
@PARSER (entered with Register B = 8) and @PAR1 (Register B = the length) copy the letters and digits at Register Pair HL to Register Pair DE, small letters made capitals, at most Register B of them; further letters and digits are passed over. The word ends at 03H, 0DH or an opening parenthesis (left at Register Pair HL) or at any other character (Register Pair HL is left after it). A space that ends the word is followed past the spaces after it, a change of LS-DOS 6.3.1. A 03H is stored after the word at Register Pair DE. The return is Z when at least one character was copied, NZ for an empty word, with Register A and Register C = the separator. FSPEC and PARAM use it; TST09AZ, the test for a letter or digit, is shared with @FNDPRM.
Store Register A (the length, never 00H) into 2145H, the operand of the LD A at 2144H (PAR6): it stays non zero, the mark of an empty word, until a character is copied.
Store Register A (00H) into 2145H, the operand of the LD A at 2144H: at least one character has been copied.
Load Register A with the operand at 2145H: 00H when a character was copied, the length stored at 2108H when none was. The file holds 00H.
2157H - @FNDPRM: Look Up a Word in a Table
@FNDPRM looks up the word at Register Pair DE (ended by 03H, 0DH or any character that is not a letter or digit) in the table at Register Pair BC. A table whose first byte has bit 7 set (80H) is in the enhanced format: after that byte, entries of a type byte (bits 3-0 the name length, bit 4 a single letter abbreviation allowed), the name, a response byte and a word. Any other table is in the old format: names of six characters padded with spaces, each with a word. A 00H where the next entry starts ends the table. Three instruction operands (217FH, 219DH and 21B7H) are set from the format: the step from a name to the next entry, the characters to compare after the first, and the offset of the word. The return is Z with Register Pair DE = the entry's word and Register Pair BC = the address of its response byte (for an old table, a byte in page 1DH, SBUFF$, so that the table is not changed), or NZ with Register A = 01H when the word is not in the table; Register Pair HL is kept. The word matches when its characters agree with the name for the name's length: a longer word whose first characters are a name that fills its field (any name of an enhanced table, a six letter name of an old one) matches that name (bug B11).
Store Register A (the name length less 1; 05H for an old table) into 219DH, the operand of the LD B at 219CH (FND3A).
Store Register A (the offset of the word) into 21B7H, the operand of the LD BC at 21B6H (FND5A).
Store Register A into 217FH, the low byte of the operand of the LD BC at 217EH (FND2), the step to the next entry.
Load Register Pair BC with the length of an entry, the operand at 217FH stored at 2177H. The file holds 0008H.
Load Register B with the characters to compare after the first, the operand at 219DH stored at 216FH. The file holds 05H.
Load Register Pair BC with the offset of the entry's word from its name, the operand at 21B7H stored at 2173H. The file holds 0006H.
21D6H - PARAM: @PARAM, Parse a Parameter List
@PARAM (SVC 17, request E3H) reads the parameters at Register Pair HL against the table at Register Pair DE. Spaces are passed over; a line that ends (0DH) or does not go on with an opening parenthesis returns Z at once, and the response bytes of the table are then left as they were. With a parenthesis, the response bytes of an enhanced table are first set to zero; then each word (up to 15 characters, copied to SBUFF$ at 1D00H) is looked up with @FNDPRM, and its value goes into the two bytes the entry's word points to: FFFFH for a word without =, else the value after = (ASSIGN at 2242H). Parameters are separated by commas; the list ends at the closing parenthesis or, since LS-DOS 6.3.1, at 0DH. A word not in the table or a bad value returns NZ with Register A = 2CH (44, Parameter error). The types allowed by an entry's type byte are not checked: the program reads the response byte.
2242H - ASSIGN: The Value after the Equals Sign
ASSIGN reads the value of a parameter and sets its response byte; the value goes into Register Pair BC, which PARAM4 (222DH) stores. A value in double quotes is a string: Register Pair BC = the address of its first character, the response byte 20H plus the length (0 for a string longer than 31 characters, and for an empty one, whose address then holds the closing quote). X'nnnn' is a hexadecimal number and a value starting with a digit a decimal number (@DECHEX), both marked with bit 7. A value starting with Y, N or O (ON, OFF) is a flag, FFFFH or 0000H, marked with bit 6, as is an empty value (PARM=), which gives 0000H. Any other value is a Parameter error.
22DDH - Texts, Free Space and the Overlay Length
The default extension for programs, the LS-DOS Ready prompt, the bytes of the overlay area not loaded, and the length of SYS1 at 23FEH, as in the other system overlays.