BDOS interrupts - INT E0h

The following is a guide to the BDOS interrupts provided by DOS Plus 2.1 in the 512. These calls are also referred to variously as CP/M calls or DOS Plus system calls. In all cases they are made by calling DOS interrupt 0E0h (224 decimal), with the required BDOS function always held in register CL. In all cases the call is immediately passed to the kernel by the DOS emulator, for execution.

By convention, in DOS Plus and CP/M programming reference manuals, the call function and parameters are often given in decimal. Because all 80186 register and memory values are in hex, all debuggers and monitors report or display in hex which is used exclusively here.

As BDOS calls access the kernel by-passing the DOS emulator, they conform to CP/M call standards which use different register assignments to DOS calls. BDOS cans use the general register scheme shown below.

Parameter Type Register

On entry Function code CL

Byte parameter
or DL

Word parameter
or DX

Memory address Segment:
Offset: DS
DX

On exit Byte returned
or AL

Word returned
or AX

Memory address Segment
Offset ES
AX

Word return EX (usually the same as AX)

Error code if failed CX (Zero if successful)

Return code AH

If a call is successful AL and CX return zero. In the event of a failure, AL normally contains 0FFh and AH may contain a reason code, particularly for filing system operations. In addition CX is used to return error codes, which also indicate the reason for failure if the cause is one of the following:

Value	Meaning
 2	Illegal function
 3	Insufficient memory
 4	Illegal system flag number
 5	Flag overrun
 6	Flag underrun
0Ch	No free process environments
12h	No available memory descriptors
17h	Illegal drive number
18h	Illegal filename
19h	Illegal file type
1Dh	Error reading file
1Eh	Could not open file
20h	Caller is not owner of resource (illegal access)
21h	No code group descriptor in command header
26h	Illegal password
29h	Error during load time fixups
2Ah	Error loading RSX module
2Bh	Illegal parameter
2Eh	8087 in use
2Fh	No tick interrupt

As can be seen from this general outline of BDOS calls, register contents are more often changed by the call than in DOS calls, therefore more care should be exercised in protecting such data as must be retained when these BDOS calls are used. In addition, BDOS calls tend to operate at a lower level and therefore are slightly more complex to implement than their 'sanitised' MSDOS counterparts.

For all that, BDOS calls and CP/M in general offer facilities which cannot be matched by DOS calls, including those calls provided in later versions. As a result, judicious use of BDOS calls can considerably extend the range of facilities available in DOS Plus programs over those provided by MSDOS or PCDOS calls if exploited to the full.

The following code is an example of a 'BDOS call only' program termination similar in purpose to that shown in the preceding appendix, which used DOS INT 21h function 4Ch. Contrast this example with the DOS program code: in this case two calls are used. The first sets the program return code (which is optional in CP/M), while the second call invokes the program terminate handler routine.

The code example shown here assumes that the value, held in the memory variable Return_Code, will have been set elsewhere in the program during execution if the program was unsuccessful and the final return code is to be other than zero (the default value).

; constant equates
Prog_code		equ 06ch	; BDOS set return code
Prog_exit		equ 08fh	; BDOS terminate call
BDOS			equ 0e0h	; BDOS call interrupt No
CSEG
	ORG 0100
start:
; program code follows here
	.........
	.........
	.........
set_result:				; Sets up program return code
	mov dx, [Return_code] W		; Set actual return code value
	mov cl, Prog_code		; set up BDOS function 06Ch
	int BDOS_Call			; INT 0E0h to set return code
exit:					; Final exit point
	mov dl, 0			; Free all memory
	mov cl, Prog_exit		; set up terminate process
	int BDOS			; and exit
; variable data
Return_Code	dw ?			; Default zero means OK
CODE ends
END

The following lists show the complete range of BDOS calls which are valid for the 512. Although these calls can be mixed with DOS interrupt calls in COM, CMD and EXE programs, it should be remembered that only BDOS calls are valid for (the portions of) programs destined to enter the background, or which are to be converted to RSXs.

Function 00h: Terminate program

Action: Terminates the calling process and returns control to the system.

On entry: CL = 0
DL = Abort code:
0 = Release all memory
1 = Retain memory allocation

Returns: Nothing

Notes: This call terminates program execution and optionally releases or retains the memory allocated to the program and its buffers.

If a two-byte program return code is to be set, a prior call to function 6Ch should be made.

This call is exactly the same as function 8Fh.

Function 01h: Read a character

Action: This call reads the next character from the logical console input device 'CONIN'.

On entry: CL = 1

Returns: AL = 8 bit data, BL = AL

Notes: If the character read is a graphics character, a carriage return, line feed or backspace, it is echoed to the console. All other characters are read but not echoed to CONOUT. If the console is in default mode the system intercepts and actions CTRL-C, CTRL-P, CTRL-Q and CTRL-S.

If printer output is active (CTRL-P), characters are also sent to the list device, PRN. if no input character is ready the call waits until a character is returned.

Function 02h: Write a character

Action: Outputs a character to the standard output device, CONOUT.

On entry: CL = 2, DL = 8-bit data

Returns: Nothing

Notes: CTRL-I (tabs) are expanded. If the console is in default mode CTRL-S and CTRL-Q are actioned and characters are sent to the list device if printer output (CTRL-P) is active, otherwise system action is determined by the bits in the console status setting (function 6Dh).

Function 03h: Auxiliary input

Action: Reads a character from the AUXIN device.

On entry: CL = 3

Returns: AL = 8 bit data input, BL = AL

Notes: Control does not return until a character is read.

Function 04h: Auxiliary output

Action: Outputs a character to the AUXOUT device.

On entry: CL = 4, AL = 8 bit data

Returns: Nothing

Notes: Control does not return to the calling routine if the device is ready for output.

Function 05h: Write char to the list device

Action: Sends a character to the current list device, PRN.

On entry: CL = 5, DL = 8 bit data

Returns: Nothing

Notes: If the printer is busy this call waits until the data is sent.

Function 06h: Direct (Raw) console I/0

Action: Permits the calling process to read or write unedited and unmodified console data or to check console status.

On entry: CL = 6

DL = function requested: 0FFh -Get Input/status, or
0FEh - Get status, or
0FDh - Get input, or
8 bit character to be output

Returns: If output: Nothing

If get input status. AL = 0 if no character or
AL = Character input

If get status: AL = 0 if no character
AL = 0FFh Character ready

If input: AL = 8 bit data, BL = AL

Notes: On entry, if DL = 0FFh, either the character entered is returned, or AL is set to zero to indicate no input ready (i.e. this call does not wait for input).
If DL = 0FEh on entry, AL returns 0 for no input, or for input waiting. The input character is not returned until a call is made with DL = 0FDh.

If the call is made with DL = 0FDh and no character is ready the system waits for input.

Function 07h: Auxiliary input status

Action: Checks the input status of the AUXIN device

On entry: CL = 7

Returns: AL = auxiliary input status: 0 if character not ready
0FFh if character ready

BL = AL

Notes: This call does not read the input data, only the status.

Function 08h: Auxiliary output status

Action: Checks the input status of the AUXOUT device

On entry: CL = 8

Returns: AL = auxiliary output status: 0 if not ready for output
0FFh if ready for output

BL = AL

Notes: Output is not performed by this call, only the status is checked.

Function 09h: String output

Action: Writes a string to the output console, CONOUT.

On entry: CL = 9, DS:DX = segment:offset of string

Returns: Nothing

Notes: The string must be terminated by the default delimiter character, normally ,ドル (24h), which is not transmitted. The default delimiter can be set to any character by a call to function 6Eh. Any ASCII codes can be embedded within the string, including control characters, which are actioned.

Function 0Ah: Read an edited line

Action: Reads an edited line from the input device CONIN, up to and including an ASCII carriage return (0Dh), placing the data in a user-defined buffer.

On entry: CL = 0Ah, DS:DX = segment:offset of input buffer

Returns: Nothing

Notes: The first byte of the buffer specifies the maximum number of characters it can hold (1 to 255). This value must be supplied by the user. The second and third bytes of the buffer are set to the number of characters actually read, excluding the terminating RETURN. If the buffer fills to one less than its maximum size, the bell is sounded and subsequent input is ignored.

If DX is set to 0FFFFh on entry the default DMA buffer is used, any other value points to a specified buffer offset.

Function 0Bh: Get console status

Action: Checks whether or not a character is available from the input console device, CONIN.

On entry: CL = 0Bh

Returns: AL 0 if no character available
AL = 1 if character available
BL = AL

Notes: If console mode bits 0 and 3 are set this call returns AL = 1 only if CTRL-C has been typed, all other characters are ignored. See function 6Dh.

Function 0Ch: Get BDOS version number

Action: Returns the BDOS version number as a two-byte value.

On entry: CL = 0Ch

Returns: AX = BDOS version number, as follows:
AL high nibble - version number
AL low nibble - revision number
AH high nibble - CPU type
AH low nibble - 0 for CP/M(86), 1 for DOS Plus
BX = AX

Notes: In DOS Plus 2.1, the AX value returned is 01080h.

Function 0Dh: Reset all drives

Action: Restores the status of all logged-in drives to their default settings.

On entry: CL = 0Dh

Returns: Nothing

Notes: This call does not update all files or disc directories. If a program fails to properly write and close any open files before issuing this call, data may be lost or directory entries may be inconsistent with the files.

All disc drives are set to read/write, the default drive is set to A: and the default DMA address is set to 080h relative to the current DMA segment address (i.e, the default in the PSP).

Function 0Eh: Set default drive

Action: Sets the specified drive to the default drive.

On entry: CL = 0Eh, DL = drive number (A: = 0, B: = 1 etc)

Returns: AL = Return code, AH = 0 or physical error code (1 or 4)
BX = AX

Notes: The possible values for DL on entry are 0 through 0Fh. If the selected drive is in the reset state, it is automatically logged in.

If an error occurs and the filing system is in default error mode, a message is displayed and the call terminates, otherwise AL is set to 0FFh and AH contains the error code.

Function 0Fh: Open a file for record access

Action: Opens a file for access and activates the FCB for that file for the current user number.

On entry: CL = 0FH, DS:DX = Segment:offset of the file control block (FCB)

Returns: If successful: AH = 0, AL = directory code
If failed: AH = physical error code (1,4,7 or 9)
AL = FFh (file not found)
BX = AX

Notes: If the call is successful the file's directory information is copied to the FCB. If the file is password protected in read mode, the password is placed in the first 8 bytes of the current DMA, or must have been previously set up as the default password. if the file is password protected in write mode and the correct password was not supplied in the DMA, interface attribute F7 is set to one (i.e. write protected).

If a file is opened for write access the access date and time stamps are updated, if applicable. If there is no physical error but the file does not exist, AL is set to 0FFh and AH is set to zero.

Function 10h: Close file

Action: Closes a file and updates the directory if the file has been modified.

On entry: CL = 10h, DS:DX = Segment offset of the FCB for the file.

F5 interface attribute : 0 = permanent close
1 = partial close

Returns: If successful: AH = 0Ah = directory code

If failed: AH = physical error code (1,2 or 4)
AL = FFh (physical error), BX = AX

Notes: This call may only be used after a file has been successfully opened and an FCB created. A partial close causes the system to update the directory, but the file remains open for further access. If the FCB has not been altered the directory is not updated. If there is no physical error but the file does not exist, AL is set to 0FFh and AH is set to zero.

Function 11h: Search for first matching file

Action: Search for a specified filename in the current directory of the current drive.

On entry: CL = 11h, DS:DX = Segment:offset of the FCB

F5 interface attribute : 0 = permanent close
1 = partial close

Returns: If successful: AH = 0Ah = directory code

If failed: AH = physical or extended error code (1 or 4)
AL = FFh (physical error), BX = AX

Notes: The calling program must set the drive field, the filename field and the file type field in the Icts~ before the call. The extent field must be set to zero.

The '?' wildcard is permitted in any filename character position or in the file type specification. If the '?' wildcard is placed in the drive field, the current drive and the current user number are searched. if wildcards are specified in the file's name or type, the first matching name is returned.

If the call is successful, the file's directory data is transferred to the FCB. If there is no physical error but the file does not exist, AL is set to 0FFh and AH is set to zero.

Function 12h: Find next file

Action: Searches the current directory in the current drive for the next matching filename after a previously successful call to function 11h.

On entry: CL = 12h

Returns: If successful: AH = 0, AL = directory code
If failed: AH = physical or extended error code (1 or 4)
AL = FFh (physical error), BX = AX

Notes: There must be no other disc related calls between the call to function 11h and this call, as the FCB is not re-specified in this call. otherwise as for function 11h.

Function 13h: Delete a file

Action: Deletes all matching files from the current directory and/or all matching XFCBs.

On entry: CL = 13h, DS:DX = Segment:offset of the FCB

F5 interface attribute :0 = standard delete
1 = delete only FCBs

Returns: If successful: AH = 0, AL = directory code
If failed: AH = physical or extended error code (1 or 4)
AL = FFh (physical error), BX = AX

Notes: The '?' wildcard is permitted. If more than one match occurs all matched items will be deleted. The file names and file types must be specified in the FCB prior to this call. If any of the files are password protected, the correct password must also have been set up.

If there is no physical error but the filename and type are not matched AL is set to 0FFh and AH is set to zero. For all operations, if any matching file fails the password check or is set to read only, the file (and its FCB) are not deleted.

Function 14h: Read records sequentially

Action: Reads the next sequential one to 128 logical 128 byte records from a file into memory beginning at the current DMA address. The system multisector count determines the number of records, defaulting to one if not set.

On entry: CL = 14h, DS:DX = Segment:offset of previously opened FCB

Returns: AL = ret. code, AH = physical error or record count, BX = AX

Notes: The call can only be made for a file previously successfully opened for input. If the read is to start from the beginning of a file, the CR field in the FCB must be set to zero.

On reading the CR field is updated to the next record position. If the CR field overflows, the system automatically opens the next extent and resets CR to zero for the next read operation. Codes of 1, 9 or 0Ah may be returned on physical error.

Function 15h: Write records sequentially

Action: Writes the next sequential one to 128 logical 128 byte records to a file from memory beginning at the current DMA address. The system multisector count determines the number of records, defaulting to one if not set.

On entry: CL = 15h, DS:DX = Segment:offset of previously opened FCB

Returns: AL = ret. code, AH = physical error or record count. BX = AX

Notes: The call can only be made for a file previously successfully opened for output. If the write is to start from the beginning of a file, the CR field in the FCB must be set to zero.

On writing, the CR field is updated to the next record position. If the CR field overflows, the system automatically opens the next extent and resets CR to zero for the next write operation. Codes of 1, 2, 9 or 0Ah are returned on physical error.

Function 16h: Create a file entry

Action: Creates a new entry in the current directory for the named file for the current user number and activates the FCB for read/write access.

On entry: CL = 16h, DS:DX = Segment:offset of unopened FCB
F6 interface attribute :0 = no password required
1 = password as set in DMA

Returns: AH = 0, AL = 0
If failed: AH = physical or ext. error code (1,2.4,8 or 9)
AL = FFh (physical error), BX = AX

Notes: The calling program must initialise the DR field, the F1 through F8 filename fields, the T1 through T3 file type fields and the extent field must be set to zero. The CR field must be set to zero, prior to writing if records are to be written sequentially from the beginning of the file.

If the file password is to be used, F6 is set to one and the password must be placed in the first eight bytes of the DMA buffer and byte nine of the DMA buffer set to password mode. A new file entry in the FCB is created and an extended FCB is created if password mode is set on a successful call. An file attributes are set to zero.

If there is no physical error but AL is returned as there is no space in the directory.

Function 17h: Rename a file

Action: Renames a matching file

On entry: CL =17h, DS:DX = Segment:offset of FCB
bytes 0 - 16 = old filename
bytes 17 - 27 = new file name
bytes 0 to 7 of DMA = password (if required)

Returns: If successful: AH = 0, AL = 0
If failed. AH = physical or ext. error code (1-4,7,8 or 9)
AL = FFh (physical error), BX = AX

Notes: The calling program must set the DR field, the F1 through F8 filename fields and the T1 through T3 file type fields to match the old filename in the DMA buffer and the old and new filenames in the FCB as shown.

If the file is password protected, the password must be placed in the first eight bytes of the correct DMA buffer, or the password must have been previously set as the default password.
If there is no physical error but AL is returned as 0FFh, the named old file does not exist.

Function 18h: Return 'Login Vector' for all logged in drives

Action: Returns the bit map of all logged-in drives

On entry: CL = 18h

Returns: AX = Login vector, BX = AX

Notes: The login vector is a 16 bit value which shows the current drives known to the system. Bit zero corresponds to drive A:, bit 1 to drive B: and so on up to 0Fh which is floating drive P:.

Each bit which is set to one represents a currently logged-in drive. A logged-in drive has had its directory read into memory and its allocation vectors built. A drive can be logged-in explicitly by a call to function 0Eh, or implicitly by a system or manual file operation which requires access to the drive.

Function 19h: Return the default drive ID

Action: Returns number of the currently selected default drive

On entry: CL = 19h

Returns: AL = drive number (0 = A:, 1 = B: etc), BL = AL

Notes: None

Function 1Ah: Set DMA buffer offset address

Action: Specifies the memory area to be used for subsequent FCB operations. (See also function 33h)

On entry: CL = 1Ah, DX = offset of DMA

Returns: Nothing

Notes: If this function is not used by a program, the DMA address defaults to a 128 byte buffer in the PSP at 080h, the area used to hold the original command tail, which will then be destroyed by any disc activity. In general it is the programmer's responsibility to ensure that the DMA is large enough for any relevant disc operation.

This function should be called before using any disc access functions if the command tail is to be preserved.

Function 1Bh: Get address of disc allocation vectors

Action: Returns the base of the allocation vector for the currently selected drive

On entry: CL = 1Bh

Returns: ES:AX = Segment:offset of allocation vector, BX = AX

Notes: The bits set to one in the allocation vector denote allocated blocks, zero denotes unallocated. The high order bit in the first byte corresponds to block zero. To ascertain the amount of free space remaining on a disc use function 2Eh.

Function 1Ch: Set the default drive to read only

Action: Sets the current drive to read only

On entry: CL = 1Ch

Returns: AL = 0 if successful, AL = 0FFh if failed

Notes: Setting a drive to read-only prevents all updates to that drive until the status is changed.

Caution: Note that, although this call is grouped with drive functions, it really acts on the current disc in the current drive. That is to say, the setting is not permanent and can be amended by simply changing the disc and issuing any disc access command, including a manual 'DIR'.

Function 1Dh: Get Read-Only drive vectors

Action: Returns the bit map of read only drives

On entry: CL = 1Dh

Returns: AX = read only vector, BX = AX

Notes: The call returns a 16 bit value in AX with bits set which correspond to drives currently set to read only. Bit zero corresponds to drive A:, bit 2 to drive B: and so on up to 0Fh which is floating drive P:.

Function 1Eh: Set file attributes

Action: Modifies a file's attributes and optionally sets its last record byte count.

On entry: CL = 1Eh, DS:DX = Segment:offset of FCB

F6 interface attribute: 0 = do not set byte count
1 = set last record byte count

Returns: If successful: AL = 0, AH = 0

If failed: AL = return code, AH = physical error (1, 2, 4, 7 or 9)

Notes: If the file is password protected, the correct password must have been placed in the DMA buffer, or defined as the default password.

Function 1Fh: Get default disc DPB address

Action: Returns the address of the BIOS resident disc parameter block address for the current drive.

On entry: 1Fh

Returns: ES:AX = Segment:offset of DPB address AX = FFFFh if error,BX = AX

Notes: The DPB contains the information concerning the actual physical characteristics of the logical drive. The contents of the DPB, therefore, may change when media is changed.

Function 20h: Get User current user number

Action: Returns current user number for CP/M media.

On entry: CL = 20h, DL = 00h to 0Fh (Set user) or FFh (get user)

Returns: AL = current user number (if get user), BL = AL

Notes: The user number is the method used in CP/M to separate files into exclusive groups, rather than directories. Files can be copied between users by means of PIP.

Function 21h: Read random records

Action: Reads a selected record from an open file.

On entry: CL = 21h
DS:DX = Segment:offset of previously opened FCB

Returns: AL = Return code
AH = Physical error or record count, BX = AX

Notes: The record is read into memory at the DMA address, the record number being indicated by the settings of the random record field in the FCB. The record number can range between zero and 262,143.

If a physical error is encountered AH contains the actual number of records read before the failure.

The file may be read sequentially after this call, but the current record field in the FCB is not advanced by the function, therefore a switch to sequential access will re-read the same record if the CR field is not changed.

Function 22h: Write random records

Action: Writes a selected record to an open file.

On entry: CL = 22h
DS:DX = Segment:offset of previously opened FCB

Returns: AL = 0 return code
AH = physical error (2, 3, 5, 6 or Ah) or record count
BX = AX

Notes: The record is written from the DMA address, the record number being indicated by the settings of the random record field in the FCB. The record number can range between zero and 262,143.
If a physical error is encountered, AH contains the actual number of records read before the failure.
The file may be written sequentially after this call, but the current record field in the FCB is not advanced by the function, therefore a switch to sequential access will re write the same record if the CR field is not changed.
However, the logical extent and the current record values for the file are updated by the call.

Function 23h: Returns the size of a file

Action: Returns the highest record number plus one of the specified file.

On entry: CL = 23h
DS:DX = Segment:offset of opened FCB

Returns: If successful: AL = if file found, AH = 0 if no error

If failed: AL = 0FFh - file not found or physical error
AH = physical or extended error code

BX = AX

Notes: Before using this call you must set the drive field, filename and filetype in the referenced FCB.

If the file has been written exclusively in sequential mode the returned value is the same as the physical number of records in the file plus one. Note, though, that if the file has been written randomly, the record number sequence may well contain gaps. In this case the returned value will not give an accurate indication of the number of records in the file, but instead it gives the logical file size as a potential record count.

Function 24h: Set random record number

Action: Sets the random record field of an FCB to correspond to the current file position as reached by previous sequential access.

On entry: CL = 24h, DS:DX = Segment:offset of previously opened FCB

Returns: Nothing.
The random record field in the FCB is updated

Notes: This function is used to change from sequential to random I/O file access.

Function 25h: Reset the specified drives

Action: Resets to the default state the specified drive(s).

On entry: CL = 25h, DX = Drive vector

Returns: Nothing

Notes: The system resets the drives specified in the 16-bit value in register DX. Bit zero corresponds to drive A:, bit 1 to drive B. and so on. For each bit set on, the corresponding drive is reset to the login state.

Function 26h: Unallocated

Function 27h: Free specified drives

Action: None in DOS Plus.

On entry: CL = 27h, DX = Drive vector

Returns: AL = 0

Notes: This call is non-functional in DOS Plus. If used it always returns zero in AL.

Function 28h: Random block write

Action: Writes one or more sequential records to an open file starting at the file's current record position.

On entry: CL = 28h
DS:DX = Segment:offset of previously opened FCB

Returns: If successful: AL = Ah = Record count

If failed: AL = Return code, AH = Physical error

Notes: This call is similar to function 22h, with the exception that, before writing to a previously unallocated data block, the new block is first filled with zeros. These zeros then can be used to identify unwritten (i.e. non-existent) random record positions within the file.

Functions 29h to 2Bh: Unallocated

Function 2Ch: Set the system multi-sector count

Action: Sets the system multi-sector count for subsequent calls to functions 14h, 15h, 21h, 22h and 28h.

On entry: CL = 2Ch, DL = Number of 128 byte records to be written

Returns: AL = Return code (0FFh = DL out of range), BL = AL

Notes: The system multi-sector count determines the number of 128 byte records which will be read or written by each subsequent single call to the read/write functions shown above.

Function 2Dh: Set file system error mode

Action: Determines the action to be taken when physical or extended errors are encountered in filing system operations.

On entry: CL = 2Dh, DL = System error mode, as follows.
0FFh = Return error mode
0FEh = Return and display
Any other value = default mode

Returns: Nothing

Notes: The action of the filing system in dealing with errors is set through this call. If 'return error' mode is set a program can ascertain a filing system error code and decide how to deal with it. If 'return and display' mnode is set the filing system will both display the error to the console device and return the code to a calling program.

In default mode an error is displayed and the action or program is terminated.

Function 2Eh: Return unallocated space an specified drive

Action: Returns the number of free (128 byte) records on the specified drive.

On entry: CL = 2Eh
DL = Drive number

Returns: If successful: AL = 0, AH = 0
If failed: AL = Return code, AH = Physical or extended error code (1 or 4), BX = AX

Notes: The remaining unallocated space on the drive is returned as a binary number value in the first three bytes of the DMA buffer. The first byte is the low byte value, the last is the high byte value.

Function 2Fh: Load and execute a program

Action: Loads and executes the program specified in the current DMA buffer.

On entry: CL = 2Fh, DMA buffer = command line

Returns: Only if failed:
AX = 0FFFFh (no command line)
BX = AX
CX = error code (see beginning of Appendix)

Notes: The command line consists of an ASCII string terminated by 00h, placed in the default DMA buffer The command line may explicitly include a 'COM', 'CMD' or EXE' filename extension. if it does not the only type of file which will be loaded is 'CMD'.

The file will be searched for in the current and P: drives, under the current user and user zero. if the file is found the current program is terminated, its memory released and the new program is loaded and executed. If there is insufficient memory for the new program, because the calling program is already terminated, loading of the new program is abandoned and a message is output to the console device.

A two byte code may be passed from the caller to the new routine by means of function 6Ch.

Function 30h: Write pending internal disc buffers to media

Action: Forces all unwritten records contained in internal blocking/deblocking buffers to be updated to media.

On entry: CL = 30h, DL = 0FFh if buffers to be purged

Returns: If successful: AL = 0, AH = 0
If failed: AL = 0FFh, AH = Physical error code, BX = AX

Notes: This call is used to ensure that all internally blocked (depending on the multi-sector count) records are written to media.

If DL is set to 0FFh all the calling routines internal record buffers are also purged. This is necessary if read-after- write verification is required, to ensure that the verification data is taken from disc rather than from the program's record buffers.

Function 31h: Get/Set system variable

Action: This is a general-purpose call to return or set system variables which do not have specific separate calls.

On entry: CL = 31h
DS:DX = Segment:offset of system control byte

Returns: Parameter block (SCBPB) bytes laid out as follows:

0 Number of the system variable(s)
1: 0 = get variables, 0Fh = set variables
2-7 (1-5 bytes) The value of the system variable

SCUPB updated if 'get variables'

Notes: The value of the system variable and its possible settings is as follows:
0: Console width. 0-79 (Default 79)
1: Console page length. 1-24 (Default 24)
2: Console page mode. 0 = scrolling, 1 = page
3: System ticks per second (read only, value 50 on the 512 and any European PC, value 60 on USA PCs).
4: Temporary file drive. 0 = current drive, 1 = A: through to 10h for P:
5: The five-byte time and date information is held in the data block in the system area in a similar format to that shown for functions 68h and 69h.

Function 32h- Call the XIOS directly

Action: This function passes transparently through the BDOS to give direct access to XIOS functions by means of a range of sub-functions.

On entry: CL = 32h, DS:DX = Segment:offset of XIOS descriptor, the format of which is byte:
0: XIOS function
1-2: CX parameter
3-4 DX parameter

Returns: AX = AX = XIOS return code, BX = AX

Notes: XIOS functions officially supported by DOS Plus are:
0 Terminate program
1 Terminate program
2 Check for console input status
3 Read character from console
4 Write character to console
5 Write character to list device
6 Write character to auxiliary device
7 Read character from auxiliary device
Fh Return list device status
15h Device initialisation
16h check console output status

The memory block parameters shown as CX and DX should contain the 16 bit values passed in those registers when normal BDOS calls are made.

As can be seen these functions have direct equivalents in BDOS calls and several similar facilities are also available via DOS interrupt 21h.

These calls therefore offer no advantage over BDOS or DOS calls, given that they are more difficult to implement.

Function 33h: Set the DMA segment address

Action: Sets the segment address of the start of the DMA. (See also function 1Ah)

On entry: CL = 33h, DX = DMA segment

Returns: Nothing

Notes: The DMA base address is set to offset 080h in the program's data segment by default. Use of this area overwrites the command tail of the original command rifle calling the program, therefore if this area is to be preserved the DMA is moved by using this call.

Function 34h: Get DMA address

Action: Returns the address of the current DMA buffer.

On entry: CL = 34h

Returns: ES:AX = Segment:offset of current DMA address, BX = AX

Notes: None

Function 35h: Allocate max. memory available

Action: Allocates the largest single block of free memory equal to or less than a specified amount.

On entry: CL = 35h, DS:DX = Segment-offset of memory control block (MCB)

The layout of the MCB is as follows (bytes):
0-1: MCB segment, start of memory
2-3: MCB length, length of allocation
4: MCB extent, additional param./returned byte value.

For this call the MCB segment is set to zero. The MCB length is set to the minimum number of paragraphs required. MCB extent is set to zero if the memory is to be released after program termination, or 2 if the allocation is to be retained after termination.

Returns: If successful: AX = 0
If failed: AX = 0FFFFh, CX = Error code
In either case the following is also returned
BX = AX

MCB segment: Base of allocated memory

MCB length: Number of paragraphs actually allocated

MCB extent: 0 if no more memory is available
1 if additional memory is available

Notes: The MCB segment is always expressed as an absolute paragraph number from the start of memory. The MCB length always contains the size of memory to be allocated in paragraphs. The returned value in MCB extent indicates whether this allocation was the last free memory block in the system.

Caution. This call allocates the whole of the largest single memory block in the system, not limited to the amount requested.

Function 36h: Allocate maximum memory at specified address

Action: Allocates the maximum memory available from a specified start paragraph.

On entry: CL = 36h,
DS:DX Segment:offset of MCB (see function 35h for MCB layout) with data as follows:
MCB segment = start paragraph required
MCB length = Minimum No. of paragraphs required
MCB extent = 0 if area is to be released
= 1 if allocation is to be retained

Returns:

If successful: AX = 0

If failed: AX = 0FFFFh, CX = Error code

In either case the following is also returned:
BX = AX

MCB segment = Base of allocated memory

MCB length = No. of paragraphs actually allocated

MCB extent = 0 if no more memory is available
= 1 if additional memory is available

Notes: Operation is as for Function 35h, except that the caller specifies the start address for the required allocation.

However, all the remainder of that block is allocated, not limited to the amount specified.

Function 37h: Allocate exact amount of memory

Action: Allocates a precise amount of memory.

On entry: CL = 37h,
DS:DX = Segment:offset of MCB (See function 35h for MCB layout) with data as follows:

MCB segment = start paragraph required (zero)

MCB length = Minimum No. of paragraphs required

MCB extent = 0 if area is to be released
= 1 if allocation is to be retained

Returns:

If successful: AX = 0

If failed: AX = 0FFFFh, CX = Error code

In either case the following is also returned:
BX = AX

MCB segment = Base of allocated memory

MCB length = No. of paragraphs actually allocated

MCB extent = 0 if no more memory is available
= 1 if additional memory is available

Notes: Operation is as for function 35h, except that the calling program specifies the precise quantity of memory to be used for the required allocation. Note that in this call the location of the allocation is not controlled.

Function 38h: Allocate exact amount of memory at specified location

Action: This call reserves only a specified quantity of memory, beginning from a specified address.

On entry: CL = 38,
DS:DX = Segment:offset of MCB (See function 35h for MCB layout) with data as follows:

MCB segment = Start paragraph required
MCB length = Exact No. of paragraphs required
MCB extent = 0 if area is to be released
= 1 if allocation is to be retained

Returns:

If successful: AX = 0

If failed: AX = 0FFFFh, CX = Error code

In either case the following is also returned:
BX = AX

MCB segment = Base of allocated memory

MCB length = No. of paragraphs actually allocated

MCB extent = 0 if no more memory is available
= 1 if additional memory is available

Notes: Operation is as for function 35h, except that the calling program specifies the precise quantity of memory to be used for the required allocation. This call is generally preferred to the previous calls since they allocate the whole of the (smallest) single memory block in which the allocation can be accommodated and/or allocate the memory at an undefined location. This call reserves only the precise amount requested at a specified start location (usually the program's own PSP start address).

The preference for function 38h is because in a single user system the smallest available memory block is also often the only one, extending to the top of RAM. if any of the preceding calls are used and MCB extent is set to two, it may be that no other program can be run subsequently, even after termination of the current task, as the entire memory may remain allocated.

Function 39: Free memory at a specified address

Action: Frees the memory allocation stating at a specified paragraph address to the end of the allocated segment.

On entry: CL = 39h,
DS:DX = Segment:offset of MCB (See function 35h for MCB layout) with data as follows:

MCB segment = Start of allocated memory
MCB length = No. of paragraphs to release
MCB extent = 0 if the specified part of the allocation is to be released
= 0FFh if the entire allocation is to be released

Returns:

If successful: AX = 0

If failed: AX = 0FFFFh, CX = Error code

In either case the following is also returned:
BX = AX

MCB segment = Base of allocated memory

MCB length = No. of paragraphs actually allocated

Notes: Memory is freed from the paragraph address specified in MCB segment to the end of the allocation that contains that paragraph. Although part of an allocation can be freed, only a contiguous block from the specified start to the end of the allocation can be released.

It is not possible to release a block in the middle of an allocation, or which includes the start but does not extend to the end.

Function 3Ah: Unallocated

Function 3Bh: Load 'CMD' file into memory

Action: Loads a CMD or RSX file into memory

On entry: CL = 3Bh
DS:DX = segment:offset of FCB

Returns: If successful: AX = Base page address, BX = AX
If failed: AX = 0FFFFh, CX = error code

Notes: This call loads a CMD or RSX program module into memory, returning the base page address of the loaded module in AX.

Note, the program is not called for execution by this call. If the loaded module is an RSX, both AX and BX are set to zero.

Function 3Ch: Call RSX program

Action: Allows direct calls to be passed to RSX modules.

On entry: CL = 3Ch,
DX = RSX parameter block address. The RSX PB layout is as follows (bytes):

0 RSX sub-function number

1 No. of word parameters (n)

2-3 Parameter one

4-5 Parameter two

... Parameter words as required

(2 bytes) Parameter n-i

(2 bytes) Parameter n

Returns: AX = 0FFFFh if no RSX function, otherwise nothing

Notes: RSX modules intercept and filter all BDOS calls by default, but this call permits a direct call to the currently loaded RSXs.
If no resident RSX recognises the sub-function code the system returns 0FFFFh in register AX.

Functions 3Dh to 62h: Unallocated

Function 63h: Truncate file to specified random record no.

Action: Sets the length of an existing file to the random record number specified in the FCB.

On entry: CL = 63h,
DS:DX = segment:offset of FCB

Returns:

If successful: AL = 0, AH = 0

If failed: AL = 0FFh,
AX = Physical or extended error code (1,2,3,4,7 or 9),
BX = AX

Notes: The calling program sets the drive field, the filename and file type fields and the random record field in the file's FCB prior to this call. The specified file is then truncated to the given random record number.

If the file is not found, the truncation length is not less than the current file length, or no such record number exists in the file (as it may not in random files) the call returns an error.

Function 64h: Create or update directory label

Action: Creates or updates a directory label for the specified drive.

On entry: CL = 64h,
DS:DX = Segment:offset of FCB

Returns:

If successful: AL = 0, AH = 0

If failed: AL = 0FFh,
AX = Physical or extended error code (1,2,3,4,7 or 9),
BX = AX

Notes: The calling program must set the file name and type fields of the FCB which are to be used as the directory label. If the directory is password protected the password must be placed in the first eight bytes of the DMA. The extent field should be set to define the user specification of the directory label data byte. If bit 0 of the byte is zero a new password is to be set, which must be placed in the second eight bytes of the DMA.

Function 65h: Get directory label data byte for specified drive

Action: Returns the existing data byte for the specified directory label in the specified drive.

On entry: CL = 65h, DL = drive number (A: = 0, B: = 1, etc)

Returns:

If successful: AL = Dir. label byte (0 = no label), AH = 0

If failed: AL = 0FFh,
AH = Physical error code (1 or 4),
BX = AX

Notes: The possible values for BL on entry are 0 to Fh. If the selected drive is in the reset state it is automatically logged in.

If an error occurs and the filing system is in default error mode, a message is displayed and the call terminates, otherwise AL is set to 0FFh and AH contains the error code.

Function 66h: Return file date/time stamp and password mode

Action: Returns the date/time information and the password mode for the file specified in the FCB.

On entry: CL = 66h, DS:DX = segment:offset of the FCB. The required data is as follows:

Byte 12: Password mode field bits set
Bit 7 Read mode
Bit 6: Write mode
Bit 5 Delete mode

Byte 12 = 0 means no password is set.

Bytes 24-27: Create or access time-stamp

Bytes 28-31 Update time stamp field

If the time stamp fields are set to binary zeros date/time stamping is not enabled.

Returns: If successful: AL = 0, AH = 0
If failed: AL = FFh (file not found),
AH = physical error code (1, 4 or 9), BX = AX

Notes: If the call is successful the date/time information and password mode are updated from the FCB.

If a file so marked is opened for write access the date and time stamps are updated if applicable.

If there is no physical error but the file does not exist, AL is Set to 0FFh and AH is set to zero.

Function 67h: Create or update extended FCB

Action: Updates a file's existing XFCB or creates an XFCB if no existing XFCB for specified file.

On entry: CL = 67h, DS:DX = Segment:offset of the FCB for the file

Returns: If successful: AH = 0, AL = directory code
If failed: AH = physical error code (1, 2, 4, 7 or 9), AL = FFh (physical error), BX = AX

Notes: The calling program must set the drive, filename and type fields in the referenced FCB. The extent field should be set to define the password mode and whether a new password is to be assigned. The bits of the extent field have the significance shown:

Bit 7: Read mode

Bit 6: Write mode

Bit 5: Delete mode

Bit 0: Assign new password

If the file is password protected the correct password must be placed in the first eight bytes of the current DMA. If bit 0 of the extent field is zero (new password) the new password must be placed in the second eight bytes of the DMA.

If there is no physical error but the file does not exist, AL is set to 0FFh and AH is Set to zero.

Function 68h: Set internal date and time

Action: Resets the system's internal clock for user date and time.

On entry:

CL = 68h

DS:DX = Segment:offset of the DAT structure, the format of which is as follows (bytes):

0-1 Date field

2 Hour field

3 Minute field

Returns: Nothing

Notes: The date is represented as a 16-bit integer value of the number of days elapsed since January 1st 1978 inclusive. The time is stored as two separate bytes, one each for hours and minutes, each held as a BCD digit.

Function 69h: Get internal date and time

Action: Returns the current date and time from the system's internal clock.

On entry: CL = 69h,
DS:DX = Segment:offset of the DAT structure (See function 68h for the format)

Returns: AL = seconds,
BL = AL, DAT filled in days, hours & minutes

Notes: The format of the information is the same as for function 68h, with the exception that the clock seconds are returned in AL. Note that this value cannot be reset.

Function 6Ah: Set the default password

Action: Specifies a default password to be used by the system for protected files.

On entry: CL = 6Ah, DS:DX = Segment:offset of the password

Returns: Nothing

Notes: The password must be specified as an eight-byte field pointed to by DS:DX. When the system accesses a password protected file both the current DMA password and the default password are checked. If either matches the file's password access is permitted.

Function 6Bh: Get the DOS Plus serial number

Action: Returns the six-character serial number of the DOS Plus Operating System.

On entry: CL = 6Bh, DS:DX = Segment:offset of serial number field

Returns: Serial number field filled

Notes: The serial number is placed in the six-byte field pointed to by DS:DX. Each byte is an ASCII character.

Function 6Ch: Get/set program return code

Action: Sets a program return code prior to termination or returns the code from the most recently-terminated program.

On entry: CL = 6Ch
DX = 0FFFF: Get return code
DX != 0FFFFh: Set return Code

Returns: AX = Program return code, BX = AX

Notes: This call permits a program to pass on a two-byte value which can be interrogated by a subsequent program by means of the same call. If DX = 0FFFFh the return code of the last terminated program is returned. Any other value sets that return code as the current program's own code.

The return code can therefore be used by a calling program, or by the batch file command
IF ERRORLEVEL

Return codes are:

0000h-FEFFh Successful

FF00h-FFFEh Unsuccessful

FF80h-FFFCh Reserved

FFFDh Fatal system error

FFFE CTRL-C termination

A default return code of zero is set by the system unless the program was loaded by a previous program, by means of function 2Fh.

Function 6Dh: Get/set console mode

Action: Sets or returns the current console operation rode.

On entry: CL = 46h(I suspect this should be 6Dh - editor)
DX = 0FFFFh: Get console mode
DX != 0FFFFh: Set console mode

The console mode variable is a 16-bit word with significant values as follows:

Bit 0 = 1: CTRL-C status only
= 0: normal status function

Bit 1 = 0: Start/stop scroll enabled
= 1: Start/stop scroll disabled

Bit 2 = 0: Normal console output mode
= 1: Tab expansion/printer output (CTRL-I, CTRL-P) disabled

Bit 3 = 0: Enable CTRL-C interception
= 1: Disable CTRL-C interception

Returns: AX = Console mode or no value
BX = AX

Notes: This call controls the action of the system in processing (or not) control characters received from the console input device, and the values returned by interrogating the console status variable by means of function Bh.

Function 6Eh: Get/set output delimiter

Action: Returns or sets a new system output delimiter.

On entry: CL = 6Eh
DL = New output delimiter (set) or
DX = 0FFFFh Get output delimiter

Returns: AL = Output delimiter or no value, BL = AL

Notes: The output delimiter is the character the system recognises as the string terminator in function 9, string output. The default delimiter is the dollar sign ($).

Function 6Fh: Write a specified block of characters

Action: Writes a specified block of data to the logical console output device, CONOUT.

On entry: CL = 6Fh, DS:DX = Segment:offset of character control block (CHCB)
The layout of the CHCB is as follows (bytes):

0-1 Offset of character string

2-3 Segment of character string

4-5 Length of character string in words

Returns: Nothing

Notes: If the console is in default mode CTRL-I tabs are expanded and CTRL-S and CTRL-Q stop and start scrolling. Also CTRL-P Characters within the block will send subsequent characters to the printer.

If the console is not in default mode the actions are determined by the current mode setting.

Function 70h: Write characters to list device

Action: Writes a specified number of characters to the logical list device, PRN, from the area of memory indicated by the character control block.

On entry: CL = 70h, DS:DX = Segment:offset of CHCB (See function 6Fh for format of CHCB)

Returns: Nothing

Notes: If the logical list device is not available this call waits until output can be completed.

Functions 7lh to 8Ch: Unallocated

Function 8Dh: Delay a specified no. of ticks

Action: This call causes a wait of the specified time before execution is resumed. During the delay other processes may use the processor.

On entry: CL = 8
DH:DL = Number of ticks to delay

Returns: Nothing if successful.
If DL was 0: AX = 0FFh delay not supported

Notes: The minimum delay is 0.02 seconds, the maximum is 65,535 * 0.02 seconds, or 21 minutes 50.7 seconds.

Function 8Eh: Relinquish processor to other tasks

Action: This call relinquishes processor control to other programs running concurrently.

On entry: CL = 8Eh

Returns:

AX = 0: Control returned, no problems

AX = 0FFFFh: Program dispatch not supported

Notes: This call provides a means of giving up the processor to other programs. Each program is given an amount of processor time determined by the value of the SLICE command before control is passed on.

Function 8Fh: Terminate program

Action: Terminates execution of the calling program.

On entry: CL = 8Fh, DL = Abort code

Returns: Nothing

Notes: This call is functionally identical to BDOS call 0.

Functions 90h to 92h: Unallocated

Function 93h: Detach program from console

Action: Disconnects console I/O from the program which is then running in the background

On entry: CL = 93h

Returns:

If successful: AL = 0

If failed: AL = 0FFh, BX = AX, CX = Error code

Notes: The system supports up to three background tasks. If no (more) background tasks are possible an error is returned. It should be noted that programs which enter the background may no longer issue DOS Plus calls. Only BDOS and XIOS calls are supported.

Functions 94h to 97h: Unallocated

Function 98h: Parse ASCII string and init. FCB

Action: The system parses an ASCII file specification and prepares an FCB.

On entry: CL = 98h, DS:DX = Segment:offset of parsed filename control block (PFCB)

The PFCB contains the offset of the ASCII file specification, followed by the offset of the target FCB to be filled by the system. A minimum length string of 128 bytes is permitted, while the length of the target FCB must be 32 bytes. The filename is in the format:

(d:)filename{.ext} {;password}

where each of the items enclosed by { } is optional.

Returns: AX = 0 if end of line or end of string. FCB as shown below
AX = 0FFFFh if error, when CX = error code, BX = AX
The FCB is initialised by this call as follows (bytes):

0 Drive ID. If not specified, default is used

1-8 Filename

9-11 Filetype (extension)

12-15 Zero filled

Notes: Leading blanks and tabs in the input string are ignored, but ASCII characters in the range 1 to 31 in the input string are treated as an error.

The system regards any parsing delimiter in the input string which is out of context with its location in the file specification as the end of the string.

The following are recognised as string delimiters, unless they are logically appropriate to their location in the ASCII file specification:

00h null
0Ch tab
0Dh return
20h space
2Ch , (comma)
2Fh | (solidus)
2Eh . (period)
3Ah : (colon)
3Bh ; (semicolon)
30h < (less than)
3Dh = (equal)
3Eh > (greater than)
5Bh [ (left square bracket)
5Dh ] (right square bracket)

All filenames and extensions are written to the FCB in upper case and blanks are used to pad the filename to eight characters and the extension to three as required. If a '*' occurs in a filename, that character and all remaining characters in the FCB entry are set to '?'.

Function 99h: Unallocated

Function 9Ah: Get system data area address

Action: Returns the segment address of the system data area, SYSDAT

On entry: CL = 9Ah

Returns: BX = 0, ES = SYSDAT segment

Notes: This call provides facilities for advanced programmers to directly manipulate system variables and data not catered for in the standard function.

It should be noted that the location of SYSDAT data is not fixed and may vary from version to version of DOS Plus, therefore access to this area should be used with discretion and only when absolutely necessary.

Functions 9Bh to ABh: Unallocated

Function ACh: Read characters from AUXIN

Action: Reads a specified block of characters from the auxiliary input device directly into a specified memory location.

On entry: CL = 0ACh, DX = CHCB offset address (See function 6Fh for format of CHCB)

Returns: AX = Number of characters read, DX = AX

Notes: This call returns the number of characters actually read, which may be less than the number specified in the CHCB. The call returns when either the auxiliary input device indicates there is no more data, or the buffer becomes full, whichever occurs first.

If no data is ready when the call is issued it waits until at least one character has been received. If "input exhausted" then occurs before the specified number of characters have been read, the call returns immediately

Function ADh: Write characters to AUXOUT

Action: Writes a specified block of characters to the auxiliary output device directly from a specified memory location.

On entry: CL = ADh
DX = CHCB offset address (See function 6Fh for format of CHCB)

Returns: AX = Number of characters written, BX = AX

Notes: This call returns the number of characters actually written, which may be less than the number specified in the CHCB. The call returns when either the auxiliary output device indicates no more data can be sent (the buffer is full), or the specified data has been transmitted, whichever occurs first.

If no data can be sent when the call is issued it waits until at least one character can be transmitted. If "output full" then occurs before all the specified data has been sent the call returns immediately.