ms-dos-3.3/PROGREF/1D_CALLS.A

_ _  |  |  _ _



 _ ______________


Write Handle (Function 40H)

 Call:

 AH = 40H
 BX
  Handle
 CX
  Bytes to write
 DS:DX
  Pointer to buffer

 Return:

 Carry set:
 AX
  5 = Access denied
  6 = Invalid handle
 Carry not set:
 AX
  Bytes written


Comments:

Function 40H writes to the file or device associated with the specified han-
dle. BX must contain the handle. CX must contain the number of bytes to
be written. DX must contain the offset (to the segment address in DS) of
the data to be written.

If you set CX to zero, the file will be truncated at the current position of
the file pointer. MS-DOS will not perform the write if the handle is read-
only.

If there is no error, AX returns the number of bytes written. Be sure to
check AX after performing a write. If its value is less than the number in
CX when the call was made, it indicates an error, even though the carry
flag isn't set. If AX contains 0, and if the target is a disk file, the disk is
full.

If you use this function request to write to standard output, you can
redirect the output. If you call this request with CX=0, the file size is set
to the value of the read/write pointer. To satisfy the new file size, alloca-
tion units are allocated or released, as required.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code

  1

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

 Meaning
_ ________________________________________________________________

5 Handle not open for writing

6 Handle not open or invalid


Macro Definition:


write_handle macro handle,buffer,bytes
  mov bx,handle
  mov dx,offset buffer
  mov cx,bytes
  mov ah,40H
  int 21H
  endm


Example:

The following program creates a file named dir.tmp, containing the
filename and extension of each file in the current directory, in the current
directory on the disk in drive B.

srch_file db "b:*.*",0
tmp_file db "b:dir.tmp",0
buffer db 43 dup (?)
handle dw ?
;
begin: set_dta buffer ;See Function 1AH
 find_first_file srch_file,16H ;Check directory
 cmp ax,12H ;Directory empty?
 je return ;Yes, go home
 create_handle tmp_file,0 ;See Function 3CH
 jc error_create ;Routine not shown
 mov handle,ax ;Save handle
write_it: write_handle handle,buffer[1EH],12 ;THIS FUNCTION
 jc error_write ;Routine not shown
 find_next_file ;Check directory
 cmp ax,12H ;Another entry?
 je all_done ;No, go home
 jmp write_it ;Yes, write record
all_done: close_handle handle ;See Function 3EH
 jc error_close ;Routine not shown



2

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Delete Directory Entry [Unlink] (Function 41H)

 Call:

 AH = 41H
 DS:DX
  Pointer to pathname

 Return:

 Carry set:
 AX
  2 = File not found
  3 = Path not found
  5 = Access denied
 Carry not set:
  No error



Comments:

Function 41H erases a file by deleting its directory entry. DX must con-
tain the offset (from the segment address in DS) of an ASCIZ string that
specifies the pathname of the file that you want to delete. You cannot use
wildcard characters.

If the file exists and is not read-only, the call deletes it. If there is an error,
the call sets the carry flag (CF) and the error code returns in AX:

Code
 Meaning
_ ________________________________________________________________

2 File doesn't exist, or specifies a directory

3 Path is invalid

5 File is read-only

To delete a file with the read-only attribute, first change its attribute to 0
with Function 43H (Get/Set File Attribute).


  3

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Macro Definition:


delete_entry macro path
  mov dx,offset path
  mov ah,41H
  int 21H
  endm


Example:

The following program deletes all files, dated before December 31, 1986,
from the disk in drive B.

year db 1986
month db 12
day db 31
files db ?
message db "NO FILES DELETED.",0DH,0AH,"$"
path db "b:*.*", 0
buffer db 43 dup (?)
;
begin: set_dta buffer ;See Function 1AH
 select_disk "B" ;See Function 0EH
 find_first_file path,0 ;See Function 4EH
 jnc compare ;got one
 jmp all_done ;no match, go home
compare: convert_date buffer[-1] ;See end of chapter
 cmp cx,year ;After 1986?
 jg next ;Yes, don't delete
 cmp dl,month ;After December?
 jg next ;Yes, don't delete
 cmp dh,day ;31st or after?
 jge next ;Yes, don't delete
 delete_entry buffer[1EH] ;THIS FUNCTION
 jc error_delete ;Routine not shown
 inc files ;Bump file counter
next: find_next_file ;Check directory
 jnc compare ;Go home if done
how_many: cmp files,0 ;Was directory empty?
 je all_done ;Yes, go home
 convert files,10,message ;See end of chapter
all_done: display message ;See Function 09H
 select_disk "A" ;See Function 0EH



4

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Move File Pointer (Function 42H)

 Call:

 AH = 42H
 AL
  Method of moving
 BX
  Handle
 CX:DX
  Distance in bytes (offset)

 Return:

 Carry set:
 AX
  1 = Invalid function
  6 = Invalid handle
 Carry not set:
 DX:AX
  New read/write pointer location


Comments:

Function 42H moves the read/write pointer of the file associated with the
specified handle. BX must contain the handle. CX and DX must contain a
32-bit offset (CX contains the most significant byte). AL must contain a
code that specifies how to move the pointer:

Code
 Cursor Moved to
_ ________________________________________________________________

0 Beginning of file plus the offset

1 Current pointer location plus the offset

2 End of file plus the offset

DX and AX return the new location of the read/write pointer (a 32-bit
integer; DX contains the most significant byte). You can determine the
length of a file by setting CX:DX to 0, AL to 2, and calling this function.
DX:AX returns the offset of the byte following the last byte in the file (size
of the file in bytes).

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________


  5

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

1 AL not 0, 1, or 2

6 Handle not open


Macro Definition:


move_ptr macro handle,high,low,method
  mov bx,handle
  mov cx,high
  mov dx,low
  mov al,method
  mov ah,42H
  int 21H
  endm


Example:

The following program prompts for a letter, converts it to its alphabetic
sequence (A=1, B=2, etc.), then reads and displays the corresponding
record from the file named alphabet.dat that is in the current directory on
the disk in drive B. The file contains 26 records, each 28 bytes long.

file db "b:alphabet.dat",0
buffer db 28 dup (?),"$"
prompt db "Enter letter: $"
crlf db 0DH,0AH,"$"
handle db ?
record_length dw 28
;
begin: open_handle file,0 ;See Function 3DH
 jc error_open ;Routine not shown
 mov handle,ax ;Save handle
get_char: display prompt ;See Function 09H
 read_kbd_and_echo ;See Function 01H
 sub al,41h ;Convert to sequence
 mul byte ptr record_length ;Calculate offset
 move_ptr handle,0,ax,0 ;THIS FUNCTION
 jc error_move ;Routine not shown
 read_handle handle,buffer,record_length
 jc error_read ;Routine not shown
 cmp ax,0 ;End of file?
 je return ;Yes, go home
 display crlf ;See Function 09H
 display buffer ;See Function 09H
 display crlf ;See Function 09H
 jmp get_char ;Get another character



6

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Get/Set File Attributes (Function 43H)

 Call:

 AH = 43H
 AL
  0 = Get attributes
  1 = Set attributes
 CX (if AL=1)
  Attributes to be set
 DS:DX
  Pointer to pathname

 Return:

 Carry set:
 AX
  1 = Invalid function
  2 = File not found
  3 = Path not found
  5 = Access denied
 Carry not set:
 CX
  Attribute byte (if AL=0)


Comments:

Function 43H gets or sets the attributes of a file. DX must contain the
offset (from the segment address in DS) of an ASCIZ string that specifies the
pathname of a file. AL must specify whether to get or set the attribute
(0=get, 1=set).

If AL is 0 (get the attribute), the attribute byte returns in CX. If AL is 1
(set the attribute), CX must contain the attributes to be set. The attri-
butes are described under "File Attributes" earlier in this chapter.

You cannot change the VolumeID bit (08H) or the Subdirectory bit (10H)
of the attribute byte with this function.



  7

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 AL not 0 or 1

2 File doesn't exist

3 Path invalid

5 Attribute in CX cannot be changed (Subdirectory or VolumeID).


Macro Definition:


change_attr macro path,action,attrib
  mov dx,offset path
  mov al,action
  mov cx,attrib
  mov ah,43H
  int 21H
  endm


Example:

The following program displays the attributes assigned to the file named
report.asm that is in the current directory on the disk in drive B.

header db 15 dup (20h),"Read-",0DH,0AH
 db "Filename Only Hidden "
 db "System Volume Sub-Dir Archive"
 db 0DH,0AH,0DH,0AH,"$"
path db "b:report.asm",3 dup (0),"$"
attribute dw ?
blanks db 9 dup (20h),"$"
;
begin: change_attr path,0,0 ;THIS FUNCTION
 jc error_mode ;Routine not shown
 mov attribute,cx ;Save attribute byte
 display header ;See Function 09H
 display path ;See Function 09H
 mov cx,6 ;Check 6 bits (0-5)
 mov bx,1 ;Start with bit 0
chk_bit: test attribute,bx ;Is the bit set?
 jz no_attr ;No
 display_char "X" ;See Function 02H
 jmp short next_bit ;Done with this bit
no_attr: display_char 20h ;See Function 02H
next_bit: display blanks ;See Function 09H
 shl bx,1 ;Move to next bit
 loop chk_bit ;Check it


8

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


IOCtl Data (Function 44H, Codes 0 and 1)

 Call:

 AH = 44H
 AL
  0 = Get device data
  1 = Set device data
 BX
  Handle
 DX
  Device data (see text)

 Return:

 Carry set:
 AX
  1 = Invalid function
  6 = Invalid handle
 Carry not set:
 DX
  Device data


Comments:

Function 44H, Codes 0 and 1, either gets or sets the data MS-DOS uses to
control the device. AL must contain 0 to get the data or 1 to set it. BX
must contain the handle. If AL is 1, DH must contain 0.

The device-data word is specified or returned in DX. If bit 7 of the data is
1, the handle refers to a device and the other bits have the following mean-
ings:


  9

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

Table 0.1

MS-DOS Data Bit Values

_ _________________________________________________________________________

Bit  Value  Meaning 

_ _________________________________________________________________________

0  1  Console input device 
1  1  Console output device 
2  1  Null device 
3  1  Clock device 
4  1  Reserved 
5  1  Don't check for control characters 
  0  Check for control characters 
6  0  End of file on input 
8-10    Reserved 
11  1  Device understands open/close 
12    Reserved 
13  1  Device supports output until busy 
14  1   

 Device can process control strings sent with Function 44H, Codes
 2 and 3 (IOCtl character); bit can be read only, but not set
15    Reserved 

_ _________________________________________________________________________

You must set the reserved bits to zero.

The control characters referred to in the description of bit 5 are
CONTROL-C, CONTROL-P, CONTROL-S, and CONTROL-Z. To read these charac-
ters as data, instead of as control characters, you must set bit 5 and use
either Function 33H, CONTROL-C Check, or the MS-DOS break command
to turn off CONTROL-C checking.

If bit 7 of DX is 0, the handle refers to a file and the other bits have the
following meanings:

Bit  Value  Meaning 

_ ________________________________________________________________

0-5     Drive number (0=A, 1=B, etc.) 
6   0  The file has been written 
8-15     Reserved 

_ ________________________________________________________________



10

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 AL not 0 or 1, or AL is 1 but DH is not 0

6 Handle in BX not open or is invalid


Macro Definition:


ioctl_data macro code,handle
  mov bx,handle
  mov al,code
  mov ah,44H
  int 21H
  endm


Example:

The following program gets the device data for standard output, sets the
bit that specifies not to check for control characters (bit 5), and then
clears the bit.

get equ 0
set equ 1
stdout equ 1
;
begin: ioctl_data get,stdout ;THIS FUNCTION
 jc error ;routine not shown
 mov dh,0 ;clear DH
 or dl,20H ;set bit 5
 ioctl_data set,stdout ;THIS FUNCTION
 jc error ;routine not shown
;
; <control characters now treated as data, or "raw mode">
;
 ioctl_data get,stdout ;THIS FUNCTION
 jc error ;routine not shown
 mov dh,0 ;clear DH
 and dl,0DFH ;clear bit 5
 ioctl_data set,stdout ;THIS FUNCTION
;
; <control characters now interpreted, or "cooked mode">
;



  11

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


IOCtl Character (Function 44H, Codes 2 and 3)

 Call:

 AH = 44H
 AL
  2 = Send control data
  3 = Receive control data
 BX
  Handle
 CX
  Bytes to read or write
 DS:DX
  Pointer to buffer

 Return:

 Carry set:
 AX
  1 = Invalid function
  6 = Invalid handle
 Carry not set:
 AX
  Bytes transferred


Comments:

Function 44H, Codes 2 and 3, sends or receives control data to or from a
character device. AL must contain 2 to send data or 3 to receive. BX must
contain the handle of a character device, such as a printer or serial port.
CX must contain the number of bytes to be read or written. DX must con-
tain the offset (to the segment address in DS) of the data buffer.

AX returns the number of bytes transferred. The device driver must sup-
port the IOCtl interface.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 AL not 2 or 3, or device cannot perform the specified function

6 Handle in BX not open or doesn't exist



12

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


ioctl_char macro code,handle,buffer
  mov bx,handle
  mov dx,offset buffer
  mov al,code
  mov ah,44H
  int 21H
  endm


Example:

No general example is applicable, since processing of IOCtl control data
depends on the device being used, as well as the device driver.


  13

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


IOCtl Block (Function 44H, Codes 4 and 5)

 Call:

 AH = 44H
 AL
  4 = Send control data
  5 = Receive control data
 BL
  Drive number (0=default, 1=A, etc.)
 CX
  Bytes to read or write
 DS:DX
  Pointer to buffer

 Return:

 Carry set:
 AX
  1 = Invalid function
  5 = Invalid drive
 Carry not set:
 AX
  Bytes transferred


Comments:

Function 44H, Codes 4 and 5, sends or receives control data to or from a
block device. AL must contain 4 to send data or 5 to receive. BL must con-
tain the drive number (0=default, 1=A, etc.). CX must contain the
number of bytes to be read or written. DX must contain the offset (to the
segment address in DS) of the data buffer.

AX returns the number of bytes transferred. The device driver must sup-
port the IOCtl interface. To determine whether it does, use Function 44H,
Code 0, to get the device data, and test bit 14; if the bit is set, the driver
supports IOCtl.



14

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 AL not 4 or 5, or device cannot perform the specified function

5 Number in BL not a valid drive number


Macro Definition:


ioctl_status macro code,drive,buffer
  mov bl,drive
  mov dx,offset buffer
  mov al,code
  mov ah,44H
  int 21H
  endm


Example:

No general example is applicable, since processing of IOCtl control data
depends on the device being used, as well as the device driver.


  15

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


IOCtl Status (Function 44H, Codes 6 and 7)

 Call:

 AH = 44H
 AL
  6 = Check input status
  7 = Check output status
 BX
  Handle

 Return:

 Carry set:
 AX
  1 = Invalid function
  5 = Access denied
  6 = Invalid handle
  13 = Invalid data
 Carry not set:
 AL
  00H = Not ready
  0FFH= Ready


Comments:

Function 44H, Codes 6 and 7, checks whether the file or device associated
with a handle is ready. AL must contain 6 to check whether the handle is
ready for input or 7 to check whether the handle is ready for output. BX
must contain the handle.

AL returns the status:

  Meaning for  Meaning for  Meaning for 
Value  Device  Input File  Output File 

_ ________________________________________________________________

00H  Not ready  Pointer is at EOF  Ready 
0FFH  Ready  Ready  Ready 

_ ________________________________________________________________

An output file always returns ready, even if the disk is full.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________


16

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

1 AL not 6 or 7

5 Access denied

6 Number in BX not a valid, open handle

13 Invalid data


Macro Definition:


ioctl_status macro code,handle
  mov bx,handle
  mov al,code
  mov ah,44H
  int 21H
  endm


Example:

The following program displays a message that tells whether the file asso-
ciated with handle 6 is ready for input or whether it is at end-of-file.

stdout equ 1
;
message db "File is "
ready db "ready."
at_eof db "at EOF."
crlf db ODH,OAH
;
begin: write_handle stdout,message,8 ;display message
 jc write_error ;routine not shown
 ioctl_status 6 ;THIS FUNCTION
 jc ioctl_error ;routine not shown
 cmp al,0 ;check status code
 jne not_eof ;file is ready
 write_handle stdout,at_eof,7 ;see Function 40H
 jc write_error ;routine not shown
 jmp all_done ;clean up & go home
not_eof: write_handle stdout,ready,6 ;see Function 40H
all_done: write_handle stdout,crlf,2 ;see Function 40H
 jc write_error ;routine not shown



  17

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


IOCtl Is Changeable (Function 44H, Code 08H)

 Call:

 AH = 44H
 AL = 08H
 BL
  Drive number (0=default, 1=A, etc.)

 Return:

 Carry set:
 AX
  1 = Invalid function
  15 = Invalid drive
 Carry not set:
 AX
  0 = Changeable
  1 = Not changeable



Comments:

Function 44H, Code 08H, checks whether a drive contains a removable or
nonremovable disk. BL must contain the drive number (0=default, 1=A,
etc.). AX returns 0 if the disk can be changed, 1 if it cannot.

This call lets a program determine whether to issue a message to change
disks.

If there is an error, the carry flag (CF) is set and the error code returns in
AX.

Code
 Meaning
_ ________________________________________________________________

1 Device does not support this call

15 Number in BL not a valid drive number

When the call returns error 1 (because the driver doesn't support it), the
caller asssumes that the driver cannot be changed.


18

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


ioctl_change macro drive
  mov bl, drive
  mov al, 08H
  mov ah, 44H
  int 21H
  endm


Example:

The following program checks whether the current drive contains a remov-
able disk. If not, processing continues; if so, the program prompts the user
to replace the disk in the current drive.

stdout equ 1
;
message db "Please replace disk in drive "
drives db "ABCD"
crlf db 0DH,0AH
;
begin: ioctl_change 0 ;THIS FUNCTION
 jc ioctl_error ;routine not shown
 cmp ax,0 ;current drive changeable?
 jne continue ;no, continue processing
 write_handle stdout,message,29 ;see Function 40H
 jc write_error ;routine not shown
 current_disk ;see Function 19H
 xor bx,bx ;clear index
 mov bl,al ;get current drive
 display_char drives[bx] ;see Function 02H
 write_handle stdout,crlf,2 ;see Function 40H
 jc write_error ;routine not shown
continue:
; (Further processing here)



  19

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


IOCtl Is Redirected Block (Function 44H, Code
09H)

 Call:

 AH = 44H
 AL = 09H
 BL
  Drive number (0=default, 1=A, etc.)

 Return:

 Carry set:
 AX
  1 = Invalid function code
  15 = Invalid drive number
 Carry not set:
 DX
  Device-attribute bits



Comments:

Function 44H, Code 09H, checks whether a drive letter refers to a drive on
a Microsoft Networks workstation (local) or is redirected to a server
(remote). BL must contain the drive number (0=default, 1=A, etc.).

If the block device is local, DX returns the attribute word from the device
header. If the block device is remote, only bit 12 (1000H) is set; the other
bits are 0 (reserved).

An application program should not test bit 12, because applications
should not make distinctions between local and remote files (or devices).
Programs should be written so that they will be independent of the loca-
tion of a device that has been removed.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 File sharing must be loaded to use this system call

15 Number in BL not a valid drive number



20

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


ioctl_rblock macro drive
  mov bl, drive
  mov al, 09H
  mov ah, 44H
  int 21H
  endm


Example:

The following program checks whether drive B is local or remote and
displays the appropriate message.

stdout equ 1
;
message db "Drive B: is "
loc db "local."
rem db "remote."
crlf db 0DH,0AH
;
begin: write_handle stdout,message,12 ;display message
 jc write_error ;routine not shown
 ioctl_rblock 2 ;THIS FUNCTION
 jc ioctl_error ;routine not shown
 test dx,1000h ;bit 12 set?
 jnz not_loc ;yes, it's remote
 write_handle stdout,loc,6 ;see Function 40H
 jc write_error ;routine not shown
 jmp done
not_loc: write_handle stdout,rem,7 ;see Function 40H
 jc write_error ;routine not shown
done: write_handle stdout,crlf,2 ;see Function 40H
 jc write_error ;routine not shown



  21

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


IOCtl Is Redirected Handle (Function 44H,
Code 0AH)

 Call:

 AH = 44H
 AL = 0AH
 BX
  Handle

 Return:

 Carry set:
 AX
  1 = Invalid function code
  6 = Invalid handle
 Carry not set:
 DX
  IOCtl bit field



Comments:

Function 44H, Code 0AH, checks whether a handle refers to a file or a dev-
ice on a Microsoft Networks workstation (local) or is redirected to a server
(remote). BX must contain the file handle. DX returns the IOCtl bit field;
bit 15 is set if the handle refers to a remote file or device.

An application program should not test bit 15, because applications
should not make distinctions between local and remote files (or devices).
Programs should be written so that they will be independent of the loca-
tion of a device that has been removed.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 Network must be loaded to use this system call

6 Handle in BX not a valid, open handle



22

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


ioctl_rhandle macro handle
  mov bx, handle
  mov al, 0AH
  mov ah, 44H
  int 21H
  endm


Example:

The following program checks whether handle 5 refers to a local or remote
file or a device and displays the appropriate message.

stdout equ 1
;
message db "Handle 5 is "
loc db "local."
rem db "remote."
crlf db 0DH,0AH
;
begin: write_handle stdout,message,12;display message
 jc write_error ;routine not shown
 ioctl_rhandle 5 ;THIS FUNCTION
 jc ioctl_error ;routine not shown
 test dx,8000h ;bit 15 set?
 jnz not_loc ;yes, it's remote
 write_handle stdout,loc,6 ;see Function 40H
 jc write_error ;routine not shown
 jmp done
not_loc: write_handle stdout,rem,7 ;see Function 40H
 jc write_error ;routine not shown
done: write_handle stdout,crlf,2 ;see Function 40H
 jc write_error ;routine not shown



  23

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


IOCtl Retry (Function 44H, Code 0BH)

 Call:

 AH = 44H
 AL = 0BH
 DX
  Number of retries
 CX
  Wait time

 Return:

 Carry set:
 AX
  1 = Invalid function code
 Carry not set:
  No error



Comments:

Function 44H, Code 0BH, specifies how many times MS-DOS should retry
a disk operation that fails because of a file-sharing violation. DX must
contain the number of retries. CX controls the pause between retries.

MS-DOS retries this type of disk operation three times, unless you use this
system call to specify a different number. After the specified number of
retries, MS-DOS issues Interrupt 24H (Critical-Error-Handler Address) for
the requesting process.

The effect of the delay parameter in CX is machine-dependent because it
specifies how many times MS-DOS should execute an empty loop. The
actual time varies, depending on the processor and clock speed. You can
determine the effect on your machine by using debug. Set the number of
retries to 1 and then time several values of CX.



24

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 File sharing must be loaded to use this system call


Macro Definition:


ioctl_retry macro retries, wait
  mov dx, retries
  mov cx, wait
  mov al, 0BH
  mov ah, 44H
  int 21H
  endm


Example:

The following program sets the number of sharing retries to 10 and
specifies a delay of 1000 between retries.

begin: ioctl_retry 10,1000 ;THIS FUNCTION
 jc error ;routine not shown



  25

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Generic IOCtl (for Handles) (Function 44H,
Code 0CH)

 Call:

 AH = 44H
 AL = 0CH
 BX
  Handle
 CH = 05H
  Category code (printer device)
 CL
  Function (minor) code
 DS:DX
  Pointer to data buffer

 Return:

 Carry set:
 AX
  1 = Invalid function code
 Carry not set:
  No error


Comments:

This call loads and selects code pages for devices on a per-device basis. It
also sets or gets the output iteration count for a printer that supports
"PRINT 'TIL BUSY."

The category code may be one of the following:

Code
 Meaning
_ ________________________________________________________________

00 Unknown device

01 Serial printer

03 Console device

05 Parallel printer

The function code may be one of the following:

Code
 Meaning
_ ________________________________________________________________



26

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

45H Sets iteration count for printer

4AH Select code page

4CH Start prepare list

4DH End prepare list

65H Gets iteration count for printer

6AH Query code page selected

6BH Query code page prepare list

_ ________________________________________________________________

Note

 DS:DX points to a word that contains the new value for the total
 number of output iterations performed before proceeding. Thus,
 DS:DX points to a word that contains the character iteration count for
 the "PRINT 'TIL BUSY" loop. This is the number of times the device
 driver will wait for the device to signal "ready" before acknowledging
 "Device busy."

_ ________________________________________________________________


Macro Definition:


ioctl_handles macro handle,function,category,buffer
  mov ch,05H
  mov cl,function
  mov dx,offset buffer
  mov bx,handle
  mov ah,44H
  mov al,0CH
  int 21H
  endm



  27

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Generic IOCtl (for Devices) (Function 44H,
Code 0DH)

 Call:

 AH = 44H
 AL = 0DH
 BL
  Drive number
  (0 = default, 1 = A, etc.)
 CH = 08H
  Category (major) code
 CL
  Function (minor) code
 DS:DX
  Pointer to parameter block -1

 Return:

 Carry set:
 AX
  1 = Invalid function code
  2 = Invalid drive
 Carry not set:
  No error


Comments:

The function code may be one of the following:

Code
 Meaning
_ ________________________________________________________________

40 Set device parameters

41 Write track on logical device

42 Format track on logical device

60 Get device parameters

61 Read track on logical device

62 Verify track on logical device

_ ________________________________________________________________

Note

 You must issue "Set Device Parameters" before you can read, write,
 format, or verify a logical drive.

28

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

_ ________________________________________________________________

You should use the following procedure when you want to read, write, for-
mat, or verify a logical drive:

 o Save drive parameters using "Get Device Parameters;"

 o Set desired drive parameters using "Set Device Parameters;"

 o Perform the I/O operation;

 o Restore the original drive parameters using "Set Device Parame-
 ters."


Set Device Parameters (Function 44 0DH, CL=40H)

When CL=40H, the parameter block has the following field format:

 --------------------------------------
 | BYTE Special Functions |
 |------------------------------------|
 | BYTE Device Type |
 |------------------------------------|
 | WORD Device Attributes |
 |------------------------------------|
 | WORD Number of Cylinders |
 |------------------------------------|
 | BYTE Media Type |
 |------------------------------------|
 | Device BPB |
 |------------------------------------|
 | Track Layout |
 --------------------------------------

These fields have the following meanings:

Special Functions

Bit  Value  Meaning 

_ ________________________________________________________________

 0   0   

 The Device BPB (BIOS Parameter Block) field contains
 the new default BPB for this device. If a previous "Set
 Parameter Device" call set this bit, Build BPB returns
 the actual media BPB; otherwise, it returns the default
 BPB for the device.

    1   

 All subsequent Build BPB requests return the device
 BPB.

 1   0  Read all fields of the parameter block. 



  29

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

    1   

 Ignore all fields of the parameter block except for the
 Track Layout field.

 2   0   

 The sectors in the track may not all be the same size.
 (You should not use this setting.)

    1   

 The sectors in the track are all the same size and the
 sector numbers range between 1 and the total number of
 sectors actually in the track. You should always set this
 bit.

 3-7   0  These bits must be zero. 

_ ________________________________________________________________


Device Type

This byte describes the physical device and is set by the device. When set,
it has the following meanings:

Value
 Meaning
_ ________________________________________________________________

0 320/360 KB

1 1.2 MB

2 720 KB

3 8-inch, single-density

4 8-inch, double-density

5 Hard disk

6 Tape drive

7 Other


Device Attributes

Bit  Value  Meaning 

_ ________________________________________________________________

    0  The media is removable. 

 0   1  The media is not removable. 

 1   0   

 Disk change-line is not
 supported; (no door lock
 support).

    1   

 Disk change-line is
 supported; (door lock
 support).

 2-7   0  These bits must be zero. 

_ ________________________________________________________________


30

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Number of Cylinders

This field indicates the maximum number of cylinders that the physical
device can support. This information is set by the device.

Media Type

For drives that may contain different media, this field (which is device-
dependent) indicates which media the drive expects.

For a 1.2 MB disk, bit zero has the following meaning:

Bit  Value  Meaning 

_ ________________________________________________________________

 0   0  Quad-density, 1.2 MB disk 

    1  Double-density, 320/360 KB disk 

_ ________________________________________________________________

The default media type is a quad-density 1.2 MB disk.

Device BPB

If bit 0 of the Special Functions field is clear, the BPB in this field is the
new default BPB for the device.

If bit 0 of the Special Functions field is set, the device driver returns the
BPB from this field for subsequent Build BPB requests.

Track Layout

This field contains a table of variable length for each logical device and
indicates the expected layout of the sectors on the media track. The field
has the following format:

 ------------------------------------------------
 | WORD Sector Count -- total # of sectors |
 |----------------------------------------------|
 | WORD Sector Number -- sector #1 |
 |----------------------------------------------|
 | WORD Sector Size -- sector #1 |
 |----------------------------------------------|
 | WORD Sector Number -- sector #2 |
 |----------------------------------------------|
 | WORD Sector Size -- sector #2 |
 ------------------------------------------------
 |
 |
 |

  31

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

 ------------------------------------------------
 | WORD Sector Number -- sector #n |
 |----------------------------------------------|
 | WORD Sector Size -- sector #n |
 ------------------------------------------------

The Sector Count field indicates the total number of sectors. Each sector
number must be unique and in the range of 1 to sector count (n).

If bit 2 of the Special Functions field is set, all sector sizes must be the
same.

Get Device Parameters (Function 440DH, CL=60H)

When CL=60H, the parameter block has the same field layout as for
CL=40H. However, some of the fields have different meanings. These are
described as follows:

Special Functions

Bit  Value  Meaning 

_ ________________________________________________________________

 0   0  Returns the default BPB for the device. 

    1   

 Returns the BPB that Build BPB
 would return.

 1-7   0  These bits must be zero. 

_ ________________________________________________________________


Track Layout

The "Get Device Parameters" call does not use this field.

Read/Write Track on Logical Drive
(Function 440D, CL=61H/CL=41H)

To write to a track on a logical drive, set CL=41H. To read a track on a
logical drive, set CL=61H.

When CL=41H or 61H, the parameter block has the following format:

 --------------------------------
 | BYTE Special Functions |
 |------------------------------|
 | WORD Head |
 |------------------------------|
 | WORD Cylinder |
 |------------------------------|

32

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

 | WORD First Sector |
 |------------------------------|
 | WORD Number of Sectors |
 |------------------------------|
 | DWORD Transfer Address |
 --------------------------------

These fields are described as follows:

Special Functions This byte must be zero.

Head

This field contains the number of the head on which you perform the write
or read.

Cylinder

This field contains the number of the cylinder on which you perform the
write or read.

First Sector

This field contains the number of the first sector on which you perform the
write or read. Sectors are numbered starting with zero, so the fourth sec-
tor is numbered 3.

Number of Sectors

This field contains the total number of sectors.

Transfer Address

This field contains the address for storing the data to be written or the
data just read.

Format/Verify Track on Logical Drive
(Function 440DH, CL=42/CL=62)

To format and verify a track on a logical drive, set CL=42H. To verify a
track on a logical drive, set CL=62H.



  33

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

When CL=42H or 62H, the parameter block has the following format:

 --------------------------------
 | BYTE Special Functions |
 |------------------------------|
 | WORD Head |
 |------------------------------|
 | WORD Cylinder |
 --------------------------------

These fields are described as follows:

Special Functions

This byte must be zero.

Head

This field contains the number of the head on which you perform the for-
mat or verify.

Cylinder

This field contains the number of the cylinder on which you perform the
format or verify.


34

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Get/Set IOCtl Drive Map (Function 44H,
Codes 0EH and 0FH)

 Call:

 AH = 44H
 AL
  OEH = Get logical drive map
  OFH = Set logical drive map
 BX
  Drive number
  (0 = default, 1 = A, etc.)

 Return:

 Carry set:
 AX
  1 = Invalid function code
  5 = Invalid drive
 Carry not set:
 AL = Logical drive mapped onto physical drive
  (= 0 if only one drive is
  assigned to this physical drive)


Comments:

MS-DOS 3.3 supports the mapping of multiple logical drives onto a single
physical block device. Get IOCtl Drive Map lets you query the DOS about
which logical drive is currently mapped onto the corresponding physical
device. Set IOCtl Drive Map alters the device that is currently mapped
onto the physical device. These functions are only useful if there is more
than one logical block device mapped onto a single physical device.

A possible use for these functions is with applications that want to disable
the DOS prompt in order to place the correct floppy disk in the drive when
accessing the other logical drive.

To detect whether a logical device currently owns the physical device it is
mapped to, a program needs to check the value in AL after calling Func-
tion 440EH or 440FH (Get/Set IOCtl Drive Map).


  35

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Duplicate File Handle (Function 45H)

 Call:

 AH = 45H
 BX
  Handle

 Return:

 Carry set:
 AX
  4 = Too many open files
  6 = Invalid handle
 Carry not set:
 AX
  New handle



Comments:

Function 45H creates an additional handle for a file. BX must contain the
handle of an open file.

MS-DOS returns the new handle in AX. The new handle refers to the same
file as the handle in BX, with the file pointer at the same position.

After you use this function request, moving the read/write pointer of
either handle also moves the pointer for the other handle. You usually use
this function request to redirect standard input (handle 0) and standard
output (handle 1). For a description of standard input, standard output,
and the advantages and techniques of manipulating them, see Software
Tools by Brian W. Kernighan and P.J. Plauger (Addison-Wesley Publish-
ing Co., 1976).

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

4 Too many open files (no handle available)

6 Handle not open or is invalid



36

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


xdup macro handle
 mov bx,handle
 mov ah,45H
 int 21H
 endm


Example:

The following program redirects standard output (handle 1) to a file
named dirfile, invokes a second copy of command.com to list the directory
(which writes the directory to dirfile), and then restores standard input to
handle 1.

pgm_file db "command.com",0
cmd_line db 9,"/c dir /w",0dH
parm_blk db 14 dup (0)
path db "dirfile",0
dir_file dw ? ; For handle
sav_stdout dw ? ; For handle
;
begin: set_block last_inst ; See Function 4AH
 jc error_setblk ; Routine not shown
 create_handle path,0 ; See Function 3CH
 jc error_create ; Routine not shown
 mov dir_file,ax ; Save handle
 xdup 1 ; THIS FUNCTION
 jc error_xdup ; Routine not shown
 mov sav_stdout,ax ; Save handle
 xdup2 dir_file,1 ; See Function 46H
 jc error_xdup2 ; Routine not shown
 exec pgm_file,cmd_line,parm_blk ; See Function
 4BH
 jc error_exec ; Routine not shown
 xdup2 sav_stdout,1 ; See Function 46H
 jc error_xdup2 ; Routine not shown
 close_handle sav_stdout ; See Function 3EH
 jc error_close ; Routine not shown
 close_handle dir_file ; See Function 3EH
 jc error_close ; Routine not shown



  37

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Force Duplicate File Handle (Function 46H)

 Call:

 AH = 46H
 BX
  Handle
 CX
  Second handle

 Return:

 Carry set:
 AX
  4 = Too many open files
  6 = Invalid handle
 Carry not set:
  No error



Comments:

Function 46H forces a specified handle to refer to the same file as a second
handle already associated with an open file. BX must contain the handle
of the open file; CX must contain the second handle.

On return, the handle in CX now refers to the same file at the same posi-
tion as the handle in BX. If the file referred to by the handle in CX was
open at the time of the call, this function closes it.

After you use this call, moving the read/write pointer of either handle also
moves the pointer for the other handle. Normally, you would use this
function request to redirect standard input (handle 0) and standard out-
put (handle 1). For a description of standard input, standard output, and
the advantages and techniques of manipulating them, see Software Tools
by Brian W. Kernighan and P.J. Plauger (Addison-Wesley Publishing Co.,
1976).



38

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

4 Too many open files (no handle available)

6 Handle not open or is invalid


Macro Definition:


xdup2 macro handle1,handle2
 mov bx,handle1
 mov cx,handle2
 mov ah,46H
 int 21H
 endm


Example:

The following program redirects standard output (handle 1) to a file
named dirfile, invokes a second copy of command.com to list the directory
(which writes the directory to dirfile), and then restores standard input to
handle 1.

pgm_file db "command.com",0
cmd_line db 9,"/c dir /w",0dH
parm_blk db 14 dup (0)
path db "dirfile",0
dir_file dw ? ; For handle
sav_stdout dw ? ; For handle
;
begin: set_block last_inst ; See Function 4AH
 jc error_setblk ; Routine not shown
 create_handle path,0 ; See Function 3CH
 jc error_create ; Routine not shown
 mov dir_file,ax ; Save handle
 xdup 1 ; See Function 45H
 jc error_xdup ; Routine not shown
 mov sav_stdout,ax ; Save handle
 xdup2 dir_file,1 ; 
 jc error_xdup2 ; Routine not shown
 exec pgm_file,cmd_line,parm_blk ; See Function
 4BH
 jc error_exec ; Routine not shown
 xdup2 sav_stdout,1 ; THIS FUNCTION
 jc error_xdup2 ; Routine not shown
 close_handle sav_stdout ; See Function 3EH
 jc error_close ; Routine not shown
 close_handle dir_file ; See Function 3EH
 jc error_close ; Routine not shown

  39

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Get Current Directory (Function 47H)

 Call:

 AH = 47H
 DS:SI
  Pointer to 64-byte memory area
 DL
  Drive number
  (0 = default, 1 = A)

 Return:

 Carry set:
 AX
  15 = Invalid drive number
 Carry not set:
  No error



Comments:

Function 47H returns the pathname of the current directory on a specified
drive. DL must contain a drive number (0=default, 1=A, etc.). SI must
contain the offset (from the segment address in DS) of a 64-byte memory
area.

MS-DOS places an ASCIZ string in the memory area, consisting of the path
(starting from the root directory) of the current directory for the drive
specified in DL. The string does not begin with a backslash and does not
include the drive letter.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

15 Number in DL not a valid drive number



40

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


get_dir macro drive,buffer
  mov dl,drive
  mov si,offset buffer
  mov ah,47H
  int 21H
  endm


Example:

The following program displays the current directory that is on the disk in
drive B.

disk db "b:
buffer db 64 dup (?)
;
begin: get_dir 2,buffer ;THIS FUNCTION
 jc error_dir ;Routine not shown
 display disk ;See Function 09H
 display_asciz buffer ;See end of chapter



  41

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Allocate Memory (Function 48H)

 Call:

 AH = 48H
 BX
  Paragraphs of memory requested

 Return:

 Carry set:
 AX
  7 = Memory-control blocks damaged
  8 = Insufficient memory
 BX
  Paragraphs of memory available
 Carry not set:
 AX
  Segment address of allocated memory



Comments:

Function 48H tries to allocate the specified amount of memory to the
current process. BX must contain the number of paragraphs of memory
(one paragraph is 16 bytes).

If sufficient memory is available to satisfy the request, AX returns the seg-
ment address of the allocated memory (the offset is 0). If sufficient memory
is not available, BX returns the number of paragraphs of memory in the
largest available block.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

7 Memory-control blocks damaged (a user program changed memory
 that doesn't belong to it)

8 Not enough free memory to satisfy the request



42

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


allocate_memory macro bytes
   mov bx,bytes
   mov cl,4
   shr bx,cl
   inc bx
   mov ah,48H
   int 21H
   endm


Example:

The following program opens the file named textfile.asc, calculates its size
with Function 42H (Move File Pointer), allocates a block of memory the
size of the file, reads the file into the allocated memory block, and then
frees the allocated memory.

path db "textfile.asc",0
msg1 db "File loaded into allocated memory block.",
 0DH,0AH
msg2 db "Allocated memory now being freed
 (deallocated).",0DH,0AH
handle dw ?
mem_seg dw ?
file_len dw ?
;
begin: open_handle path,0
 jc error_open ;Routine not shown
 mov handle,ax ;Save handle
 move_ptr handle,0,0,2 ;See Function 42H
 jc error_move ;Routine not shown
 mov file_len,ax ;Save file length
 set_block last_inst ;See Function 4AH
 jc error_setblk ;Routine not shown
 allocate_memory file_len ;THIS FUNCTION
 jc error_alloc ;Routine not shown
 mov mem_seg,ax ;Save address of new memory
 move_ptr handle,0,0,0 ;See Function 42H
 jc error_move ;Routine not shown
 push ds ;Save DS
 mov ax,mem_seg ;Get segment of new memory
 mov ds,ax ;Point DS at new memory
 read_handle cs:handle,0,cs:file_len ;Read file into
; new memory
 pop ds ;Restore DS
 jc error_read ;Routine not shown
; (CODE TO PROCESS FILE GOES HERE)
 write_handle stdout,msg1,42 ;See Function 40H
 jc write_error ;Routine not shown
 free_memory mem_seg ;See Function 49H
 jc error_freemem ;Routine not shown
 write_handle stdout,msg2,49 ;See Function 40H

  43

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

 jc write_error ;Routine not shown



44

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Free Allocated Memory (Function 49H)

 Call:

 AH = 49H
 ES
  Segment address of memory to be
  freed

 Return:

 Carry set:
 AX
  7 = Memory-control blocks damaged
  9 = Incorrect segment
 Carry not set:
  No error



Comments:

Function 49H frees (makes available) a block of memory previously allo-
cated with Function 48H (Allocate Memory). ES must contain the segment
address of the memory block to be freed.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

7 Memory-control blocks damaged (a user program changed memory
 that didn't belong to it)

9 Memory pointed to by ES was not allocated with Function 48H


Macro Definition:


free_memory macro seg_addr
  mov ax,seg_addr
  mov es,ax
  mov ah,49H
  int 21H
  endm



  45

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Example:

The following program opens a file named textfile.asc, calculates its size
with Function 42H (Move File Pointer), allocates a block of memory the
size of the file, reads the file into the allocated memory block, and then
frees the allocated memory.

path db "textfile.asc",0
msg1 db "File loaded into allocated memory block.",
 0DH,0AH
msg2 db "Allocated memory now being freed
 (deallocated).",0DH,0AH
handle dw ?
mem_seg dw ?
file_len dw ?
;
begin: open_handle path,0
 jc error_open ;Routine not shown
 mov handle,ax ;Save handle
 move_ptr handle,0,0,2 ;See Function 42H
 jc error_move ;Routine not shown
 mov file_len,ax ;Save file length
 set_block last_inst ;See Function 4AH
 jc error_setblk ;Routine not shown
 allocate_memory file_len ;See Function 48H
 jc error_alloc ;Routine not shown
 mov mem_seg,ax ;Save address of new memory
 mov_ptr handle,0,0,0 ;See Function 42H
 jc error_move ;Routine not shown
 push ds ;Save DS
 mov ax,mem_seg ;Get segment of new memory
 mov ds,ax ;Point DS at new memory
 read_handle handle,code,file_len ;Read file into
; new memory
 pop ds ;Restore DS
 jc error_read ;Routine not shown
; (CODE TO PROCESS FILE GOES HERE)
 write_handle stdout,msg1,42 ;See Function 40H
 jc write_error ;Routine not shown
 free_memory mem_seg ;THIS FUNCTION
 jc error_freemem ;Routine not shown
 write_handle stdout,msg2,49 ;See Function 40H
 jc write_error ;Routine not shown



46

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Set Block (Function 4AH)

 Call:

 AH = 4AH
 BX
  Paragraphs of memory
 ES
  Segment address of memory area

 Return:

 Carry set:
 AX
  7 = Memory-control blocks damaged
  8 = Insufficient memory
  9 = Incorrect segment
 BX
  Paragraphs of memory available
 Carry not set:
  No error


Comments:

Function 4AH changes the size of a memory-allocation block. ES must
contain the segment address of the memory block. BX must contain the
new size of the memory block, in paragraphs (one paragraph is 16 bytes).

MS-DOS attempts to change the size of the memory block. If the call fails
on a request to increase memory, BX returns the maximum size (in para-
graphs) to which the block can be increased.

Since MS-DOS allocates all available memory to a .com program, you
would use this call most often to reduce the size of a program's initial
memory-allocation block.



  47

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

7 Memory-control blocks destroyed (a user program changed memory
 that didn't belong to it)

8 Not enough free memory to satisfy the request

9 Wrong address in ES (the memory block it points to cannot be
 modified with Set Block)

The following macro shrinks the initial memory-allocation block of a .com
program. It takes as a parameter the offset of the first byte following the
last instruction of a program (LAST_INST in the sample programs), uses
it to calculate the number of paragraphs in the program, and then adds 17
to the result: one to round up and 16 to set aside 256 bytes for a stack. It
then sets up SP and BP to point to this stack.

Macro Definition:


set_block macro last_byte
  mov bx,offset last_byte
  mov cl,4
  shr bx,cl
  add bx,17
  mov ah,4AH
  int 21H
  mov ax,bx
  shl ax,cl
  dec ax
  mov sp,ax
  mov bp,sp
  endm


Example:

The following program invokes a second copy of command.com and exe-
cutes a dir (directory) command.

pgm_file db "command.com",0
cmd_line db 9,"/c dir /w",0DH
parm_blk db 14 dup (?)
reg_save db 10 dup (?)
;
begin: set_block last_inst ;THIS FUNCTION
 exec pgm_file,cmd_line,parm_blk,0 ;See Function
 ;4BH



48

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Load and Execute Program (Function 4BH,
Code 00H)

 Call:

 AH = 4BH
 AL = 00H
 DS:DX
  Pointer to pathname
 ES:BX
  Pointer to parameter block

 Return:

 Carry set:
 AX
  1 = Invalid function
  2 = File not found
  3 = Path not found
  4 = Too many open files
  5 = Access denied
  8 = Insufficient memory
  10 = Bad environment
  11 = Bad format
 Carry not set:
  No error


Comments:

Function 4BH, Code 00H, loads and executes a program. DX must contain
the offset (from the segment address in DS) of an ASCIZ string that specifies
the drive and pathname of an executable program file. BX must contain
the offset (from the segment address in ES) of a parameter block. AL must
contain 0.

There must be enough free memory for MS-DOS to load the program file.
MS-DOS allocates all available memory to a program when it loads it, so
you must free some memory with Function 4AH (Set Block) before using
this function request to load and execute another program. Unless you or
MS-DOS needs the memory for some other purpose, you should shrink the
memory to the minimum amount required by the current process before
issuing this request.

MS-DOS creates a Program Segment Prefix for the program being loaded
and sets the terminate and CONTROL-C addresses to the instruction that
immediately follows the call to Function 4BH in the invoking program.


  49

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

The parameter block consists of four addresses:

Table 0.2

Contents of the Parameter Block

_ _________________________________________________________________________

Offset  Length   
(Hex)  (Bytes)  Description 

_ _________________________________________________________________________

00  2 (word)   

 Segment address of the environment to be passed; 00H
 means copy the parent program's environment.

02  4 (dword)   

 Segment: Offset of command line to be placed at offset 80H
 of the new Program Segment Prefix. Must be a correctly-
 formed command line no longer than 128 bytes.

06  4 (dword)   

 Segment: Offset of FCB to be placed at offset 5CH of the
 new Program Segment Prefix (the Program Segment Prefix
 is described in Chapter 4, "MS-DOS Control Blocks and
 Work Areas")

0A  4 (dword)   

 Segment: Offset of FCB to be placed at offset 6CH of the
 new Program Segment Prefix

_ _________________________________________________________________________

All open files of a program are available to the newly loaded program, giv-
ing the parent program control over the definition of standard input, out-
put, auxiliary, and printer devices. For example, a program could write a
series of records to a file, open the file as standard input, open a second file
as standard output, and then use Function 4BH, Code 00H (Load and Exe-
cute Program) to load and execute a program that takes its input from
standard input, sorts records, and writes to standard output.

The loaded program also receives an environment, a series of ASCIZ strings
of the form parameter=value (for example, verify= on). The environment
must begin on a paragraph boundary, be less than 32K bytes long, and
end with a byte of 00H (that is, the final entry consists of an ASCIZ string
followed by two bytes of 00H). Following the last byte of zeros is a set of
initial arguments passed to a program containing a word count followed
by an ASCIZ string. If the call finds the file in the current directory, the
ASCIZ string contains the drive and pathname of the executable program as
passed to Function 4BH. If the call finds the file in the path, it concaten-
ates the filename with the path information. (A program may use this area
to determine whence it was loaded.) If the word-environment address is 0,
the loaded program either inherits a copy of the parent program's environ-
ment or receives a new environment built for it by the parent.

Place the segment address of the environment at offset 2CH of the new
Program Segment Prefix. To build an environment for the loaded pro-
gram, put it on a paragraph boundary and place the segment address of
the environment in the first word of the parameter block. To pass a copy
of the parent's environment to the loaded program, put 00H in the first

50

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

word of the parameter block.

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 AL not 0 or 3

2 Program file not found

3 Path invalid or not found

4 Too many open files (no handle available)

5 Directory full, a directory with the same name exists, or a file with
 the same name exists

8 Not enough memory to load the program

10 Environment appears longer than 32K

11 Program file is an .exe file that contains internally inconsistent
 information


Executing Another Copy of Command.com

Since command.com builds pathnames, searches command paths for pro-
gram files, and relocates .exe files, the simplest way to load and execute
another program is to load and execute an additional copy of
command.com, passing it a command line that includes the /c switch,
which invokes the .com or .exe file.

This action requires 17K bytes of available memory, so a program that
does it should be sure to shrink its initial memory-allocation block with
Function 4AH (Set Block). The format of a command line that contains
the /c switch:

length,/c command,0DH

Length is the length of the command line, counting the length byte but not
the ending carriage-return (0DH).

Command is any valid MS-DOS command.

0DH is a carriage-return character.

If a program executes another program directly\(emnaming it as the program
file to Function 4BH instead of command.com\(emit must perform all the
processing normally done by command.com.


  51

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Macro Definition:


exec macro path,command,parms
 mov dx,offset path
 mov bx,offset parms
 mov word ptr parms[02H],offset command
 mov word ptr parms[04H],cs
 mov word ptr parms[06H],5CH
 mov word ptr parms[08H],es
 mov word ptr parms[0AH],6CH
 mov word ptr parms[0CH],es
 mov al,0
 mov ah,4BH
 int 21H
 endm


Example:

The following program invokes a second copy of command.com and exe-
cutes a dir (directory) command by using the /w (wide) switch:

pgm_file db "command.com",0
cmd_line db 9,"/c dir /w",0DH
parm_blk db 14 dup (?)
reg_save db 10 dup (?)
;
begin:
 set_block last_inst ;See Function 4AH
 exec pgm_file,cmd_line,parm_blk,0 ;THIS FUNCTION



52

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Load Overlay (Function 4BH, Code 03H)

 Call:

 AH = 4BH
 AL = 03H
 DS:DX
  Pointer to pathname
 ES:BX
  Pointer to parameter block

 Return:

 Carry set:
 AX
  1 = Invalid function
  2 = File not found
  3 = Path not found
  4 = Too many open files
  5 = Access denied
  8 = Insufficient memory
  10 = Bad environment
 Carry not set:
  No error


Comments:

Function 4BH, Code 03H, loads a program segment (overlay). DX must
contain the offset (from the segment address in DS) of an ASCIZ string that
specifies the drive and pathname of the program file. BX must contain the
offset (from the segment address in ES) of a parameter block. AL must
contain 3.

MS-DOS assumes that since the invoking program is loading into its own
address space, it requires no free memory. This call does not create a Pro-
gram Segment Prefix.



  53

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________

The parameter block is four bytes long:


Table 0.3

Contents of the Parameter Block

_ _________________________________________________________________________

Offset  Length   
(Hex)  (Bytes)  Description 

_ _________________________________________________________________________

00  2 (word)  Segment address where program is to be loaded 

02  2 (word)   

 Relocation factor; usually the same as the first word of the
 parameter block (for a description of an .exe file and of
 relocation, see Chapter 6, ".Exe File Structure and
 Loading.")

_ _________________________________________________________________________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

1 AL not 00H or 03H

2 Program file not found

3 Path invalid or not found

4 Too many open files (no handle available)

5 Directory is full, a directory with the same name exists, or a file
 with the same name exists

8 Not enough memory to load the program

10 Environment appears longer than 32K


Macro Definition:


exec_ovl macro path,parms,seg_addr
  mov dx,offset path
  mov bx,offset parms
  mov parms,seg_addr
  mov parms[02H],seg_addr
  mov al,3
  mov ah,4BH
  int 21H
  endm



54

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Example:

The following program opens a file named textfile.asc, redirects standard
input to that file, loads more.com as an overlay, and calls an overlay
named bit.com, which reads textfile.asc as standard input. The overlay
must establish its own addressability and end with a FAR return.

stdin equ 0
;
file db "TEXTFILE.ASC",0
cmd_file db "\bit.com",0
parm_blk dw 4 dup (?)
overlay label dword
 dw 0
handle dw ?
new_mem dw ?
;
begin: set_block last_inst ;see Function 4AH
 jc setblock_error ;routine not shown
 allocate_memory 2000 ;see Function 48H
 jc allocate_error ;routine not shown
 mov new_mem,ax ;save seg of memory
 open_handle file,0 ;see Function 3DH
 jc open_error ;routine not shown
 mov handle,ax ;save handle
 xdup2 handle,stdin ;see Function 45H
 jc dup2_error ;routine not shown
 close_handle handle ;see Function 3EH
 jc close_error ;routine not shown
 mov ax,new_mem ;addr of new memory
 exec_ovl cmd_file,parm_blk,ax ;THIS FUNCTION
 jc exec_error ;routine not shown
 call overlay ;call the overlay
 free_memory new_mem ;see Function 49H
 jc free_error ;routine not shown
;



  55

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


End Process (Function 4CH)

 Call:

 AH = 4CH
 AL
  Return code

 Return:

 None



Comments:

Function 4CH terminates a process and returns to MS-DOS. AL contains a
return code that can be retrieved by the parent process with Function 4DH
(Get Return Code of Child Process) or the if command, using errorlevel.

MS-DOS closes all open handles, ends the current process, and returns
control to the invoking process.

This function request doesn't require CS to contain the segment address of
the Program Segment Prefix. You should use it to end a program (rather
than Interrupt 20H or a jump to location 0) unless your program must be
compatible with MS-DOS versions before 2.0.

_ ________________________________________________________________

Note

 If you use file sharing, you must remove all locks issued by this process
 or the DOS will be in an uncertain state.

_ ________________________________________________________________



56

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Macro Definition:


end_process macro return_code
  mov al,return_code
  mov ah,4CH
  int 21H
  endm


Example:

The following program displays a message and returns to MS-DOS with a
return code of 8. It uses only the opening portion of the sample program
skeleton shown at the beginning of this chapter.

message db "Displayed by FUNC_4CH example",0DH,0AH,"$"
;
begin: display message ;See Function 09H
 end_process 8 ;THIS FUNCTION
code ends
 end code



  57

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Get Return Code of Child Process (Function
4DH)

 Call:

 AH = 4DH

 Return:

 AX
  Return code



Comments:

Function 4DH retrieves the return code specified when a child process ter-
minates via either Function 31H (Keep Process) or Function 4CH (End
Process). The code returns in AL. AH returns a code that specifies why the
program ended:

Code
 Meaning
_ ________________________________________________________________

0 Normal termination

1 Terminated by CONTROL-C

2 Critical device error

3 Function 31H (Keep Process)

This call can retrieve the exit code only once.

Macro Definition:


ret_code macro
  mov ah,4DH
  int 21H
  endm

58

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Example:

No example is included for this function request, because the meaning of a
return code varies.


  59

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Find First File (Function 4EH)

 Call:

 AH = 4EH
 DS:DX
  Pointer to pathname
 CX
  Attributes to match

 Return:

 Carry set:
 AX
  2 = File not found
  3 = Path not found
  18 = No more files
 Carry not set:
  No error



Comments:

Function 4EH searches the current or specified directory for the first entry
that matches the specified pathname. DX must contain the offset (from the
segment address in DS) of an ASCIZ string that specifies the pathname,
which can contain wildcard characters. CX must contain the attribute to
be used in searching for the file, as described in Section 1.5.5, "File Attri-
butes," earlier in this chapter.

If the attribute field is hidden file, system file, or subdirectory entry (02H,
04H, or 10H), or any combination of these values, all normal file entries
are also searched. To search all directory entries except the volume label,
set the attribute byte to 16H (hidden file, system file, and directory entry).



60

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________

If this function finds a directory entry that matches the name and attri-
bute, it fills the current DTA as follows:


Table 0.4



_ _________________________________________________________________________

Offset  Length  Description 

_ _________________________________________________________________________

00H  21  Reserved for subsequent Function 4FH (Find Next File)  

15H  1  Attribute found 

16H  2  Time file was last written 

18H  2  Date file was last written 

1AH  2  Low word of file size 

1CH  2  High word of file size 

1EH  13   

 Name and extension of the file, followed by 00H. All blanks
 are removed; if there is an extension, it is preceded by a
 period. (Volume labels include a period after the eighth
 character.)

_ _________________________________________________________________________

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

2 Specified file invalid or doesn't exist

3 Specified path invalid or doesn't exist

18 No matching directory entry found


Macro Definition:


find_first_file macro path,attrib
   mov dx,offset path
   mov cx,attrib
   mov ah,4EH
   int 21H
   endm



  61

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Example:

The following program displays a message that specifies whether a file
named report.asm exists in the current directory on the disk in drive B.

yes db "File exists.",0DH,0AH,"$"
no db "File does not exist.",0DH,0AH,"$"
path db "b:report.asm",0
buffer db 43 dup (?)
;
begin: set_dta buffer ;See Function 1AH
 find_first_file path,0 ;THIS FUNCTION
 jc error_findfirst ;Routine not shown
 cmp al,12H ;File found?
 je not_there ;No
 display yes ;See Function 09H
 jmp return ;All done
not_there: display no ;See Function 09H



62

_ _  |  |  _ _




_ _  |  |  _ _



 _ ______________


Find Next File (Function 4FH)

 Call:

 AH = 4FH

 Return:

 Carry set:
 AX
  18 = No more files
 Carry not set:
  No error



Comments:

Function 4FH searches for the next directory entry that matches the name
and attributes specified in a previous Function 4EH (Find First File). The
current DTA must contain the information filled in by Function 4EH (Find
First File).

If the function finds a matching entry, it fills the current DTA just as it
did for Find First File (see Function 4EH (Find First File)).

If there is an error, the carry flag (CF) is set and the error code returns in
AX:

Code
 Meaning
_ ________________________________________________________________

2 Specified path invalid or doesn't exist

18 No matching directory entry found



  63

_ _  |  |  _ _




_ _  |  |  _ _



_ ______________


Macro Definition:


find_next_file macro
  mov ah,4FH
  int 21H
  endm


Example:

The following program displays the number of files contained in the
current directory on the disk in drive B.

message db "No files",0DH,0AH,"$"
files dw ?
path db "b:*.*",0
buffer db 43 dup (?)
;
begin: set_dta buffer ;See Function 1AH
 find_first_file path,0 ;See Function 4EH
 jc error_findfirst ;Routine not shown
 cmp al,12H ;Directory empty?
 je all_done ;Yes, go home
 inc files ;No, bump file counter
search_dir: find_next_file ;THIS FUNCTION
 jc error_findnext ;Routine not shown
 cmp al,12H ;Any more entries?
 je done ;No, go home
 inc files ;Yes, bump file counter
 jmp search_dir ;And check again
done: convert files,10,message ;See end of chapter
all_done: display message ;See Function 09H



64

_ _  |  |  _ _