DR-DOS System and Programmer's Guide (original) (raw)

[Front] [Prev Chapter] [Next Chapter]

Chapter 2 Using the Applications Programmer’s Interface

DR-DOS System Call Parameters

System Call Error Return Codes

FCB Oriented File Management

System Call Summary

This section provides the information that is required to use the Caldera DR-DOS function calls and interrupts from applications programs.

2.1 DR-DOS System Call Parameters

Under DR-DOS, a process requests a function by placing the function number in register AH, supplying additional information in other registers as necessary, and then issuing an INT 21H. When DR-DOS takes control, it switches to an internal stack. User registers except AX are preserved, unless information is passed back to the register as indicated in the specific requests. To accommodate the interrupt system, the user stack size should be 80H bytes larger than the program’s internal requirements.

2.1.1 ASCIIZ Input Strings

The system calls listed in Table 2-1 require the address of an ASCIIZ string in registers DS:DX as an input parameter. ASCIIZ strings are ASCII character strings containing an optional drive reference and directory path. In some cases, the strings also include a file name. ASCIIZ strings are delimited by a zero byte or a null (0H) byte. Path names are delimited by a backslash (\) character.

Table 2 1 System Calls Requiring ASCIIZ Strings

2.1.2 File and Device Handles

The functions Create a File (3CH), Open a File (3DH), Duplicate a File Handle (45H) and Create New File (5BH) return a 16-bit binary identifier value in register AX. This identifier is called a “handle”. The handle is used later to identify files or devices that have been opened or created with the system call that originally returned the handle. Table 2-2 lists the handles that are
pre-defined to identify standard devices. Your program can use these handles without previously opening the devices assigned to them.

Table 2 2 Standard Device Handles

2.2 System Call Error Return Codes

When a DR-DOS call operation is successful, most calls clear the Carry flag. If there is an error, these calls set the Carry flag and return an error code in the AX register. Chapter 5, Error Handling, provides a list of the binary error codes returned in register AX.

2.3 FCB Oriented File Management

2.3.1 Standard DR-DOS File Control Block

Figure 2-1 illustrates the standard File Control Block (FCB). Table 2-3 defines the fields in the standard FCB. The fields from offset 10H through offset 1FH (FILESIZE, DATE, and RESERVED) are set by DR-DOS and must not be changed by user programs. All remaining fields of the standard FCB must be set by user programs.

All data in word fields is stored with the least significant byte first.

Figure 2 1
Standard File Control Block

Table 2 3 Standard FCB Fields

2.3.2 Extended File Control Block

Programs can use extended FCBs to create or search for files that have special attributes.

An extended FCB adds a seven-byte prefix to a normal FCB. Figure 2-2 shows the format of the FCB prefix, in which the addresses are offsets from the beginning of a normal FCB. For completeness, the illustration also shows the standard FCB after the prefix.

The fields in the extended FCB are defined in Table 2-4.

Table 2 4 Extended FCB Fields

Figure 2-2
Extended FCB Prefix

2.3.3 File Attribute Byte

A program can assign one or more attributes to a file at the time the file is created. The attribute byte, as it appears in a directory entry or in the prefix of an extended FCB, can have the values listed in Table 2-5.

Table 2 5 Attribute Byte Values

You can use the Change File Mode call (43H) to change the Read/only, Hidden, System, and Archive attributes. A file can have any or all of these four attributes in any combination. You cannot change the volume and subdirectory attributes with Change File Mode.

The description of Search for First Entry (11H) in Chapter 4, DR-DOS System Calls, contains an explanation of how to use the attribute byte in file searches.

2.3.4 Disk Transfer Area (DTA)

DR-DOS uses the Disk Transfer Area (DTA) to store data for all FCB file reads and writes, and some of the other FCB-oriented function calls. These calls include:

Search for First Entry (11H)

Search for Next Entry (12H)

Sequential Read (14H)

Sequential Write (15H)

Random Read (21H)

Random Write (22H)

Random Block Read (27H)

Random Block Write (28H)

When DR-DOS gives control to a DOS program, it establishes a default DTA at offset 80H in the program’s Program Segment Prefix (PSP). See the Load or Execute Program (4BH) call for a description of the PSP.

The default DTA is 128 bytes long. To change the default DTA or establish a new DTA, use the Set Disk Transfer Address call (1AH). DR-DOS allows the DTA to be placed in any location within memory, but it must not cross 64Kb (segment) boundaries.

Once a DTA is established, DR-DOS continues to use that area for all disk operations until a subsequent Set DTA function is performed. You can obtain the current DTA with the Get Disk Transfer Address call (2FH).

2.4 System Call Summary

Table 2-6 lists the system functions supported by DR-DOS. The system calls fall into the following categories:

• Character Device I/O
• File Management
• Extended File Management
• Directory Management
• Miscellaneous
• Program Control
• Memory Management
• Time
• Country Information
• Networking

Table 2 6 System Call Categories and Calls

[Front] [Prev Chapter] [Next Chapter]

info@caldera.com

Copyright © 1993, 1997 Caldera, Inc All rights reserved.