Decoded: Rogue (1980) by Toy, Arnold, Wichman
DOS version (1983) by Mel Sibony and Jon Lane
Source file: FIO.ASM
Beginner friendly, line-by-line code walkthrough by MaiZure

FIO.ASM provides file I/O operations using the DOS API

Original code:
https://britzl.github.io/roguearchive/

Original code with line numbers
http://www.maizure.org/projects/decoded-rogue/FIO_linenum.txt




1     COMMENT (vi tab stop is 8)
2     COMMENT
3     COMMENT
4     COMMENT
5     COMMENT
6     BLANK
7     Declares the start of the data segment with paragraph alignment
8     Bring in errno, with external linkage
9     End of data segment
10    BLANK
11    Declares the start of the code segment with paragraph alignment
12    The usual suspects are assumed for code and data
13    Declares the functions in this code. These are publicly available to the
      C code. Note that the assembler expects the trailing underscore, the C
	  code does not.
14    BLANK

OPEN FILE

15    Defines the open procedure
16    Saves the current stack frame
17    Starts a new stack frame
18    Grabs the first argument (file name) and puts it in DX
19    Grabs the second argument (access mode) and puts it in AL
20    Sets up the DOS API call for file open, AH = 0x3d
21    BLANK
22    Label to invoke DOS software interrupt - note that even though this is
      part of the open procedure, all of our procedures jump in at this point
	  since all of them invoke and clean up the same way
23    Stores the source index on the stack, by this convention
24    Stores the destination index on the stack.
25    Invoke software interrupt
26    If interrupt completed successfully jump to line 29. Fail fallthrough
27    Move the interrupt return value to errno
28    Set AX to all 1s
29    Clean up procedure (undo stack frame)
30    Restore destination index register
31    Restore source index register
32    Restore original base pointer
33    Ret (this is not an interrupt handler technically so no iret)
34    End procedure for
35    BLANK

CLOSE A FILE

36    Defines the close file procedure
37    Store the current stack frame
38    Create a new stack frame
39    Get the first argument (file handle)
40    Set DOS API call to file close (AH = 0x3e)
41    Jump to line 22 to invoke the actual interrupt
42    End of close procedure
43    BLANK

READ FROM A FILE

44    Defines read procedure
45    Store the stack frame
46    Create a new stack frame
47    Get the first argument (file handle)
48    Get the third argument (number of bytes to read)
49    Get the second argument (address to store read)
50    Set up DOS API call to file read (AH = 0x3f)
51    Jump to line 22 to invoke the actual interrupt
52    End of read procedure
53    BLANK

WRITE TO A FILE

54    Define the write to file procedure
55    Store the stack frame
56    Create a new stack frame
57    Get the first argument (file handle)
58    Get the third argument (size to write)
59    Get the second argument (data to write)
60    Set up for DOS API call to write to file (AH = 0x40)
61    Jump to line 22 to invoke the actual interrupt
62    End of write procedure
63    BLANK

UNLINK / DELETE A FILE

64    Define the unlink procedure (deletes a file)
65    Store the current stack frame
66    Create a new stack frame
67    Get the first argument (file handle)
68    Set up the DOS API call for unlink (delete) file
69    Jump to line 22 to invoke the actual interrupt
70    End unlink procedure
71    BLANK

CREATE A NEW FILE

72    Define the create file procedure
73    Store the current stack frame
74    Create a new stack frame
75    Get the first argument (file name)
76    Set file attributes to 0 (read-only)
77    Set up the DOS API call for create file
78    Jump to line 22 to invoke the actual interrupt
79    End create procedure
80    BLANK

SEEK WITHIN A FILE

81    Declare the lseek procedure
82    Store the current stack frame
83    Create a new stack frame
84    Get the first argument (file handle)
85    Get the second argument (low 64k position)
86    Get the third argument (high file position, always 0 in this game)
87    Get the fourth argument (file base position (start, end, etc))
88    Set up for the seek
89    Jump to line 22 to invoke the actual interrupt
90    End of seek procedure
91    BLANK
92    End of code segment
93    EOF