TRS-80 DOS - NEWDOS/80 v2.0 for the Model III - SYS21/SYS Disassembled

SYS21/SYS

Other Navigation

NEWDOS/80 v2.0 SYS21/SYS Disassembly - ERASE, KEEP and the Array Sort CMD"O" (Model III)

SYS21/SYS carries out three Disk BASIC commands. It loads 4D00H-51E7H in five load records (transfer address 4D00H) into the overlay area 4D00H-51FFH; the code ends at 51E1H and 51E2H-51E7H are 6 bytes of 00H. BASIC/CMD runs it with RST 28H, not through its loader at 576CH: code 57H from 57B0H for CMD"F=ERASE" and CMD"F=KEEP" (57AAH and 57AEH, found by SYS20/SYS in BASIC/CMD's table at 592BH, with Register B = 28H or 20H), and code 37H from 57B3H for CMD"O" (from the letter commands at 57DDH). 4D00H drops the dispatcher's return address 4BC5H, so the commands return straight to the ROM's statement loop. The page shows every byte of the file once, in address order.

• CMD"F=ERASE",name,name... deletes the named variables; CMD"F=KEEP",name,name... deletes all others. A name is a simple variable or an array written with parentheses. Each one found is marked with bit 4 of its type byte (4D5BH); 4D67H then copies the kept entries down and stores the new 40FBH and 40FDH. User functions are always kept. A comma at the end of a line continues the list on the next line (BASIC 5D78H); empty lines and REM lines in between are passed over. BASIC's statement-end CALL at 6426H points at 4D67H while the list is read, so an error still closes up the tables.
• CMD"O",n,[*]array(start)[,[-]array(start)...] sorts n elements (n = 0: the rest of the first array) of up to nine arrays, from the same start subscript, as the columns of one table. The first array is the first key, each later one breaks the ties left; a minus sign makes a key descending; a string array may be followed by (position,length). With an asterisk the first array must be an integer array: it is filled with the element numbers start to start + n - 1 and only it is rearranged, by the keys after it (an index sort). The sort is a merge sort in place, with the buffer 5200H-56FFH (BASIC/CMD's overlay area, so 576EH is cleared) and the blocks at 4300H; 4288H is cleared so SYS21/SYS is loaded again next time, because the sort changes operands in its own code.

The Array Blocks at 4300H

4DBAH builds nine blocks of 17H (23) bytes at 4300H-43CEH in SYS0/SYS's sector buffer, numbered 1-9; 43CFH-43D0H (block number 0, type 0) end the table. With an index sort block 1 is the index array and the keys start at block 2 (4317H).

Variables

ROM Addresses

DOS Addresses

BASIC/CMD Addresses

Operands Changed at Run Time

Outside Routines

4D00H - Entry Point: Select CMD"O", ERASE or KEEP

The SYS0/SYS overlay dispatcher loads SYS21/SYS into 4D00H-51E7H and calls 4D00H with Register A holding the RST 28H code that BASIC/CMD issued. Code 37H (function 1 of directory slot 17H) comes from BASIC 57B3H for CMD"O", the array sort. Code 57H (function 2 of slot 17H) comes from BASIC 57B0H for CMD"F=ERASE" (Register B = 28H, loaded at BASIC 57AAH) and CMD"F=KEEP" (Register B = 20H, loaded at BASIC 57AEH). In every case Register Pair HL holds BASIC's text pointer, pointing just past the CMD string in the program line.

4D0EH - CMD"F=ERASE" and CMD"F=KEEP": Mark the Named Variables

CMD"F=ERASE",name,name... deletes the named variables; CMD"F=KEEP",name,name... deletes every variable except the named ones. A name is a simple variable (A, B$, X%) or an array, written with parentheses (A(); anything may stand between them). Each variable found gets bit 4 of its type byte set as a mark; the close-up at 4D67H then copies the kept variables down over the deleted ones. User functions (DEF FN, whose entries have bit 7 set in the name's first character) are never deleted. A comma at the end of a program line continues the list on the next line; the rest of that line may be a REMark, and whole REM lines in between are skipped.

4D67H - Close Up the Variable Tables

Copies every simple variable and every array that is kept down over those that are dropped, clears the marks, and stores the new ends of the tables at 40FBH and 40FDH. Register Pair HL is the source (the entry being looked at) and Register Pair DE the destination (where the next kept entry goes). The test at 4D89H decides for each entry: for ERASE (JR Z at 4D8DH) an unmarked entry is kept, for KEEP (JR NZ) a marked one. User functions (bit 7 of the first name character) are always kept. This routine is also reached from BASIC's statement-end clean-up (CALL at 6426H, set at 4D15H) when an error ends the statement. It ends by jumping to BASIC 6497H, which puts that CALL back to 6496H.

4DBAH - CMD"O": Build the Array Blocks

CMD"O",n,[asterisk]array(start)[,[-]array(start)...] sorts n elements of the arrays from the start subscript given (n = 0 sorts the rest of the first array). The first array is the first sort key; each array after it breaks ties left by the ones before. A minus sign before an array sorts on it in descending order. All arrays are moved together, as the columns of one table. With an asterisk before the first array, that array must be an integer array: it is filled with the element numbers of the keys (start to start+n-1) and only it is rearranged, by the keys that follow (an index sort; the keys stay where they are). A string array may be followed by (position,length) to compare only that part of each string. At most 9 arrays. The routine first builds nine 23-byte blocks at 4300H, one per array; the table "The Array Blocks at 4300H" at the top of the page gives their layout.

4F01H - The Merge Sort

The elements are merged in passes: runs of 1, 2, 4 ... elements are merged pairwise into runs twice as long, until one run holds all n. Two neighbouring runs, A and B, are merged in place. While elements are taken from run A they stay where they are; once an element of run B has been taken, every element taken goes into a buffer at 5200H-56FFH (each moved array has its own part of it). When the buffer is full or a run is used up (5087H), the rest of run A is moved up to meet what is left of run B, and the buffer is copied back in front of it. The routines called through 50EEH do one step for every array that is moved; with the index sort that is only block 1, and 5093H/5096H find the key elements from the index values. For equal keys the element of run A is taken first, so the order of equal elements is kept.

5093H - Index Sort: Find the Key Elements

Used only by the index sort (when the flag at 5102H is 01H). The index array's current element (run A's at +09H or run B's at +0DH in block 1) holds an element number; for every key block from block 2 on, the address of that element of the key array is worked out (element number times element length, plus the address of element 0 in +05H/+06H) and stored in the same field of the key's block. 5093H does it for run A (field +09H); 5096H for the field whose offset is in Register Pair BC. Without the index sort both return at once with Index Register IX unchanged; with it IX returns at 4317H, block 2, so that the compare starts with the first key.

50D7H - Take an Element: Leave It or Copy It to the Buffer

Called with Register Pair HL pointing at an element, Register Pair BC holding its length and Index Register IX on the array's block; returns with HL past the element. 50D7H copies the element to the buffer only when the buffer is in use (byte +16H of the block not 0); otherwise the element stays where it is. 50DFH always copies, except for an array whose data another block moves (bit 6 of +04H), where BASIC 65F4H only steps HL past the element.

50EEH - Do One Step for Every Moved Array

Calls the routine whose address is in Register Pair BC once for every array block in use, from block 1 up, with Index Register IX pointing at the block and Register Pair BC holding the element length. With the index sort only block 1 (the index array) is moved, so the loop stops after it. Register Pairs DE and HL are passed through to the routine unchanged.

510CH - Give an Array Its Part of the Buffer

Called through 50EEH at 4F13H, with Register Pair HL = the first free byte of the buffer at 5200H, Register Pair DE = the rows the buffer holds, Register A and Register Pair BC = the element length, and Index Register IX on the array's block.

511DH - Set Up a Pair of Runs

Called through 50EEH at 4F5DH, with Register A and Register Pair BC = the element length and Index Register IX on the array's block. Run A starts at the end of the last pair (+0FH/+10H) and holds the count at 5124H elements; run B follows it and holds the count at 5145H. The block gets run A's pointer (+09H) and end (+0BH), and run B's pointer (+0DH) and end (+0FH), which is also where the next pair starts.

5153H - Take Run B's Element

Called through 50EEH at 5040H, with Register Pair BC = the element length and Index Register IX on the array's block. Run B's element always goes into the buffer. The first time in a pair, run A's current position is recorded at +15H/+16H as the place the buffer is copied back to.

5174H - Take Run A's Element

Called through 50EEH at 5063H, with Register Pair BC = the element length and Index Register IX on the array's block. Run A's element stays where it is, or goes into the buffer if the buffer is in use, and run A's pointer moves on.

5184H - Empty the Buffer

Called through 50EEH at 5090H, with Register Pair BC = the element length and Index Register IX on the array's block. The elements of run A not yet taken (from +09H to +0BH) are moved up so that they end just before run B's pointer; run B's pointer becomes run A's new end. Then the buffer is copied back to the copy-back address (+15H/+16H), which fills exactly the gap in front of the moved elements, and the buffer is marked not in use.

51D5H - Start a Pass

Called through 50EEH at 4F35H with Index Register IX on the array's block: the first pair of runs of a pass starts at the first element sorted.