flexdos - FLEX Disk Operating System
DESCRIPTION
The
Disk Operating System
(DOS) forms the communication link between the user and the
File Management System.
All commands are accepted through DOS. Functions such as file
specification parsing, command argument parsing, terminal I/O, and error
reporting are all handled by DOS. The following section describe the DOS user
callable subroutines, and give examples of some possible uses.
FLEX Memory map gives an overview of memory usage of FLEX.
USER-CALLABLE SYSTEM ROUTINES
Unless specifically documented otherwise, the contents of all registers shoud
be presumed destroyed by calls to these routines. All routines, unless
otherwise indicated, should be called with a JSR instruction. In the 6809
version of FLEX the Y and U registers are preserved across all the following
routines. The A, B, and X registers should be considered changed except where
noted otherwise. Often a value or status is returned in one of these registers.
- Coldstart Entry Point $CD00 (COLDS)
-
The BOOT program loaded from the disk jumps to this address to initialize the
FLEX system. Both the Disk Operating System (DOS) portion and the
File Management System portion (FMS) of FLEX are
initialized. After initialization,
the FLEX title line is printed and the
STARTUP file
, if one exists, is loaded
and executed. This entry point is only for use by the BOOT program, not by
user programs. Indiscriminate use of the Coldstart Entry Point by user programs
could result in the destruction of the diskette. Documentation of this routine
is included here only for completeness.
- Warmstart Entry Point $CD03 (WARMS)
-
This is the main re-entry point into DOS from user programs. A JMP instruction
should be used to enter the Warmstart Entry Point. At this point, the main loop
DOS is entered. The main loop of DOS checks the Last Terminator location for
a TTYSET end-of-line character. If one is found, it is assumed that there is
another command on the line, and DOS attempts to process it. If no end-of-line
is in the Last Terminator location DOS assumes that the current command line is
finished, and looks for a new line to be input from the keyboard. If, however,
DOS was called from a user program through the
DOCMND entry point, control
will be returned to the user program when the end of a command line is reached.
- DOS Main Loop Re-entry Point $CD06 (RENTER)
-
This is a direct entry point into the DOS main loop. None of the Warmstart
initialization is performed. This entry point must be entered by a JMP
instruction. Normally, this entry point is used internally by DOS and
user-written programs should not have need to use it. For example of use, see
"Printer Driver" section for details.
- Input Character $CD09 (INCH)
- Input Character $CD0C (INCH2)
-
Each of these routines inputs one character from the keyboard, returning it to
the calling program in the A-register. The address portion of these entry
points to a routine in the Custom I/O package. They may be altered by changing
that package. The
GETCHR routine normally uses
INCH but may be instructed to
use INCH2 by setting the "Input Switch" non-zero (see flexemu(1) Memory Map).
The Users's program may change the jump vector at the
INCH address to refer to
some other input routine such as a routine to get a character from paper tape.
The INCH2 address should never be altered. The Warmstart Entry Point resets the
INCH jump vector to the same routine as INCH2 and sets the Input Switch to
zero.
RSTRIO also resets these bytes. User programs should
use the GETCHR
routine, rather than calling INCH, because INCH does not check the
TTYSET
parameters.
- Output Character $CD0F (OUTCH)
- Output Character $CD12 (OUTCH2)
-
On entry to each of these routines, the A-register should contain the character
being output. Both of these routines output the character in the A-register to
an output device. The OUTCH routine usually does the same as OUTCH2; however,
OUTCH may be changed by programs to refer to some other output routine. For
example, OUTCH may be changed to drive a line printer. OUTCH2 is never changed,
and always points to the output routine in the Custom I/O package. This
address may not be patched to refer to some other output routine. The routine
PUTCHR
calls one of these two routines, depending on the content of the
location "Output Switch".
The Warmstart Entry
Point resets the OUTCH jump vector to the same routine as OUTCH2, and sets
the Output Switch to zero.
RSTRIO
also resets these locations. User routines
should use
PUTCHR
rather than calling OUTCH or OUTCH2 directly since these
latter two do not check the
TTYSET
parameters.
- Get Character $CD15 (GETCHR)
-
preserved: B, X.
This routine gets a single character from the keyboard. The character is
returned to the calling program in the A-register. The Current Line Number
location is cleared by a call to GETCHR. Because this routine honors the
TTYSET
parameters, its use is preferred to that of
INCH
. If the location
"Input Switch" is non-zero, the routine
INCH2
will be used for input. If zero,
the byte at "File Input Address" is checked. If it is non-zero, the address
at this location is used as a File Control Block of a previously opened
input file and a character is retrieved from the file. If zero, a character
is retrieved via the
INCH
routine.
- Put Character $CD18 (PUTCHR)
-
preserved: B, X.
This routine outputs a character to a
device, honoring all of the
TTYSET
parameters. On entry, the character should
be in the A-register. If the
"Special I/O Flag"
is zero, the column count is checked, and a new line is started if the
current line is full. If an ACIA is being used to control the monitor terminal,
it is checked for a
TTYSET
Escape Character having been typed. If so, output
will pause at the end of the current line. If the location
is non-zero, the routine
"Output Switch"
is used to send the character. If zero, the
location File Output Address is checked. If it is non-zero the contents of
this location is used as a address of a File Control Block of a previously
opened for write file, and the character is written to the file. If zero,
the routine
OUTCH2
is called to process the character. Normally,
OUTCH
sends
the character to the terminal. The user program may, however, change the
address portion of the
OUTCH
entry point to go to another character output
routine.
- Input into Line Buffer $CD1B (INBUFF)
-
This routine inputs a line from the keyboard into the Line Buffer. The
TTYSET
Backspace and Delete character are checked and processed if encountered.
All other control characters except RETURN and LINE FEED, are ignored. The
RETURN is placed in the buffer at the end of the line. A LINE FEED is entered
into the buffer as a space character but is echoed back to the terminal as
a Carriage Return and Line Feed pair for continuation of the text on a new
line. At most, 128 characters may be entered on the line, including the
final RETURN. If more are entered, only the first 127 are kept, the RETURN
being the 128th. On exit, the Line Buffer Pointer is pointing to the first
character in the Line Buffer. Caution: The command line entered from the
keyboard is kept in the Line Buffer. Calling
INBUFF
from a user program will
destroy the command line, including all unprocessed commands on the same line.
Using
INBUFF
and the Line Buffer for other than DOS commands may result in
unpredictable side-effects.
- Print String $CD1E (PSTRNG)
-
preserved: B.
This routine is similar to the PDATA routine in SWTBUG and DISKBUG. On entry,
the X-register should contain the address of the first character of the string
to be printed. The string must end with an ASCII EOT character ($04). This
routine honors all of the
TTYSET
conventions when printing the string. A
carriage return and line feed are output before the string.
- Classify character $CD21 (CLASS)
-
preserved: All registers.
This routine is used for testing if a character is alphanumeric (i. e. a
letter or a number). On entry, the character should be in the A-register. If
the character is alphanumeric, the routine returns with the carry flag cleared.
If the character is not alphanumeric, the carry flag is set and the character
is stored in the Last Terminator location.
- Print Carriage Return and Line Feed $CD24 (PCRLF)
-
preserved: X.
In addition to printing a carriage return and line feed, this routine checks
and honors several
TTYSET
conditions. On entry, this routine checks for a
TTYSET
Escape Character having been entered while the previous line was being
printed. If so, the routine waits for another
TTYSET
Escape Character or a
RETURN to be typed. If a RETURN was entered, the routine clears the Last
Terminator location so as to ignore any commands remaining in the command line,
and then jumps to the address contained in the Escape Return Register location.
Unless changed by the user's program, this address is that of the Warmstart
Entry Point. If, instead of a RETURN, another
TTYSET
Escape Character was
typed, or it wasn't necessary to wait for one, the Current Line Number is
checked. If the last line of the page has been printed and the
TTYSET
Pause feature is enabled, the routine waits for a RETURN or a
TTYSET
Escape Character, as above. Note that all pausing is done before the
carriage return and line feed are printed. The carriage return and line feed
are now printed, followed by the number of nulls specified by the
Null Count. If the end
of the page was encountered on entry to this routine, an "eject" is
performed by issuing additional carriage return, line feeds, and nulls until
the total number of blank lines is that specified in the
Eject Count.
- Get Next Buffer Character $CD27 (NXTCH)
-
preserved: B, X.
The character in location Current Character is placed in location Previous
Character. The character to which the Line Buffer Pointer points is taken
from the Line Buffer and saved in the Current Character location. Multiple
spaces are skipped so that a string of spaces looks no different than a single
space. The line Buffer Pointer is advanced to point to the next character
unless the character just fetched was a RETURN or
TTYSET
End-Of-Line character.
Thus, once an end-of-line character or RETURN is encountered, additional
calls to NXTCH will continue to return the same
end-of-line character or RETURN. NXTCH cannot be used to cross into the next
command in the buffer. NXTCH exits through the routine
CLASS
, automatically classifying the character. On exit, the character is in the
A-register, the carry is clear if the character is aphanumeric.
- Restore I/O Vector $CD2A (RSTRIO)
-
preserved: A, B.
This routine forces the OUTCH jump vector to point to
the same routine as does the OUTCH2 vector. The Output
Switch location and the Input Switch location are set to zero. The
INCH jump vector is reset to point to the same address
as the
INCH2
vector is reset to point to the same
address as the
INCH2
vector. Both the File Input Address and the File
Output Address are set to zero.
- Get File Specification $CD2D (GETFIL)
-
preserved: X.
On entry to this routine, the X-register must contain the address of a
File Control Block (FCB), and the Line Buffer
Pointer must be pointing to the
first character of a file specification in the Line Buffer. This routine will
parse the file specification, storing the various components in the FCB to
which the X-register points. If a drive number was not specified in the file
specification, the working drive number will be used. On exit, the carry bit
will be clear if no error was detected in processing the file specification.
The carry bit will be set if there was a format error int the file
specification. If no extension was specified in the file specification, none
is stored. The calling program should set the default extension desired after
GETFIL has been called by using the
SETEXT
routine. The Line Buffer Pointer
is left pointing to the character immediately beyond the separator, unless
the separator is a carriage return or End of Line character. If an error was
detected, Error number 21 is stored in the error status byte of the FCB.
- File Loader $CD30 (LOAD)
-
On entry, the system
File Control Block (at $C840) must contain the name of
a file which has been opened for binary reading. This routine is used to load
binary files only, not text files. The file is read from the disk and stored
in memory, normally at the load addresses specified in the binary file itself.
It is possible to load a binary file into a different memory area by using
the Loader Address Offset locations. The 16-bit value in the Loader Address
Offset locations is added to the addresses read from the binary file. Any
carry generated out of the most significant bit of the address is lost. The
transfer address, if any is encountered, is not modified by the Loader Address
Offset. Note that the setting of a value in the Loader Address Offset does
not act as a program relocator in that it does not change any addresses in
the program itself, merely the location of the program in memory. If the file
is to be loaded without an offset, be certain to clear the Loader Address
Offset locations before calling this routine. On exit, the Transfer Address
Flag is zero if no transfer address was found. This flag is non-zero if a
transfer address record was encountered in the binary file, and the Transfer
Address locations contain the last transfer address encountered. The disk
file is closed on exit. If a disk error is encountered, an error message is
issued and control is returned to DOS at the Warmstart Entry Point.
- Set Extension $CD33 (SETEXT)
-
preserved: X.
On entry, the X-register should contain the address of the
FCB
into which the
default extension is to be stored if there is not an extension already in the
FCB. The A-register, on entry, should contain a numeric code indicating what
the default extension is to be. The numeric codes are described below. If
there is already an extension in the FCB (possibly stored there by a call to
GETFIL), this routine returns to the calling program
immediately. If there is
no extension in the FCB, the extension indicated by the numeric code in the
A-register is placed in the FCB File Extension area. The legal codes are:
Code | Extension |
0 | BIN |
1 | TXT |
2 | CMD |
3 | BAS |
4 | SYS |
5 | BAK |
6 | SCR |
7 | DAT |
8 | BAC |
9 | DIR |
10 | PRT |
11 | OUT |
Any values other than those above are ignored, the routine returning without
storing any extensions.
- Add B-register to X-register $CD36 (ADDBX)
-
The contents of the B-register is added to the contents of the X-register. This
routine is here for compatibility with 6800 FLEX.
- Output Decimal Number $CD39 (OUTDEC)
-
On entry, the X-register contains the address of the most significant byte of a
16-bit (2 byte), unsigned, binary number. The B-register, on entry, should
contain a space suppression flag. The number will be printed as a decimal
number with leading zeroes suppressed. If the B-register was non-zero on entry,
spaces will be substituted for the leading zeroes. If the B-register is zero
on entry, printing of the number will start with the first non-zero digit.
- Output Hexadecimal Number $CD3C (OUTHEX)
-
preserved: B, X.
On entry, the X-register contains the address of a single binary byte. The
byte on which the X-register points is printed as 2 hexadecimal digits.
- Report Error $CD3F (RPTERR)
-
On entry ot this routine, the X-register contains the address of a File Control
Block in which the Error Status Byte is non-zero. The error code in the
FCB
is stored by this routine in the Error Type location. A call to the routine
RSTRIO
is made and location Error Vector is checked. If this location is zero, the
file ERRORS.SYS is opened for random read. If this location is non-zero, it
is assumed to be an address pointing to an ASCII string (containing any
necessary null pad characters) of a legal File name plus extension (string
should be 11 characters long). This user provided file is then opened for
random read. The error number is used in a calculation to determine the
record number and offset of the appropriate error string message in the file.
Each error message string is 63 characters in length, thus allowing 4
messages per sector. If the string is found, it is printed on the terminal.
If the string is not found (due to too large of error number being encountered)
or if the error file itself was not located on the disk, the error number is
reported to the monitor terminal as part of the message:
DISK ERROR #nnn
Where "nnn" is the error number being reported. A description of the error
numbers is given in FLEX Error Messages.
- Get Hexadecimal Number $CD42 (GETHEX)
-
This routine gets a hexadecimal number from the Line Buffer. On entry, the
Line Buffer Pointer must point to the first character of the number in the
Line Buffer. On exit, the carry bit is cleared if a valid number was found,
the B-register is set non-zero, and the X-register contains the value of the
number. The Line Buffer Pointer is left pointing to the character immediately
following the separator character, unless that character is a carriage return
or End of Line. If the first character examined in the Line Buffer is a
separator character (such as a comma), the carry bit is still cleared, but
the B-register is set to zero indicating that no actual number was found. In
this case, the value returned in the X-register is zero. If a non-hexadecimal
character is found while processing the number, characters in the Line Buffer
are skipped until a separator character is found, then the routine returns
to the caller with the carry bit set. The number in the Line Buffer may be of
any length, but the value is truncated to between 0 and $FFFF inclusive.
- Output Headecimal Address $CD45 (OUTADR)
-
On entry, the X-register contains the address of the most significant byte of
a 2 byte hex value. The bytes to which the X register points are printed as
4 hexadecimal digits.
- Input Decimal Number $CD48 (INDEC)
-
This routine gets an unsigned decimal number from the Line Buffer. On entry,
the Line Buffer Pointer must point to the first character of the number in the
Line Buffer. On exit, the carry bit is cleared if a valid number was found, the
B-register is set non-zero, and the X-register contains the binary value of
the number, The Line Buffer Pointer is left pointing as described in the
routine
GETHEX
. If the first character examined in the buffer is a separator
character (such as a comma), the carry bit is still cleared, but the B-register
is set to zero indicating that no actual number was found. In this case, the
number returned in X is zero. The number in the Line Buffer may be of any
length but the result is truncated to 16 bit precision.
- Call DOS as a Subroutine $CD4B (DOCMND)
-
This entry point allows a user-written program to pass a command string to DOS
for processing, and have DOS return control to the user program on completion
of the commands. The command string must be placed in the Line Buffer by the
user program, and the Line Buffer Pointer must be pointing to the first
character of the parameters and commands in the Line Buffer. The command string
must terminate with a RETURN character (hex $0D). After the commands have been
processed, DOS will return control to the user's program with the B-register
containing any error code received from the File Management System. The
B-register will be zero if no programs which may destroy the user program in
memory. An example of a use of this feature of DOS is that of a program
wanting to save a portion of memory as a binary file on the disk. The program
could build a
SAVE command in the Line Buffer with the
desired file name and parameters, and call the
DOCMND entry point. On return, the memory will have been saved on the disk.
- Check Terminal Input Status $CD4E (STAT)
-
This routine may be called to check the status of the terminal input device
(to see if a character has been typed on the keyboard). If a character has
been hit, the Z condition code will be cleared on return (a not-equal
condition). If no character has been hit, the Z condition code will be set (an
equal condition). No registers, other than the CC-register, are altered.
USER-WRITTEN COMMANDS
The programmer may write his own commands for DOS. These commands may be
either disk-resident as disk files with a CMD extension, or they may be
memory-resident in either RAM or ROM.
MEMORY-RESIDENT COMMANDS:
A memory-resident command is a program, already in memory, to which DOS will
transfer when the proper command is entered from the keyboard. The command
which invokes the program, and the entry-point of the program, are stored in
a User Command Table created by the programmer in memory. Each entry in the
User Command Table has the following format:
FCC | 'command' | (Name that will invoke the program) |
FCB | 0 | |
FDB | entry address | (The entry address of the program) |
The entire table is ended by a zero byte. For example, the following table
contains the commands DEBUG (entry at $3000) and PUNT (entry at $3200):
FCC | 'DEBUG' |
FCB | 0 |
FDB | $3000 |
FCC | 'PUNT' |
FCB | 0 |
FDB | $3200 |
FCB | 0 | End of Command table |
The address of the User Command Table is made known to DOS by storing it in the
User Command Table Address locations (see).
The User Command Table is searched before the disk directory, but after DOS's
own command table is searched. The DOS command table contains only the GET and
MON commands. Therefore, the user may not define his own GET and MON commands.
Since the User Command Table is searched before the disk directory, the
programmer may have commands with the same name as those on the disk. However,
in this case, the commands on the disk will never be executed while the User
Command Table is known to DOS. The User Command Table may be deactivated by
clearing the User Command Table Address locations.
DISK-RESIDENT COMMANDS:
A disk-resident command is an assembled program, with a transfer address, which
has been saved on the disk with a CMD extension.
Disk commands, when loaded into memory, may reside anywhere in the User RAM
Area; the address is determined at assembly time by using an ORG statement.
Most commands may be assembled to run in the
Utility Command Space.
Most of the commands supplied with FLEX run in the Utility Command Space.
For this reason, the
SAVE command
cannot be used to save information which is
in the Utility Command Space or System FCB space as this information would be
destroyed when the
SAVE command
command is loaded. The
SAVE.LOW command
command is to be used
in this case. The
SAVE.LOW command
command loads into memory at location $100 and
allows the saving of programs in the $C100 region.
The System FCB area is used to load all commands from the disk. Commands
written to run in the Utility Command Space must not overflow into the
System FCB area. Once loaded, the command itself may use the System FCB
area for scratch or as an FCB for its own disk I/O. Look for an example in
FLEX File Management System.
SEE ALSO
Documents on the behalf of the FLEX User Group
Other Documents
Related Links