www.beck-ipc.com

@CHIP-RTOS - DOS Interface Documentation

    IPC@CHIP® Documentation Index

DOS

DOS API Here are the DOS interface definitions.   DOS uses interrupt 0x21 with a service number in the high order byte of the AX register (AH).

For some useful comments see also under Programming notes

    DOS Interrupt 0x21 Services

    Service is selected by index in AH register.   All implemented DOS services are listed here:
  • 0x00:_Terminate Program
  • 0x02:_Output Character to standard output
  • 0x06:_Direct Console Output
  • 0x07:_Direct Console Input
  • 0x08:_Read Keyboard
  • 0x09:_Send string to standard output
  • 0x0B:_Character Available Test
  • 0x0E:_Set Default Drive
  • 0x19:_Get Current Drive
  • 0x1A:_Set Disk Transfer Area Address
  • 0x25:_Set IRQ Vector
  • 0x2A:_Get System Date
  • 0x2B:_Set System Date
  • 0x2C:_Get System Time
  • 0x2D:_Set System Time
  • 0x2F:_Get Disk Transfer Area Address
  • 0x30:_Get DOS Version
  • 0x31:_Keep Process
  • 0x35:_Get IRQ Vector
  • 0x36:_Get Disk Free Space
  • 0x39:_Create Directory
  • 0x3A:_Remove Directory
  • 0x3B:_Set Current Working Directory
  • 0x3C:_Create New File Handle
  • 0x3D:_Open an Existing File
  • 0x3E:_Close File Handle
  • 0x3F:_Read from File
  • 0x40:_Write to File
  • 0x41:_Delete File
  • 0x42:_Set Current File Position
  • 0x43:_Get/Set File Attributes
  • 0x44:_IOCTL, Set/Get Device Information
  • 0x47:_Get Current Working Directory
  • 0x48:_Allocate Memory
  • 0x49:_Free Allocated Memory
  • 0x4A:_Resize Memory
  • 0x4B:_EXEC
  • 0x4C:_End Process
  • 0x4E:_Find First File
  • 0x4F:_Find Next File
  • 0x50:_Debugger Support
  • 0x51:_Get PSP Segment Address
  • 0x56:_Change Directory Entry, Rename File
  • 0x57:_Get/Set File Date and Time
  • 0x58:_Get/Set memory strategy (dummy function)
  • 0x62:_Get PSP Segment Address
  • 0x63:_Get Leading Byte (stub)
  • 0x68:_Flush DOS Buffers to Disk

    •
    Any service not listed is not supported.   A warning will be issued on the console when an unimplemented DOS interrupt 0x21 service is requested.   If you need a function that is not supported, please let us know at mailto:atchip@beck-ipc.com

    A maximum of 12 DOS programs can be run simultaneously.

    The system supports a maximum of 20 open files.

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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)

    Return Value

    AL = total number of drives on success, else -1

    Related Topics

    Get current drive

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.25V1.25V1.25V1.17V1.17

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    This call is used within your compiler's standard C-library findfirst() function.   Prior to using the findfirst/findnext functions a buffer area must be set with this API.

    Related Topics

    DOS Get Disk Transfer Area address service
    DOS findfirst service
    DOS findnext service

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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)

    Return Value

    AL = 0 if date was accepted
    AL = 0xFF if date was rejected by the limited error checking

    Comments

    This function performs only limited error checking on the entered date.

    Related Topics

    Get system date
    Set system time

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0x21 service 0x2D:     Set System Time

    Sets the system time.

    Parameters

    AH
    0x2D

    CH
    Hour

    CL
    Minute

    DH
    Second

    Return Value

    AL = 0

    Comments

    This function performs no error checking on the entered time values.

    Related Topics

    Set system date
    Get system time

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Related Topics

    DOS Set Disk Transfer Area address service
    DOS findfirst service
    DOS findnext service

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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 !

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Comments

    This service must be invoked by the program's main() task or no operation will be performed.

    The DOSn @Chip-RTOS task supporting this terminating DOS program will be deleted.   The memory allocated from the system by this task will remain allocated and marked as being owned by TSR (Terminate/Stay Resident).

    After this calling program's task has been deleted, the program's memory image will be reduced to the size specified in DX register.   Since this action is taken after the task has been retired, it is safe to delete the programs stack space as well so that the TSR will have a yet smaller memory image following the termination.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    For drives with more than 0xFFFF clusters, the BIOS API alternative function should be used.

    Note:  
      In SC12 @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.

    Related Topics

    BIOS service 0x36 Get Disk Free Space

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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: Drive not found
      3: Path not found
      5: Path exists or access denied

    Related Topics

    Remove Directory

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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: I/O failure
      3: Path not found or too many tasks accessing file system
      5: Access denied: Not a directory, not empty, in use or drive is read-only.

    Comments

    The subdirectory must not contain any files.

    Related Topics

    Create Directory

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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.

    For C language applications, the _dos_getfileattr() and _dos_setfileattr() functions from the standard C-library may be used to access this API.

    Related Topics

    Delete File

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    For SC1x CPU's, a paragraph is 16 bytes in length.

    For SC1x3/SC2x CPU's, a paragraph is 256 bytes in length.

    Related Topics

    Free allocated memory
    Resize memory
    Allocate fast memory
    Reassign memory ownership

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0x21 service 0x4A:     Resize Memory

    Increases or decreases the size of a system memory block.

    Parameters

    AH
    0x4A

    BX
    Desired new size expressed in paragraphs

    ES
    Segment address of memory block (allocated by DOS SWI 0x21 Service 0x48)

    Return Value

    Success: Carry flag cleared

    Failure: Carry flag set due to not enough memory available.   In this case, the size of the largest free block is returned in BX (paragraph count).

    Comments

    For SC1x CPU's, a paragraph is 16 bytes in length.

    For SC1x3/SC2x CPU's, a paragraph is 256 bytes in length.

    Increasing a memory block's size may fail even when there is more heap memory available than requested in register BX.   This can occur when the heap area following the specified memory block (ES register) has already been allocated, leaving insufficient heap space for this block to grow.   Note that this API cannot move the base address of the memory block.

    Related Topics

    Allocate memory
    Free memory

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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 use in child process
                     (system default environment used if 0000h).
    02h    DWORD    Pointer to command tail to be copied into child's PSP
                     The command tail string should be zero terminated.
                     (Command tail pointer not used if NULL.)
    06h    DWORD    Pointer to first FCB (not used)
    0Ah    DWORD    Pointer to second FCB (not used)
    0Eh    DWORD    Will hold subprogram's initial SS:SP on return
    12h    DWORD    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0x21 service 0x4C:     End Process

    Terminates a DOS program.

    Parameters

    AH
    0x4C

    AL
    exit code

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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 (provisional, not used!)

    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 DTA address must be set with interrupt 0x21 function 0x1A before calling this findfirst function.   This is handled by a compiler's C-library code.   The findfirst/findnext sequence is handled by your compiler library so the Disk Transfer Area is therefore not described here.

    SC1x3/SC2x Comments

    The alternative directory scan functions for long file names (LFN) starting with BIOS_LFN_Findfirst can be used to read out the long file names.

    Related Topics

    Find next file
    Fast Findfirst file
    Long file name Findfirst file

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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, AX = 0x12

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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 to set callback
    (Set this to zero if not a debugger calling.)

    Return Value

    DX:BX contains pointer to internal task list.
    AL = Task list length = 12
    AH = Real-Time Interrupt rate in kHz, minus 1 kHz
           (AH = 0 for 1 kHz)
    CX = size of task list elements
    SI = RTOS Private Data Segment
    DI = Offset of RTOS idle counter
    ES = 0x2 (for feature identification)

    Comments

    This function was originally intended only for debugger use, but has since become useful for internal use by the Beck C-Library as well.

    The callback vector in DX:BX is not accepted unless CX = 0x8765.   Only debuggers should set CX to this value.   All other callers should set CX to zero and then the contents of DX:BX registers passed in are not relevant.

    The data structure at returned [SI:DI] pointer consists of two 32 bit unsigned long words, the first of which is the RTOS's idle loop up counter and the second is the RTOS's Real-Time Interrupt (RTI) up counter.   The RTI rate in kHz can be calculated from the value returned in AH register by adding one.

    As with all of the DOS interrupt 0x21 calls, interrupts are enabled on entry into this API.

    Beck C-Library Usage

    RTX_FineTickInit()

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    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.


    Top of list
    Index page
    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:   3 - Drive is write protected
      AX:   4 - New file name already exists
      AX:   7 - Directory update failed
      AX:   9 - File sharing violation
      AX:  11 - Unable to sign caller into file system (too many other tasks are already using the file system)

    Comments

    A file or directory cannot be renamed when it is in use by a task or program.   In these cases, the failure code returned in register AX will be 7.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.23V1.23V1.23V1.16V1.00

    Top of list
    Index page
    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
    AX = File system error code

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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 : 3 Read-only disk drive
      AX : 7 I/O error occurred

    Related Topics

    Create New File Handle
    Open Existing File
    Close File Handle

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page

    End of document