[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

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:

1514131211109876543210
yyyyyyymmmmddddd

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:

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
Copyright © 1993, 1997 Caldera, Inc All rights reserved.