Chapter 2 Using the Applications Programmer’s Interface

System Call Error Return Codes

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**
Hex Number	System Call
39	Create a Subdirectory
3A	Remove a Subdirectory
3B	Change Current Directory
3C	Create a File
3D	Open a File
41	Erase a File from Directory
43	Change File Mode
4B	Load or Execute a Program
4E	Find First
56	Rename a File
5A	Create Unique File
5B	Create New File

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**
Handle	Standard Device
0000	Input device
0001	Output device
0002	Error output device
0003	Auxiliary device
0004	List device

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

Undisplayed Graphic

Table 2 3
Standard FCB Fields

Field

Definition

DRIVE

Drives are numbered sequentially starting with zero. Before a file is opened, 0 refers to the default drive, 1 to drive A, 2 to drive B, and so forth. After a file is opened, zero is replaced by the actual drive number.

FILENAME

This field may contain either a filename or a reserved name for a device. Filenames must be left-justified with trailing blanks. If a device name is placed in this field, do not include the colon.

FILE EXTENSION

Must be left-justified with trailing blanks or all blanks.

CURRENT BLOCK

Current block number relative to the beginning of the file, starting with zero. The Open call sets this field to zero. A block is 128 records long. Record size is specified in the following field. The current block number is used with the current record field (see CURREC) for sequential reads and writes.

DATE

Logical record size in bytes. The Open call sets this field to 80H. If your records are not 80H bytes in length you must set this value to the correct value for your file. DR-DOS uses this field to determine locations in the file for all disk reads and writes.

FILE SIZE

File size in bytes. The first word of this four-byte field is the low-order part of the size.

DATE

Date the file was created or last updated. The month, day, and year are mapped in the field as follows:

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
y	y	y	y	y	y	y	m	m	m	m	d	d	d	d	d

where:

mm is 1-12dd is 1-31yy is 0-119 (1980-2099)

RESERVED

Reserved for use by DR-DOS.

CURREC

Current record number in the range 0-127 within the current block (see CURRENT BLOCK). You must set the field before sequential read or write operations. To read the first record of a file, set CURREC to zero. The field is not initialized by the Open File (0FH) call.

RANDREC

Record number relative to the beginning of the file, starting with zero. You must set this two-word field before random read/write operations. The first word of the field contains the low-order part of the record number. Both words are used if the record size is less than 64 bytes, otherwise only the first three bytes are used. The field is not initialized by the Open File call.

If you use the FCB at offset 5CH in the Program Segment Prefix (PSP), the last byte of the RANDREC field overlaps the first byte of the unformatted parameter area in the PSP.

An unopened FCB comprises the FCB prefix (for extended FCBs), the drive number, filename and extension. An opened FCB has the remaining fields filled in by Create File or Open File calls.

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**
Field	Definition
FLAG	Byte containing FFH to indicate an extended FCB.
RESERVED	Reserved for use by DR-DOS.
ATTR	Attribute byte. The attribute byte is defined in Section 2.3.3.

Undisplayed Graphic

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**
Value	Meaning
00H	Indicates a normal file. These files have no special attributes and are not excluded from any directory search.
01H	Indicates that the file is marked read/only. If you use the Open a File Handle call (3DH) to attempt to open a read/only file for output, the call returns an error.
02H	Indicates a hidden file. A file with this attribute is excluded from normal directory searches
04H	Indicates a system file. A file with this attribute is excluded from normal directory searches.
08H	Indicates that an entry contains a volume label in the filename and extension fields. When the attribute byte has this value, a directory entry contains no other usable information and can exist only in the root directory.
10H	Indicates that an entry defines a subdirectory. Such an entry is excluded from normal directory searches.
20H	Indicates that the file has been written to and closed. BACKUP, RESTORE and other file transfer utilities check for this value to determine whether a file has changed since it was last backed up.

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**
Hex	System Call
	Character Device I/O
01	Keyboard Input
02	Console Output
03	Auxiliary Input
04	Auxiliary Output
05	Printer Output
06	Direct Console I/O
07	Direct Console Input
08	Console Input without Echo
09	Print String
0A	Buffered Keyboard Input
0B	Check Console Status
0C	Character Input with Buffer Flush
33	Ctrl-Break Check
	File Management
0D	Disk Reset
0E	Select Disk
0F	Open File
10	Close File
11	Search for First Entry
12	Search for Next Entry
13	Delete File
14	Sequential Read
15	Sequential Write
16	Create File
17	Rename File
19	Current Disk
1A	Set Disk Transfer Address
1B	Allocation Table Address
1C	Allocation Table for Specific Drive
21	Random Read
22	Random Write
23	File Size
24	Set Random Record Field
27	Random Block Read
28	Random Block Write
29	Parse File Name
2E	Set/Reset Verify Switch
2F	Get Disk Transfer Address
36	Get Disk Free Space
54	Get Verify State
	Extended File Management
3C	Create a File
3D	Open a File Handle
3E	Close a File Handle
3F	Read from a File or Device
40	Write to a File or Device
41	Erase a File from Directory
42	Move File Read/Write Pointer
43	Change File Mode
44	Device I/O Control
45	Duplicate a File Handle
46	Force a Duplicate of a File Handle
4E	Find First
4F	Find Next
56	Rename a File
57	Get/Set File Time and Date Stamps
59	Get Extended Error
5A	Create Unique File
5B	Create New File
5C	Lock/Unlock File Access
67	Set Handle Count
68	Commit File
39	Create a Subdirectory
	Directory Management
3A	Remove a Subdirectory
3B	Change Current Directory
47	Get Current Directory
	Miscellaneous
25	Set Vector
30	Get DR-DOS Version Number
35	Get Vector
	Program Control
00	Program Terminate
26	Create a New Program Segment Prefix
31	Keep Process
4B	Execute a Program
4C	Terminate a Process
4D	Get Subprocess Return Code
62	Get Program Segment Prefix Address
	Memory Management
48	Allocate Memory
49	Free Allocated Memory
4A	Modify Allocated Memory Blocks
	Time
2A	Get Date
2B	Set Date
2C	Get Time
2D	Set Time
	Country Information
38	Get/Set Country Dependent Information
65	Get Extended Country Information
66	Get/Set Global Code Page
	Networking
5E00	Get Machine Name
5E02	Set Printer Setup
5E03	Get Printer Setup
5F02	Get Redirection List Entry
5F03	Redirect Device
5F04	Cancel Redirection

[Front] [Prev Chapter] [Next Chapter]

info@caldera.com