< Previous | Contents | Next >
C: 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 calls use the general register scheme shown below.
Parameter Type |
Register |
|||
On entry |
Function code Byte parameter |
CL DL |
||
On exit |
Byte returned or Word returned or Memory address Segment Offset Word return Error code if failed Return code |
AL AX ES: AX BX (usually the same as AX) CX (Zero if successful) 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' MS-DOS 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 MS-DOS or PC-DOS 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 ; 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.
Action: |
Terminates the calling process and returns control to the system. |
|
On entry: |
CL = 0 |
|
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. |
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. |
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). |
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. |
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. |
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. |
Action: |
Permits the calling process to read or write unedited and unmodified console data or to check console status. |
|||||||||||||
On entry: |
|
|||||||||||||
Returns: |
|
|||||||||||||
Notes: |
On entry, if DL = 0FFh, either the character entered is returned, or AL is set to zero to indicate no input ready (ie 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. |
Action: |
Checks the input status of the AUXIN device |
||||
On entry: |
CL = 7 |
||||
Returns: |
BL = AL |
||||
Notes: |
This call does not read the input data, only the status. |
Action: |
Checks the input status of the AUXOUT device |
||||
On entry: |
CL = 8 |
||||
Returns: |
BL = AL |
||||
Notes: |
Output is not performed by this call, only the status is checked. |
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. |
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. |
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 |
|
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. |
Action: |
Returns the BDOS version number as a two-byte value. |
|
On entry: |
CL = 0Ch |
|
Returns: |
AX = BDOS version number, as follows: |
|
Notes: |
In DOS Plus 2.1, the AX value returned is 01080h. |
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 (ie the default in the PSP). |
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) |
|
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. |
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: |
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 (ie 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. |
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.
|
|||||||
Returns: |
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. |
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
|
|||||||
Returns: |
BX = AX |
|||||||
Notes: |
The calling program must set the drive field, the filename field and the file type field in the FCB 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. |
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: |
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. |
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
|
|||||||
Returns: |
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. |
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. |
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. |
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
|
|||||||
Returns: |
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. All file attributes are set to zero. If there is no physical error but AL is returned as 0FFh there is no space in the directory. |
Action: |
Renames a matching file |
|||||||
On entry: |
CL =17h, DS:DX = Segment:offset of FCB |
|||||||
Returns: |
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. |
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. |
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 |
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. |
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. |
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'. |
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 1 to drive B: and so on up to 0Fh which is floating drive P:. |
Action: |
Modifies a file's attributes and optionally sets its last record byte count. |
|||||||
On entry: |
CL = 1Eh, DS:DX = Segment:offset of FCB
|
|||||||
Returns: |
|
|||||||
Notes: |
If the file is password protected, the correct password must have been placed in the DMA buffer, or defined as the default password. |
Action: |
Returns the address of the BIOS resident disc parameter block address for the current drive. |
|
On entry: |
CL = 1Fh |
|
Returns: |
ES:AX = Segment:offset of DPB address |
|
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. |
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. |
Action: |
Reads a selected record from an open file. |
|
On entry: |
CL = 21h |
|
Returns: |
AL = Return code |
|
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. |
Action: |
Writes a selected record to an open file. |
|
On entry: |
CL = 22h |
|
Returns: |
AL = 0 return code |
|
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. |
Action: |
Returns the highest record number plus one of the specified file. |
|||||||
On entry: |
CL = 23h |
|||||||
Returns: |
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. |
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. |
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. |
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. |
Action: |
Writes one or more sequential records to an open file starting at the file's current record position. |
|||||||
On entry: |
CL = 28h |
|||||||
Returns: |
|
|||||||
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 (ie non-existent) random record positions within the file. |
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. |
Action: |
Determines the action to be taken when physical or extended errors are encountered in filing system operations. |
|
On entry: |
CL = 2Dh |
|
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' mode 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. |
Action: |
Returns the number of free (128 byte) records on the specified drive. |
|||||||
On entry: |
CL = 2Eh |
|||||||
Returns: |
|
|||||||
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. |
Action: |
Loads and executes the program specified in the current DMA buffer. |
|
On entry: |
CL = 2Fh, DMA buffer = command line |
|
Returns: |
Only if failed: |
|
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. |
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: |
|
|||||||
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 routine's 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. |
Action: |
This is a general-purpose call to return or set system variables which do not have specific separate calls. |
|||||||||||||||||||||||||
On entry: |
CL = 31h Parameter block (SCBPB) bytes laid out as follows: |
|||||||||||||||||||||||||
Returns: |
SCBPB updated if 'get variables' |
|||||||||||||||||||||||||
Notes: |
The value of the system variable and its possible settings is as follows:
|
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: |
|||||||||||||||||||||||||||||||||||||||||||||
Returns: |
AX = XIOS return code, BX = AX |
|||||||||||||||||||||||||||||||||||||||||||||
Notes: |
XIOS functions officially supported by DOS Plus are:
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. |
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 line calling the program, therefore if this area is to be preserved the DMA is moved by using this call. |
Action: |
Returns the address of the current DMA buffer. |
|
On entry: |
CL = 34h |
|
Returns: |
ES:AX = Segment:offset of current DMA address |
|
Notes: |
None |
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): 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: |
In either case the following is also returned: BX = AX
|
||||||||||||||||
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. |
Action: |
Allocates the maximum memory available from a specified start paragraph. |
||||||||||||||||
On entry: |
CL = 36h,
|
||||||||||||||||
Returns: |
In either case the following is also returned: BX = AX
|
||||||||||||||||
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. |
Action: |
Allocates a precise amount of memory. |
||||||||||||||||
On entry: |
CL = 37h,
|
||||||||||||||||
Returns: |
In either case the following is also returned: BX = AX
|
||||||||||||||||
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. |
Action: |
This call reserves only a specified quantity of memory, beginning from a specified address. |
||||||||||||||||
On entry: |
CL = 38,
|
||||||||||||||||
Returns: |
In either case the following is also returned: BX = AX
|
||||||||||||||||
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. |
Action: |
Frees the memory allocation stating at a specified paragraph address to the end of the allocated segment. |
|||||||||||||
On entry: |
CL = 39h,
|
|||||||||||||
Returns: |
In either case the following is also returned: BX = AX
|
|||||||||||||
Notes: |
Memory is freed from the paragraph address specified in the 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. |
Action: |
Loads a CMD or RSX file into memory |
|||||||
On entry: |
CL = 3Bh |
|||||||
Returns: |
|
|||||||
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. |
Action: |
Allows direct calls to be passed to RSX modules. |
||||||||||||||||||||||
On entry: |
CL = 3Ch,
|
||||||||||||||||||||||
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. |
Action: |
Sets the length of an existing file to the random record number specified in the FCB. |
|||||||
On entry: |
CL = 63h, |
|||||||
Returns: |
|
|||||||
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. |
Action: |
Creates or updates a directory label for the specified drive. |
|||||||
On entry: |
CL = 64h, |
|||||||
Returns: |
|
|||||||
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. |
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: |
|
|||||||
Notes: |
The possible values for DL 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. |
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 = Bytes 24-27: Create or access time-stamp If the time stamp fields are set to binary zeros date/time stamping is not enabled. |
|||||||
Returns: |
|
|||||||
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. |
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: |
|
|||||||
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 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. |
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):
|
||||||||||
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. |
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. |
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. |
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. |
Action: |
Sets a program return code prior to termination or returns the code from the most recently-terminated program. |
||||||||||||||||
On entry: |
CL = 6Ch |
||||||||||||||||
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:
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. |
Action: |
Sets or returns the current console operation rode. |
|||||||||||||
On entry: |
CL = 6Dh The console mode variable is a 16-bit word with significant values as follows:
|
|||||||||||||
Returns: |
AX = Console mode or no value |
|||||||||||||
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. |
Action: |
Returns or sets a new system output delimiter. |
|
On entry: |
CL = 6Eh |
|
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 ($). |
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):
|
||||||||||
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. |
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. |
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. |
|
Notes: |
The minimum delay is 0.02 seconds, the maximum is 65,535 * 0.02 seconds, or 21 minutes 50.7 seconds. |
Action: |
This call relinquishes processor control to other programs running concurrently. |
|||||||
On entry: |
CL = 8Eh |
|||||||
Returns: |
|
|||||||
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. |
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. |
Action: |
Disconnects console I/O from the program which is then running in the background |
|||||||
On entry: |
CL = 93h |
|||||||
Returns: |
|
|||||||
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. |
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 The FCB is initialised by this call as follows (bytes):
|
|||||||||||||||||||||||||||||||||||||||||||
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:
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 '?'. |
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. |
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. |
Action: |
Writes a specified block of characters to the auxiliary output device directly from a specified memory location. |
|
On entry: |
CL = ADh |
|
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. |
< Previous | Contents | Next >