DOS Interface Documentation - SC12 @CHIP-RTOS V1.10

DOS

DOS API News

Interrupt 0x21 service 0x00: Terminate Program

Refer to interrupt 0x21, service 0x4C.

Parameters

AH

0x00

Comments

This service has been replaced by service 0x4C.   The system treats both as the same function.

Interrupt 0x21 service 0x02: Output Character to standard output

Sends the character in DL to the standard output.

Parameters

AH

0x02

DL

Character to be output to stdout

Return Value

Returns nothing

Comments

Each potential output device has its own output buffer.   This function queues the provided output character into each device's output buffer for which stdout is configured.

The transmitters are interrupt driven buffered I/O.   If space is available in the transmit buffer(s) when this call is made, the character is stored and control returned immediately to the caller.   Otherwise a wait loop is entered, awaiting space in each configured transmit buffer.

This function does not check for Ctrl-C.

Related Topics

stdout configuration

Interrupt 0x21 service 0x06: Direct Console Output

If DL!=0xFF: Send the character in DL to the standard output.
If DL==0xFF: read character from stdin if one is available.

Parameters

AH

0x06

DL

Character to be output to stdout

Return Value

If call with DL!=0xFF then no return value (only output to stdout)
If call with DL==0xFF then

If input character is available at stdin then

Set BX register to indicate the stdin channel source of character,
        where:  1: EXT , 2: COM , 4: Telnet.
Return input character in AL and reset CPU's zero flag

Else

Set CPU's zero flag to indicate no character available

Endif

Endif

Comments

Output is buffered and interrupt driven.   This function will return after placing output character into the transmit buffer when DL != 0xFF.

This function does not check for Ctrl-C.

Related Topics

stdin configuration

stdout configuration

Interrupt 0x21 service 0x07: Direct Console Input

Wait for a character to be read from standard input.

Parameters

AH

0x07

Return Value

Returns the character read in AL.
Returns in BX the source stdin channel of the character, where:   1: EXT , 2: COM , 4: Telnet

Comments

This function is identical to interrupt 0x21, service 0x08.

This function does not echo the received character and it does not check for Ctrl-C.

Related Topics

stdin configuration

Interrupt 0x21 service 0x08: Read Keyboard

Wait for a character to be read from standard input.

Parameters

AH

0x08

Return Value

Returns the character read in AL.
Returns in BX the source stdin channel of the character, where:   1: EXT , 2: COM , 4: Telnet

Comments

This function is identical to interrupt 0x21, service 0x07.

This function does not echo the character and it does not check for Ctrl-C.

Related Topics

stdin configuration

Interrupt 0x21 service 0x09: Send string to standard output

Sends a string to stdout ending with '$' or null terminated.

Parameters

AH

0x09

DS:DX

Specifies a pointer to the first character of the string.

Return Value

Returns nothing.

Comments

This function does not check for Ctrl-C.

Related Topics

stdout configuration

Interrupt 0x21 service 0x0B: Character Available Test

Check if a character from standard input is available.

Parameters

AH

0x0B

Return Value

AL=0x00:   No character is available.
AL=0xFF:   Character is available.

Comments

This function does not check for Ctrl-C.

Related Topics

stdin configuration

Interrupt 0x21 service 0x0E: Set Default Drive

Changes the default drive for the current task.

Parameters

AH

0x0E

DL

New default drive (00h = A:, 01h = B:, etc)

Related Topics

Get current drive

Interrupt 0x21 service 0x19: Get Current Drive

Returns the current drive for this process.

Parameters

AH

0x19

Return Value

AL = drive where 0 is A:, 1 is B:, ..., 4 is E:

Related Topics

Set default drive

Interrupt 0x21 service 0x1A: Set Disk Transfer Area Address

Sets address of the Disk Transfer Area (DTA) needed for findfirst/findnext functions.

Parameters

AH

0x2A

DS:DX

Pointer to DTA

Comments

The main task of your application has a standard pointer to a Disk Transfer Area of the program.   Tasks created with the RTOS API inside of your application use a DTA from an internal list.   A task, which gets access to the file system (via RTX_ACCESS_FILESYSTEM service) reserves an entry in this list.

Only ten DTA entries for user tasks are available.

Related Topics

DOS Get Disk Transfer Area address service

RTOS's RTX_ACCESS_FILESYSTEM Service

Interrupt 0x21 service 0x25: Set IRQ Vector

This function allows you to set an interrupt vector to your interrupt function.

Parameters

AH

0x25

AL

Specifies vector number.

DS:DX

Vector to your interrupt procedure.

Return Value

No return value.

Comments

You can use the following IRQ's

0x0A     DMA0 / INT5
0x0B     DMA1 / INT6
0x0C     INT0
0x0E     INT2
0x0F     INT3
0x10     INT4

IRQ 0x0D (Ethernet) and IRQ 0x13 (Timer) cannot be changed !

Also this DOS service interrupt 0x21 vector cannot be changed using this service.

Related Topics

Get IRQ vector

Interrupt 0x21 service 0x2A: Get System Date

Returns the system date.

Parameters

AH

0x2A

Return Value

CX=Year (full 4 digits), DH=Month, DL=Day, AL=day of week (0=Sunday)

Related Topics

Set system date

Get system time

Interrupt 0x21 service 0x2B: Set System Date

Sets the system date.

Parameters

AH

0x2B

CX

Year (including century, e.g. 2001)

DH

Month (1..12)

DL

Day (1..31)

Comments

This function performs no error checking on entered date.

Related Topics

Get system date

Set system time

Interrupt 0x21 service 0x2C: Get System Time

Returns the system time.

Parameters

AH

0x2C

Return Value

CH=Hour, CL=Minute, DH=Second, DL=0

Related Topics

Get system date

Set system time

Interrupt 0x21 service 0x2D: Set System Time

Sets the system time.

Parameters

AH

0x2D

CH

Hour

CL

Minute

DH

Second

Related Topics

Set system date

Get system time

Interrupt 0x21 service 0x2F: Get Disk Transfer Area Address

Gets address of the Disk Transfer Area (DTA) needed for findfirst/findnext.

Parameters

AH

0x2F

Return Value

Returns the address of the DTA in ES:BX

Comments

The main task of your application has a standard pointer to a Disk Transfer Area of the program.   Tasks created with the RTOS API inside of your application use a DTA from an internal list.   A task, which gets access to the file system (via RTX_ACCESS_FILESYSTEM service) reserves an entry in this list.

Only ten DTA entries for user tasks are available.

Related Topics

DOS Set Disk Transfer Area address service

RTOS's RTX_ACCESS_FILESYSTEM Service

Interrupt 0x21 service 0x30: Get DOS Version

Get the version number of DOS.

Parameters

AH

0x30

Return Value

Returns the DOS version in AX.

Comments

This function always returns 0x0003 (meaning DOS version 3.00).

However, this does not mean that we have a full implementation of DOS 3.0 !

Interrupt 0x21 service 0x31: Keep Process

Makes a program remain resident after it terminates.

Parameters

AH

0x31

DX

Memory size, in paragraphs, required by the program

Return Value

None

Interrupt 0x21 service 0x35: Get IRQ Vector

Gets the address of an interrupt service routine.

Parameters

AH

0x35

AL

Specifies vector number.

Return Value

Returns the vector in ES:BX

Related Topics

Set IRQ vector

Interrupt 0x21 service 0x36: Get Disk Free Space

DOS function for detecting disk free space.

Parameters

AH

0x36

DL

Drive (0 current drive, 1=A, ...)

Return Value

AX:   -1 Invalid drive number
    else
AX:   number of sectors per cluster
BX:   number of free clusters
CX:   number of bytes per sector
DX:   number of clusters per drive

Comments

When call is successful (AX=1), free disk space can be computed from the return values as:

free disk space (bytes) = AX * BX * CX

Note:  

In @CHIP-RTOS version 1.00, this function had a bug: Parameter 0 in DL was taken as drive A:, which should have meant the current drive.

Interrupt 0x21 service 0x39: Create Directory

Creates a new subdirectory.

Parameters

AH

0x39

DS:DX

Pointer to null terminated path name.

Return Value

Carry flag is cleared on success, set on error.
On error AX contains error code:

2: File not found
3: Path not found
5: Path exists or access denied

Related Topics

Remove Directory

Interrupt 0x21 service 0x3A: Remove Directory

Deletes a subdirectory.

Parameters

AH

0x3A

DS:DX

Pointer to null terminated path name.

Return Value

Carry flag is cleared on success, set on error.
On error AX contains error code:

2: File not found
3: Path not found
5: access denied, not a directory, not empty, or in use

Comments

The subdirectory must not contain any files.

Related Topics

Create Directory

Interrupt 0x21 service 0x3B: Set Current Working Directory

Sets the current working directory.

Parameters

AH

0x3B

DS:DX

Null terminated path of new current working directory

Return Value

Carry flag is cleared on success, set on error.

Comments

If the path contains a drive name, the current working directory of that drive is changed without changing the default drive.   Otherwise, the current working directory is changed for the default drive.

Each task has it's own current working directory.

Related Topics

Get current working directory

Interrupt 0x21 service 0x3C: Create New File Handle

Creates a file of specified name.   If a file by this name already exists, it is deleted.   The returned file handle is for a new empty file.

Parameters

AH

0x3C

CX

File attributes (bit field):

B0 - Read Only
B1 - Hidden File
B2 - System File
B5 - Archive Flag

DS:DX

Pointer to a null terminated file name and path

Return Value

Success: Carry flag cleared, AX = file handle
Failure: Carry flag set, AX = error code:

AX=2: Path not found
AX=3: File name length exceeded 147 character limit
AX=4: Too many files open
AX=5: Invalid file name or access denied

Comments

Files are always opened in a non-sharing mode.

Related Topics

Open Existing File

Close File Handle

Get/Set File Date/Time

Interrupt 0x21 service 0x3D: Open an Existing File

Opens an existing file.

Parameters

AH

0x3D

AL

Open mode:

AL=0: Open for read
AL=1: Open for write
AL=2: Open for read and write

DS:DX

Pointer to a null terminated file path.

Return Value

Success: Carry flag cleared, AX = file handle
Failure: Carry flag set, AX = error code:

AX=2: Path or file not found
AX=4: Too many files open
AX=5: Access denied

Comments

In write mode, files are always opened in a non-sharing mode.

The file system does not distinguish between file not found or invalid path.   The error return value in both cases is 2.

Related Topics

Create New File Handle

Close File Handle

Get/Set File Attributes

Get/Set File Date/Time

Interrupt 0x21 service 0x3E: Close File Handle

Closes an open file.

Parameters

AH

0x3E

BX

File handle

Return Value

Success: Carry flag cleared
Failure: Carry flag set, AX = error code:

AX=6: file not open

Related Topics

Create New File Handle

Open Existing File

Get/Set File Date/Time

Interrupt 0x21 service 0x3F: Read from File

Reads a number of bytes from a file, the handle of which is specified in BX.

Parameters

AH

0x3F

BX

File handle

CX

Number of bytes to read

DS:DX

Pointer to the destination data buffer.

Return Value

Success: Carry flag cleared, AX = number of bytes read into buffer from file
Failure: Carry flag set, AX = error code:

AX=5: Access denied
AX=6: Invalid file handle

Related Topics

Create New File Handle

Open Existing File

Write to File

Set Current File Position

Interrupt 0x21 service 0x40: Write to File

Writes a number of bytes to a file, the handle of which is specified in BX.

Parameters

AH

0x40

BX

File handle

CX

Number of bytes to write

DS:DX

Pointer to the source data buffer.

Return Value

Success: Carry flag cleared, AX = number of bytes written into the file
Failure: Carry flag set, AX = error code:

AX=5: Access denied
AX=6: Invalid file handle

Comments

Requesting zero bytes written to file (CX=0) truncates the file at the current position.

Related Topics

Create New File Handle

Open Existing File

Read from File

Set Current File Position

Interrupt 0x21 service 0x41: Delete File

Deletes a file.   Wildcards are not allowed.

Parameters

AH

0x41

DS:DX

Pointer to null terminated file name and path.

Return Value

Success: Carry flag is cleared
Failure: Carry flag is set, AX holds error code:

AX=2: File not found
AX=5: Access denied

Comments

Files with read only attribute cannot be deleted.

Related Topics

Create New File Handle

Get/Set File Attributes

Interrupt 0x21 service 0x42: Set Current File Position

The operating system maintains a 32 bit file pointer that it uses for read or write requests to the respective file.   This service can be used to either read or set this file pointer.   The file pointer associated with handle is set to a new byte position offset relative to the origin of the move.

Parameters

AH

0x42

AL

Origin of move
    0x00: Relative to start of file
    0x01: Relative to current position
    0x02: Relative to end of file

BX

File handle

CX,DX

Offset of the displacement with higher order word in CX.

Return Value

Success: Carry flag is cleared, DX,AX holds the new position relative to the start of the file with high word in DX.
Failure: Carry flag is set, AX holds error code:

AX = 0x06: Invalid handle
AX = 0x19: Invalid displacement

Comments

If you attempt to seek beyond the end of file, the file pointer will be positioned at the end of the file.

To read current file position without changing it, call with AL=1, CX:DX = 0:0.

Related Topics

Read from File

Write to File

Interrupt 0x21 service 0x43: Get/Set File Attributes

Use this function to inspect or change the attributes of a file.

Parameters

AH

0x43

AL

0: get, 1: set

CX

File attributes (bit field):

B0 - Read Only
B1 - Hidden File
B2 - System File
B5 - Archive Flag

DS:DX

Pointer to a null terminated string holding the file path.

Return Value

Success: Carry flag cleared, file attributes in CX (bit field):

... same flag bits as CX input parameter with additional bits ...
B3 - Volume
B4 - Directory Entry

Failure: Carry flag set, AX holds error code:

AX=1: Invalid function (wrong value in AL)
AX=2: File not found
AX=5: Access denied

Comments

Input parameter CX is not used when input parameter AL = 0.

Related Topics

Delete File

Interrupt 0x21 service 0x44: IOCTL, Set/Get Device Information

Changes the data that DOS uses to control a device.

Parameters

AH

0x44

AL

0: Get device data, 1: Set device data

BX

Handle

DX

Device data

Return Value

Success: Carry flag cleared, Device data in DX.
Failure: Carry flag set, AX holds error code

AX=1: Invalid function (wrong value in AL)
AX=6: Invalid handle

Comments

If bit 7 of the data is 1, the handle refers to a device and data bit assignments are as follows:

Bit   Meaning when bit is set to '1'
B15    Reserved
B14    Device can handle function 0x44, codes 2 and 3
B13    Device supports output until busy
B12    Reserved
B11    Device understands open/close
B10-8  Reserved
B7     '1' indicates handle refers to a device
B6     Not "end of file" on input
B5     Don't check for control characters
B4     Reserved
B3     Clock device
B2     Null device
B1     Console Output device
B0     Console Input device

If bit 7 of the data is 0, the handle refers to a file and data bit assignments are as follows:

Bit   Meaning
B15-8 Reserved
B7    Set to '0' to indicate handle refers to a file.
B6    Set to '0' when the file has been written
B0-5  Drive number (0=A, 1=B, etc)

The first three file handles are used for the stdio devices:

0: Input
1: Output
2: Error

This service was implemented to be compatible with the older DOS compilers.   The data is saved when you issue a write, but the data is not used by the @CHIP-RTOS.   Control characters are not recognized as such.   Function 0x44 codes 2 and 3 are not supported.

Interrupt 0x21 service 0x47: Get Current Working Directory

Gets the current working directory for a drive.

Parameters

AH

0x47

DS:SI

Pointer to a 64 byte memory area to receive null terminated path of current working directory (CWD).

DL

Drive number, 0 for current, 1 for A, ..

Return Value

Success: Carry flag cleared, Buffer at [DS:SI] contains CWD path.
Failure: Carry flag set, error code in AX=15

Comments

Each task has it's own current working directory.   When a program starts, its current drive and working directory will be set to the drive and directory that was current before the program started.

Related Topics

Set current working directory

Interrupt 0x21 service 0x48: Allocate Memory

Allocates memory for the calling process.

Parameters

AH

0x48

BX

Size counted in paragraphs

Return Value

Success:

Carry flag cleared, AX holds the segment of the memory area

Failure:

Carry flag set due to not enough memory available.
AX = 0.
BX holds the size of the largest free block available expressed by paragraph count.

Comments

A paragraph is 16 bytes in length.

Related Topics

Free allocated memory

Resize memory

Interrupt 0x21 service 0x49: Free Allocated Memory

Releases the specified allocated memory.

Parameters

AH

0x49

ES

Segment of the memory area to be released, allocated with function 0x48

Return Value

Success: Carry flag cleared
Failure: Carry flag set, AX holds the error code = 9.

Related Topics

Allocate memory

Resize memory

Interrupt 0x21 service 0x4A: Resize Memory

Increases or decreases the size of a memory allocation block.

Parameters

AH

0x4A

BX

Desired new size expressed in paragraphs

ES

Segment address of memory block

Return Value

Success: Carry flag cleared
Failure: Carry flag set due to not enough memory available and the size of the largest free block is returned in BX (paragraph count).

Comments

A paragraph is 16 bytes in length.

This call may fail if a user tries in their application to increase a memory block, allocated with int21h 0x48.   In that case it is only possible to decrease the size of the allocated memory block.

Related Topics

Allocate memory

Free memory

Interrupt 0x21 service 0x4B: EXEC

Load and/or execute a program.   This function loads the program and builds its PSP (Program Segment Prefix) based on a parameter block that you provide.

Parameters

AH

0x4B

AL

Type of load:
    00h - Load and execute
    01h - Load but do not execute

DS:DX

Null terminated program name (must include extension)

ES:BX

parameter block
Offset  Size     Description 00h    WORD     Segment of environment to copy for child process
                 (copy caller's environment if 0000h)
02h    DWORD    Pointer to command tail to be copied into child's PSP
06h    DWORD    Pointer to first FCB to be copied into child's PSP
0Ah    DWORD    Pointer to second FCB to be copied into child's PSP
0Eh    DWORD    (AL=01h) will hold subprogram's initial SS:SP on return
12h    DWORD    (AL=01h) will hold entry point (CS:IP) on return

Return Value

Success:

Carry flag cleared
AX = New program's task ID
BX = segment of PSP (add sizeof PSP/16 for relocation offset)

Failure:

Carry flag set
AX = 1

Comments

Use 'Type of Load' AL = 0x00 to load and execute another program.

'Type of Load' AL = 0x01 is used to load a program without executing it.   This option is available for debuggers.   The new task is waiting for it's trigger when started in this manner.

For both functions, the calling process must ensure that there is enough unallocated memory available; if necessary, by releasing memory with services AH=0x49 or AH=0x4A.

Interrupt 0x21 service 0x4C: End Process

Terminates a DOS program.

Parameters

AH

0x4C

Comments

The memory used by the process is released, with following exception.   This function will not free system memory allocated by a task that was created within a program.   Only memory allocated by the program's main task will be freed here.

Related Topics

Delete @CHIP-RTOS task

Interrupt 0x21 service 0x4E: Find First File

Find first file matching file name specification and attribute.   The results are stored in the Disk Transfer Area (DTA).

Parameters

AH

0x4E

CX

File attribute

DS:DX

Null terminated file specification (may include path and wildcards)

Return Value

Success: Carry flag cleared, search results are in DTA
Failure: Carry flag set

Comments

The main task of your application has a standard pointer to a Disk Transfer Area of the program.   This DTA address should be set with interrupt 0x21 function 0x1A before calling this findfirst function.   The findfirst/findnext sequence is handled by your compiler library so the Disk Transfer Area is therefore not described here.

Tasks created with the RTOS API inside of your application use a DTA from an internal list.   A task which gets access to the file system reserves an entry in this list.

Only ten DTA entries for user tasks are available.

Related Topics

Find next file

RTOS RTX_ACCESS_FILESYSTEM Service

Fast Findfirst file

Interrupt 0x21 service 0x4F: Find Next File

Finds the next file in the findfirst/findnext sequence.   The results are stored in the Disk Transfer Area (DTA).

Parameters

AH

0x4F

Return Value

Success: Carry flag cleared, search results are in DTA
Failure: Carry flag set

Comments

The task that calls findnext must be the same task that called findfirst.

Since the entire state of a findfirst/findnext sequence is held in the DTA data block, other disk operations such as renaming, moving, deleting, or creating files can cause inaccurate directory searches such as finding the same file twice.   Please look at the findfirst function (Interrupt 0x21, function 0x4E) for further restrictions.

The findnext function is designed to be called in a loop until it fails, which indicates the last file has been found.

Related Topics

Find first file

Interrupt 0x21 service 0x50: Debugger Support

Gets address of internal program task list and sets callback vector used for program startup notification.

Parameters

AH

0x50

DX:BX

Callback vector

CX

Sanity Check = 0x8765

Return Value

DX:BX contains pointer to internal task list.
AX = Task list length = 12
CX = size of task list elements
SI = RTOS Private Data Segment

Comments

This function is intended only for debugger usage.

Interrupt 0x21 service 0x51: Get PSP Segment Address

Gets PSP (Program Segment Prefix) segment address

Parameters

AH

0x51

Return Value

BX contains the PSP segment address, if BX=0, PSP was not found

Comments

This function will not work if called from tasks created within programs.

This function is identical to interrupt 0x21 service 0x62.

Interrupt 0x21 service 0x56: Change Directory Entry, Rename File

Rename a file by changing its directory entry

Parameters

AH

0x56

DS:DX

Pointer to null terminated old file name

ES:DI

Pointer to null terminated new file name (without path name!)

Return Value

Success: Carry flag cleared
Failure: Carry flag set, AX holds error code

AX:   1 - File not found
AX:   4 - New file name already exists
AX:   5 - Internal error
AX:   7 - Directory update failed

Interrupt 0x21 service 0x57: Get/Set File Date and Time

Get or set file date and time.   The file is specified by file handle.

Parameters

AH

0x57

AL

AL=0 to get the date and time of the last modification.
AL=1 to set the file date and time.

BX

File handle

CX

if AL==1: Time in the format described below

DX

if AL==1: Date in the format described below

Return Value

Success: Carry flag cleared, if input parameter AL=0 then:

CX = time of last modification
DX = date of last modification

Failure: Carry flag set

Comments

The time/date registers are coded as follows:

CX time of last modification
bits 15-11:  hours (0..23)
bits 10-5:   minutes
bits 4-0:    seconds/2

DX date of last modification
bits 15-9:   year-1980
bits 8-5:    month
bits 4-0:    day

Related Topics

Create New File Handle

Open Existing File

Interrupt 0x21 service 0x58: Get/Set memory strategy (dummy function)

Get/Set memory strategy, only a dummy function for compatibility

Parameters

AH

0x58

AL

AL=0 Get strategy
AL=1 Set strategy.

BX

(Al=1) Strategy 0: First fit, 1: Best fit, 2: Last fit

Return Value

If parameter AL == 0 (get strategy)

AX contains the memory strategy dummy value
Carry flag cleared

If parameter AL == 1 (set strategy)

IF input parameter BX > 2 THEN
    AX = 1
ELSE
    AX = input parameter BX

Comments

This is only a dummy function, added for compatibility.

The @CHIP-RTOS has its own fixed memory strategy.   Memory is always allocated in the following manner:

DOS programs are always loaded into the lowest free memory block in the @CHIP-RTOS heap memory area.   For memory blocks allocated internally in the @CHIP-RTOS or with Int21h 0x48, the @CHIP-RTOS searches for a free memory block starting at the highest heap RAM address.   So the largest free memory block of the system is always located in the middle of the @CHIP-RTOS heap memory area.

The shell command mem shows the state of the internal memory map.

Interrupt 0x21 service 0x62: Get PSP Segment Address

Gets PSP (Program Segment Prefix) segment address

Parameters

AH

0x62

Return Value

BX contains the PSP segment address, if BX=0, PSP was not found

Comments

This function will not work if called from tasks created within programs.

This function is identical to interrupt 0x21 service 0x51.

Interrupt 0x21 service 0x63: Get Leading Byte (stub)

Dummy function, not supported by the IPC@CHIP @CHIP-RTOS

Parameters

AH

0x63

Return Value

Always returns with Carry flag set

AL = 0xFF
DS = 0
SI = 0

Interrupt 0x21 service 0x68: Flush DOS Buffers to Disk

Flush DOS file buffers to disk for specified file.

Parameters

AH

0x68

BX

file handle

Return Value

Success: Carry flag cleared
Failure: Carry flag set, AX holds error code

AX : 2 Invalid handle
AX : 7 I/O error occurred

Related Topics

Create New File Handle

Open Existing File

Close File Handle