flexdos - FLEX Disk Operating System

---

DESCRIPTION

USER-CALLABLE SYSTEM ROUTINES

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.

Warstart 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 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 specifiation. 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 itslef, 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 Decima 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 ot 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 randoem 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 ubffer is a separator character (such as a comma), the carry bit is still cleared, but the B-register is set to zero inidcating 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 teh 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.

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:

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

• flexemu Main
• FLEX Users Manual
• Misc FLEX Utilities
• FLEX File Management System (FMS)
• File systems supported by flexemu
• FLEX Error Messages
• FLEX File Control Block (FCB)
• FLEX Memory Map
• Monitor program neumon54.hex