throbber
Interrupt 21H Function 3FH
`
`Interrupt 21H (33)
`Function 3FH (63)
`Read File or Device
`
`2.0 and later
`
`Function 3FH reads from the file or device referenced by a handle.
`To Call
`
`AH
`BX
`ex
`DS:DX
`Returns
`
`=3FH
`= handle number
`= number of bytes to read
`= segment:offset of data buffer
`
`If function is successful:
`
`Carry flag is clear.
`
`AX
`DS:DX
`
`= number of bytes read from file
`= segment:offset of data read from file
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`05H
`access denied
`06H
`invalid handle
`Programmer's Notes
`• Data is read from the file beginning at the current location of the file pointer. After a
`successful read, the file pointer is updated to point to the byte following the last byte
`read.
`If Function 3FH returns OOH in the AX register, the function attempted to read when
`the file pointer was at the end of the file. If AX is less than CX, a partial record at the
`end of the file was read.
`Function 3FH can be used with all handles, including standard input (normally the
`keyboard). When reading from standard input, this function normally reads charac(cid:173)
`ters only to the first carriage-return character. Thus, the number of bytes read in AX
`will not necessarily match the length requested in CX.
`• On networks running under MS-DOS version 3.1 or later, the user must have Read
`access to the directory and file containing the information to be read.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`
`•
`
`•
`
`•
`
`1306
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1316
`
`

`
`Interrupt 21H Function 3FH
`
`Related Functions
`40H (Write File or Device)
`42H (Move File Pointer)
`59H (Get'Extended.Error Information)
`Example
`
`;************************************************************;
`
`Function 3FH: Read File or Device
`
`int read(handle,pbuffer,nbytes)
`int handle,nbytes;
`char *pbuffer;
`
`Returns -1 if there was a read error,
`otherwise returns number of bytes read.
`
`;************************************************************;
`
`cProc
`parmW
`parmDP
`parmW
`cBegin
`
`read,PUBLIC,ds
`handle
`pbuffer
`nbytes
`
`bx 1 handle
`mov
`loadDP ds,dx,pbuffer
`mov
`cx,nbytes
`mov
`ah,3fh
`int
`21h
`jnb
`rcLok
`mov
`ax,-1
`
`Get handle.
`Get pointer to buffer.
`Get number of bytes to read.
`Set function code.
`Ask MS-DOS to read ex bytes.
`Branch if read worked.
`Else return -1.
`
`rcLok:
`cEnd
`
`Section V: System Calls
`
`1307
`
`
`
`ZTE (USA) 1007, Page 1317
`
`

`
`Interrupt 21H Function 40H
`
`Interrupt 21H (33)
`Function 40H (64)
`Write File or Device
`
`2.0 and later
`
`Function 40H writes the specified number of bytes to a file or device referenced by a
`handle.
`To Call
`
`=40H
`=handle
`=number of bytes to write
`= segment: offset of data buffer
`
`AH
`BX
`ex
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX
`
`= number of bytes written to file or device
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`05H
`access denied
`06H
`invalid handle
`Programmer's Notes
`
`•
`
`• Data is written to the file or device beginning at the· current location of the file
`pointer. After writing the specified data, Function 40H updates the position of the
`file pointer and returns the actual number of bytes written in AX.
`Function 40H returns error code 05H (access denied) if the file was opened as read(cid:173)
`only with Function 3CH (Create File with Handle), 3DH (Open File with Handle),
`5AH (Create Temporary File), or 5BH (Create New File). On networks running under
`MS-DOS version 3.1 or later, access is also denied if the file or record has been locked
`by another process.
`The handle number in BX must be one of the predefined device handles (0 through 4)
`or a handle obtained through a previous call to open or create a file (such as Function
`3CH, 3DH, 5AH, or 5BH).
`If CX = 0, the file is truncated or extended to the current file pointer location. Clusters
`are allocated or released in the file allocation table (FAT) as required to fulfill the
`request.
`
`•
`
`•
`
`1308
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1318
`
`

`
`Interrupt 21H Function 40H
`
`•
`
`•
`
`If the handle parameter for Function 40H refers to a disk file and the number of bytes
`written (returned in AX) is less than the number requested in CX, the destination disk
`is full. The carry flag is not set in this situation.
`Function 59H (Get Extended Error Information) provides further information on any
`·error-in partkular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`3FH (Read File or Device)
`42H (Move File Pointer)
`Example
`
`;************************************************************;
`
`Function 40H: Write File or Device
`
`int write(handle,pbuffer,nbytes)
`int handle,nbytes;
`char *pbuffer;
`
`Returns -1 if there was a write error,
`otherwise returns number of bytes written.
`
`;************************************************************;
`
`cProc
`parmW
`parmDP
`parmW
`cBegin
`
`write,PUBLIC,ds
`handle
`pbuffer
`nbytes
`
`bx,handle
`mov
`loadDP ds,dx,pbuffer
`mov
`cx,nbytes
`mov
`ah,40h
`int
`21h
`wr_ok
`jnb
`mov
`ax,-1
`
`Get handle.
`Get pointer to buffer.
`Get number of byt.es to write.
`Set function code.
`Ask MS-DOS to write CX bytes.
`Branch if write successful.
`Else return -1 .
`
`wr_ok:
`cEnd
`
`Section V.· System Calls
`
`1309
`
`
`
`ZTE (USA) 1007, Page 1319
`
`

`
`2.0 and later
`
`Interrupt 21H Function 41H
`
`Interrupt 21H (33)
`Function 41H (65)
`Delete File
`
`Function 41H deletes the directory entry of the specified file.
`To Call
`
`=41H
`= segment: offset of ASCIIZ pathname
`
`AH
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`02H
`file not found
`03H
`path not found
`05H
`access denied
`Programmer's Notes
`• The pathname must be a null-terminated ASCII string (ASCIIZ). Unlike Function 13H
`(Delete File), Function 41H does not allow wildcard characters in the pathname.
`• Because Function 41H supports the use of full pathnames, it is preferable to Function
`13H.
`Function 41H returns error code 05H (access denied) and fails if the file has either a
`directory or volume attribute or if it is a read-only file.
`A directory can be deleted (if it is empty) with Function 3AH (Remove Directory). A
`read-only file can be deleted if its attribute is changed to normal with Function 43H
`.(Get/Set File Attributes) before Function 41H is called.
`• On networks running under MS-DOS version 3.1 or later, the user must have Create
`access to the directory containing the file to be deleted.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`3AH (Remove Directory)
`43H (Get/Set File Attributes)
`
`•
`
`•
`
`1310
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1320
`
`

`
`Interrupt 21H Function 41H
`
`Example
`
`;************************************************************;
`
`Function 41H: Delete File
`
`int delete(pfilepath)
`char *pfilepath;
`
`Returns 0 if file deleted,
`otherwise returns error code.
`
`;~***********************************************************;
`
`delete,PUBLIC,ds
`cProc
`parrnDP pfilepath
`cBegin
`
`loadDP ds,dx,pfilepath
`mov
`ah, 41h
`iht
`21h
`dl_err
`jb
`
`xor
`
`a:x:,a:x:
`
`dl_err:
`cEnd
`
`Get pointer to pathnarne.
`Set function code.
`Ask MS-DOS to delete file.
`Branch if MS-DOS could not delete
`file.
`Else return 0.
`
`Section V: System Calls
`
`1311
`
`
`
`ZTE (USA) 1007, Page 1321
`
`

`
`Interrupt 21H Function 42H
`
`Interrupt 21H (33)
`Function 42H (66)
`Move File Pointer
`
`2.0 and later
`
`Function 42H sets the position of the file pointer (for the next read/write operation) for .
`the file associated with the specified handle.
`To Call
`
`AH
`AL
`
`BX
`CX:DX
`
`=42H
`= method code:
`OOH
`byte offset from beginning of file
`01H
`byte offset from current location of file pointer
`02H
`byte offset from end of file
`= handle number
`= offset value to move pointer:
`ex
`most significant half of a doubleword value
`DX
`least significant half of a doubleword value
`
`Returns
`!(function is successful:
`
`Carry flag is clear.
`
`DX:AX
`
`= new file pointer position (absolute byte offset from beginning of file)
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`01H
`invalid function (AL not OOH, 01H, or 02H)
`06H
`invalid handle
`Programmer's Notes
`•
`The value in CX:DX is an offset specifying how far the file pointer is to be moved.
`With method code OOH, the value in CX:DX is always interpreted as a positive 32-bit
`integer, meaning the file pointer is always set relative to the beginning of the file.
`With method codes 01H and 02H, the value in CX:DX can be either a positive or nega(cid:173)
`tive 32-bit integer. Thus, method 1 can move the file pointer either forward or back(cid:173)
`ward from its current position; method 2 can move the file pointer either forward or
`backward from the end of the file.
`
`1312
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1322
`
`

`
`Interrupt 21H Function 42H
`
`•
`
`Specifying method code OOH with an offset of 0 positions the file pointer at the begin(cid:173)
`ning of the file. Similarly, specifying method code 02H with an offset of 0 conve(cid:173)
`niently positions the file pointer at the end of the file. With method code 02H offset 0,
`the size of the file can also be determined by examining the pointer position returned
`by the function.
`• Depending on the offset specified in CX:DX, methods 1 and 2 may move the file
`pointer to a position before the start of the file. Function 42H does not return an error
`code if this happens, but later attempts to read from or write to the file will produce
`unexpected errors.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`3FH (Read File or Device)
`40H (Write File or Device)
`Example
`
`•
`
`:************************************************************;
`
`Function 42H: Move File Pointer
`
`long seek(handle,distance,mode)
`int handle,mode;
`long distance;
`
`Modes:
`
`0: from beginning of file
`1: from the current position
`2: from the end of the file
`
`Returns -1 if there wa$ a seek error,
`otherwise returns long pointer position.
`
`:************************************************************:
`
`cProc
`parmw
`parmD
`parmB
`cBegin
`
`$eek,PUBtlC
`handle
`distance
`mode
`
`mov
`les
`mov
`mov
`mov
`
`bx,handle
`dx,distance
`cx,es
`al,mode
`ah,42h
`
`Get handle.
`Get distance into ES:DX.
`Put high word of di$tance into ex.
`Get move method code.
`set function code.
`
`(more)
`
`Section V.· System Calls
`
`1313
`
`
`
`ZTE (USA) 1007, Page 1323
`
`

`
`Interrupt 21H Function 42H
`
`int
`jnb
`mov
`cwd
`
`21h
`sk_ok
`ax,-1
`
`sLok:
`cEnd
`
`Ask MS-DOS to move file pointer.
`Branch if seek successful.
`Else return -1 .
`
`1314
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1324
`
`

`
`Interrupt 21H (33)
`Function 43H (67)
`Get/Set File Attributes
`
`Function 43H gets or sets the attributes of the specified file.
`To Call
`AH
`
`=43H
`
`To get file attributes:
`
`AL
`DS:DX
`
`=OOH
`= segment: offset of ASCIIZ pathname
`
`To set file attributes:
`
`AL
`ex
`
`=01H
`= attributes to set:
`
`Bit
`
`Attribute
`
`0
`1
`2
`5
`
`Read-only file
`Hidden file
`System file
`Archive
`
`DS:DX
`Returns
`
`= segment:offset of ASCIIZ pathname
`
`If function is successful:
`
`Carry flag is clear.
`ex
`If function is not successful:
`
`= attribute .
`
`Carry flag is set.
`
`AX
`
`= error code:
`01H
`invalid function (AL not OOH or 01H)
`file not found
`02H
`03H
`path not found
`05H
`access denied
`
`Interrupt 21H Function 43H
`
`2.0 and later
`
`Section V: System Calls
`
`1315
`
`
`
`ZTE (USA) 1007, Page 1325
`
`

`
`Interrupt 21H Function 43H
`
`Programmer's Notes
`•
`The pathname must be a null-terminated ASCII string (ASCIIZ).
`•
`Function 43H cannot be used to set or change either a volume-label or directory at(cid:173)
`tribute (bits 3 and 4 of the attribute byte). With MS-DOS versions 3.x, Function 43H
`can be used to make a directory hidden or read-only.
`• On networks running under MS-DOS version 3.1 or later, the user must have Create
`access to the directory containing the file in order to change the read-only, hidden, or
`system attribute. The archive bit, however, can be changed regardless of access rights.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`None
`Example
`
`•
`
`:************************************************************;
`
`Function 43H: Get/Set File Attributes
`
`int file_attr(pfilepath,func,attr)
`char *pfilepath;
`int func, attr;
`
`Returns -1 for all errors,
`otherwise returns file attribute.
`
`:************************************************************:
`
`cProc
`parmDP
`parmB
`parmW
`cBegin
`
`file_attr,PUBLIC,ds
`pfilepath
`func
`attr
`
`loadDP ds,dx,pfilepath
`mov
`al,func
`mov
`cx,attr
`ah,43h
`mov
`int
`21h
`fa_ok
`jnb
`cx,-1
`mov
`
`Get pointer to pathname.
`Get/set flag into AL.
`Get new attr (if pres"ent).
`Set code function.
`Call MS-DOS.,
`Branch if no error.
`Else return -1 .
`
`mov
`
`ax, ex
`
`Return this value.
`
`fa_ok:
`
`cEnd
`
`13}6
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1326
`
`

`
`Interrupt 2m (33)
`Function 44H (68)
`IOCTL
`
`Interrupt 21H Function 44H
`
`2.0 and later
`
`Function 44H is a collection of subfunctions that provide a process a direct path of com(cid:173)
`munication with a device driver. As such, this function is the most flexible means of gain(cid:173)
`ing access to the full capabilities of an installed device.
`
`An IOCTL subfunction is called with 44H in AH and the value for the subfunction in AL. If
`a subfunction has minor functions, those values are specified in CL. Otherwise, the BX,
`CX, and DX registers are used for such information as handles, drive identifiers, buffer ad(cid:173)
`dresses, and so on.
`
`The subfunctions and the versions of MS-DOS with which they are available are
`
`Subfunction
`
`Name
`
`OOH
`01H
`02H
`03H
`04H
`05H
`06H
`07H
`08H
`09H
`OAH
`OBH
`OCH
`
`ODH
`
`Get Device Data
`Set Device Data
`Receive Control Data from Character Device
`Send Control Data to Character Device
`Receive Control Data from Block Device
`Send Control Data to Block Device
`Check Input Status
`Check Output Status
`Check If Block Device Is Removable
`Check If Block Device Is Remote
`Check If Handle Is Remote
`Change Sharing Retry Count
`Generic I/0 Control for Handles
`Minor Code 45H: Set Iteration Count
`Minor Code 65H: Get Iteration Count
`Generic I/0 Control for Block Devices
`Minor Code 40H: Set Device Parameters
`Minor Code 60H: Get Device Parameters .
`Minor Code 41H: Write Track on Logical Drive
`Minor Code 61H: Read Track on Logical Drive
`Minor Code 42H: Format and Verify Track
`on Logical Drive
`Minor Code 62H: Verify Track on Logical Drive
`
`MS-DOS
`Versions
`
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`3.0 and later
`3.1 and later
`3.1 and later
`3.1 and later
`3.2
`
`3.2
`
`(more)
`
`Section V System Calls
`
`1317
`
`
`
`ZTE (USA) 1007, Page 1327
`
`

`
`Interrupt 21H Function 44H
`
`Sub function
`
`Name
`
`OEH
`OFH
`
`Get Logical Drive Map
`Set Logical Drive Map
`
`MS-DOS
`Versions
`
`3.2
`3.2
`
`These subfunctions are documented, either individually or in related pairs, in the entries
`that follow.
`
`1318
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1328
`
`

`
`Interrupt 21H Function 44H Subfunction OOH
`
`Interrupt 21H (33)
`Function 44H (68) Subfunction OOH
`IOCTL: Get Device Data
`
`2.0 and later
`
`Function 44H Subfunction OOH gets information about a character device or file referenced
`by a handle.
`To Call
`
`AH =44H
`AL =OOH
`BX = handle number
`Returns
`
`If function is successful:
`
`Carry flag is clear.
`
`DX contains information on file or device:
`
`Bit
`
`Value
`
`Meaning
`
`For a file (bit 7 = 0):
`8-15
`0
`7
`0
`6
`0
`0-5
`
`For a device (bit 7 = 1):
`0
`15
`14
`1
`
`8-13
`7
`6
`5
`
`0
`1
`0
`0
`1
`
`Reserved.
`Handle refers to a file.
`File has been written.
`Drive number (0 = A, 1 = B, 2 = C, and so on).
`
`Reserved.
`Processes control strings transferred by IOCTL Subfunctions 02H
`(Receive Control Data from Character Device) and 03H (Send
`Control Data to Character Device), set by MS-DOS.
`Reserved.
`Handle refers to a device.
`End of file on input.
`Checks for control characters (cooked mode).
`Does not check for control characters (raw mode).
`
`(more)
`
`Section V: System Calls
`
`1319
`
`
`
`ZTE (USA) 1007, Page 1329
`
`

`
`Interrupt 21H Function 44H Subfunction OOH
`
`Bit
`
`Value
`
`Meaning
`
`4
`3
`2
`1
`0
`
`0
`1
`1
`1
`1
`
`Reserved.
`Clock device.
`Null device.
`Standard output device.
`Standard input device.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error code:
`01H
`invalid IOCTL subfunction
`05H
`access denied
`06H
`invalid handle
`Programmer's Notes
`• Bits 8-15 of DX correspond to the upper 8 bits of the device-driver attribute word.
`• The handle in BX must reference an open device or file.
`• Bit 5 of the device data word for character-device handles defines whether that han(cid:173)
`dle is in raw mode or cooked mode. In cooked mode, MS-DOS checks for Control-C,
`Control-P, Control-S, and Control-Z characters and transfers control to the Control-C
`exception handler (whose address is saved in the vector for Interrupt 23H) when a
`Control-C is detected. In raw mode, MS-DOS does not check for such characters when
`1/0 is performed to the handle; however, it will still check for a Control-C entered at
`the keyboard on other function calls unless such checking has been turned off with
`Function 33H, the BREAK= OFF directive in CONFIG.SYS, or a BREAK OFF com(cid:173)
`mand at the MS-DOS prompt.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`33H (Get/Set Control-C Check Flag)
`3CH (Create File with Handle)
`3DH (Open File with Handle)
`
`•
`
`1320
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1330
`
`

`
`Interrupt 21H Function 44H Subfunction OOH ·
`
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions OOH,01H:
`Get/Set IOCTL Device Data
`
`int ioctl_char_flags(setflag,handle,newflags)
`int setflag;
`int handle;
`int newflags;
`
`Set setflag = 0 to get flags, 1 to set flags.
`
`Returns -1 for error, else returns flags.
`
`;************************************************************;
`
`cProc
`parmB
`parmW
`parmW
`cBegin
`
`ioctl_char_flags,PUBLIC
`set flag
`handle
`newflags
`
`mov
`and
`mov
`mov
`
`mov
`int
`mov
`
`jnc
`mov
`
`al,setflag
`al, 1
`bx,handle
`dx,newflags
`
`ah,44h
`21h
`ax,dx
`
`iocfx
`ax,-1
`
`Ge.t set flag.
`Save only lsb.
`Get handle to character device.
`Get new flags (they are used only
`by "set" option).
`Set function code.
`Call MS-DOS.
`Assume success - prepare to return
`flags.
`Branch if no error.
`Else return error flag.
`
`iocfx:
`cEnd
`
`Section V.· System Calls
`
`1321
`
`
`
`ZTE (USA) 1007, Page 1331
`
`

`
`·Interrupt 21H Function 44H Subfunction OlH
`
`Interrupt 21H (33)
`Function 44H (68) Subfunction OlH
`IOCTL: Set Device Data
`
`2.0 and later
`
`Function 44H Subfunction 01H, the complement of IOCTL Subfunction OOH, sets informa(cid:173)
`tion about a character device- but not a file- referenced by a handle.
`To Call
`AH =44H
`AL =01H
`BX = handle number
`OX = device data word:
`
`Bit
`
`8-15
`7
`6
`5
`
`4
`3
`2
`1
`0
`
`Value
`
`Meaning
`
`0
`1
`0
`0
`
`1
`
`0
`1
`1
`1
`1
`
`Reserved.
`Handle refers to a device.
`End of file on input.
`Check for control characters
`(cooked mode).
`Do not check for control characters
`(raw mode).
`Reserved.
`Clock device.
`Null device.
`Standard output device.
`Standard input device.
`
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error code:
`01H
`invalid IOCTL subfunction
`05H
`access denied
`06H
`invalid handle
`
`1322
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1332
`
`

`
`Interrupt 21H Function 44H Subfunction OlH
`
`Programmer's Notes
`• The handle in BX must reference an open device.
`• DH must be OOH. If it is not, the carry flag is set and error code OlH (invalid function)
`is returned.
`• Bit 5 of the device data word for character-device handles selects raw mode or cooked
`mode for the handle. In cooked mode, MS-DOS checks for Control-C, Control-P,
`Control-S, and Control-Z characters and transfers control to the Control-C exception
`handler (whose address is saved in the vector for Interrupt 23H) when a Control-Cis
`detected. In raw mode, MS-DOS does not check for such characters when I/0 is per(cid:173)
`formed to the handle; however, it will still check for a Control-C entered at the key(cid:173)
`board on other function calls unless such checking has been turned off with Function
`33H, the BREAK=OFF directive in CONFIG.SYS, or a BREAK OFF command at the
`MS-DOS prompt.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`33H (Get/Set Control-C Check Flag)
`3CH (Create File with Handle)
`3DH (Open File with Handle)
`Example
`See SYSTEM CALLS: INTERRUPT 21H: Function 44H Subfunction OOH.
`
`•
`
`Section V: System Calls
`
`1323
`
`
`
`ZTE (USA) 1007, Page 1333
`
`

`
`Interrupt 21H Function 44H Subfunctions 02H and 03H
`
`Interrupt 21H (33)
`2.0 and later
`Function 44H (68) Subfunctions 02H and 03H
`IOCTL: Receive Control Data from Character Device; Send Control Data to
`Character Device
`
`Function 44H Subfunctions 02H and 03H respectively receive and send control strings
`from and to a character-oriented device driver.
`To Call
`
`AH
`AL
`
`=44H
`receive control strings
`= 02H
`send control strings
`03H
`= handle number
`= number of bytes to transfer
`= segment: offset of data buffer
`
`BX
`ex
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX
`
`= number of bytes transferred
`
`If AL was 02H on call:
`
`Buffer at DS:DX contains data read from device driver.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`OlH
`invalid function
`05H
`access denied
`06H
`invalid handle
`ODH
`invalid data (bad control string)
`Programmer's Notes
`•
`Subfunctions 02H and 03H provide a means of transferring control information of any
`type or length between an application program and a character-device driver. They
`do not necessarily result in any input to or output from the physical device itself.
`Subfunction 02H can be used to read control information about such features as
`device status, availability, and current output location. Subfunction 03H is often used
`to configure the driver or device for subsequent I/0; for example. it may be used to set
`the baud rate, word length, and parity for a serial communication'S adapter or to initial(cid:173)
`ize a printer for a specific font, page length, and so on. The format of the control data
`passed by these subfunctions is driver specific and does not follow any standard.
`
`•
`
`1324
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1334
`
`

`
`Interrupt 21H Function 44H Subfunctions 02H and 03H
`
`•
`
`• Character-device drivers are not required to support IOCTL Subfunctions 02H and
`03H. Therefore, Subfunction OOH (Get Device Data) should be called before either
`Subfunction 02H or 03H to determine whether a device can process control strings.
`If bit 14 of the device data word returned bySubfunction OOH is set, the device driver
`supports IOCTL Subfunctions 02H and 03H.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`44H Subfunction OOH (Get Device Data)
`44H Subfunction 04H (Receive Control Data from Block Device)
`44H Subfunction 05H (Send Control Data to Block Device)
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions 02H,03H:
`IOCTL Character Device control
`
`int ioctl_char_ctrl(recvflag,handle,pbuffer,nbytes)
`int
`recvflag;
`int
`handle;
`char *pbuffer;
`int
`nbytes;
`
`Set recvflag = 0 to receive info, 1 to send.
`
`Returns -1 for error, otherwise returns number of
`byte~ sent or received.
`
`;************************************************************;
`
`cProc
`parmB
`parmW
`parmDP
`parmW
`cBegin
`
`ioctl_char_ctrl,PUBLIC,<ds>
`recvflag
`handle
`pbuffer
`nbytes
`
`mov
`and
`add
`mov
`mov
`loadDP
`mov
`int
`jnc
`mov
`
`al,recvflag
`al, 1
`al,2
`bx,handle
`cx,nbytes
`ds,dx,pbuffer
`ah,44h
`21h
`iccx
`ax,-1
`
`Get recvflag.
`Keep only lsb.
`AL = 02H for receive, 03H for send.
`Get character-device handle.
`Get number of bytes to receive/send.
`Get pointer to buffer.
`Set function code.
`Call MS-DOS.
`Branch if no error.
`Return -1 for all errors.
`
`iccx:
`cEnd
`
`Section V: System Calls
`
`1325
`
`
`
`ZTE (USA) 1007, Page 1335
`
`

`
`Interrupt 21H Function 44H Subfunctions 04H and OSH
`
`Interrupt 21H (33)
`2.0andlater
`Function 44H (68) Subfunctions 04H and.05H
`IOCTL: Receive Control Data from Block Device; Send Control Data to Block
`Device
`
`Function 44H Subfunctions 04H and 05H respectively receive and send control strings
`from and to a block-oriented device driver.
`To Call
`AH
`AL
`
`=44H
`receive block-device data
`=04H
`send block-device data
`05H
`= drive number (0 = default drive, 1 = drive A, 2 = drive B, and so on)
`= number of bytes to transfer
`= segment:offset of data buffer
`
`BL
`ex
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX
`
`= number of bytes transferred
`
`If AL was 04H on call:
`
`Buffer at DS:DX contains control data read from device driver.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`01H
`invalid function
`05H
`access denied
`06H
`invalid handle
`ODH
`invalid data (bad control string)
`Programmer's Notes
`•
`Subfunctions 04H and 05H provide a means of transferring control information of any
`type or length between an application program and a block-device driver. They do
`not necessarily result in any input to or output from the physical device itself.
`• Control strings can be used to request driver operations that are not file oriented, such
`as tape rewind or disk eject (if hardware supported). The contents of such control
`strings are specific to individual device drivers and do not follow any standard format.
`
`1326
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1336
`
`

`
`Interrupt 21H Function 44H Subfunctions 04H and 05H
`
`•
`
`•
`
`Subfunction 04H can be used to obtain a code from the driver indicating device avail(cid:173)
`ability or status. Block devices that might use this subfunction include magnetic tape
`or tape cassette, CD ROM, and Small Computer Standard Interface (SCSI) devices.
`• Block-device drivers are not required to support IOCTL Subfunctions 04H and 05H. If
`the driver does not support these subfunctions, error code OlH (Invalid Function) is
`returned.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`44H Subfunction OOH (Get Device Data)
`44H Subfunction 02H (Receive Control Data from Character Device)
`44H Subfunction 03H (Send Control Data to Character Device)
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions 04H,05H:
`IOCTL Block Device Control
`
`int ioctl-block_ctrl(recvflag,drive_ltr,pbuffer,nbytes)
`int
`recvflag;
`int
`drive_ltr;
`char *pbuffer;
`int
`nbytes;
`
`Set recvflag = 0 to receive info, 1 to send.
`
`Returns -1 for error, otherwise returns number of
`bytes sent or received.
`
`;********************************~***************************;
`
`cProc
`parmB
`parmB
`parmDP
`parmW
`cBegin
`
`ioctl-block_ctrl,PUBLIC,<ds>
`recvflag
`drive_ltr
`pbuffer
`nbytes
`
`mov
`and
`add
`mov
`or
`jz
`and
`sub
`
`al,recvflag
`al, 1
`al,4
`bl,drive_ltr
`bl,bl
`ibc
`bl,not 20h
`bl, 'A'-1
`
`Get recvflag.
`Keep only lsb.
`AL = 04H for receive, OSH for send.
`Get drive letter.
`Leave 0 alone.
`
`Convert letter to uppercase.
`Convert to drive number:
`'A'
`'B' = 2, etc.
`
`1,
`
`(more)
`
`Section V: System Calls
`
`1327
`
`
`
`ZTE (USA) 1007, Page 1337
`
`

`
`Interrupt 21H Function 44H Subfunctions 04H and OSH
`
`ibc:
`
`ibex:
`cEnd
`
`cx,nbytes
`mov
`loadDP ds,dx,pbuffer
`mov
`ah,44h
`int
`21h
`jnc
`ibex
`mov
`ax,-1
`
`Get number of bytes to receive/send.
`Get pointer to buffer.
`Set function code.
`Call MS-DOS.
`Branch if no error.
`Return -1 for all errors.
`
`1328
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1338
`
`

`
`Interrupt 21H Function 44H Subfunctions 06H and 07H
`
`Interrupt 21H (33)
`2.0andlater
`Function 44H (68) Subfunctions 06H and 07H
`IOCTL: Check Input Status; Check Output Status
`
`Function 44H Subfunctions 06H and 07H respectively determine whether a device or file
`associated with a handle is ready for input or output.
`To Call
`AH =44H
`get input status
`AL = 06H
`get output status
`07H
`BX = handle number
`Returns
`
`If function is successful:
`
`Carry flag is clear.
`
`AL = input or output status:
`OOH
`not ready
`FFH
`ready
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error .code:
`OlH
`invalid function
`05H
`access denied
`06H
`invalid handle
`ODH
`invalid data (bad control string)
`Programmer's Notes
`• The status returned in AL has the following meanings:
`
`Status
`
`Device
`
`Input File
`
`Output File
`
`OOH
`OFFH
`
`Not ready
`Ready
`
`Pointer at EOF
`Ready
`
`Ready
`Ready
`
`Section V: System Calls
`
`1329
`
`
`
`ZTE (USA) 1007, Page 1339
`
`

`
`Interrupt 21H Function 44H Subfunctions 06H and 07H
`
`•
`
`• Output files always return a ready condition, even if the disk is full or no disk is in the
`drive.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`None
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions 06H,07H:
`IOCTL Input/Output Status
`
`int ioctl_char_status(outputflag,handle)
`int output flag;
`int handle;
`
`Set outputflag = 0 for input status, 1 for output status.
`
`Returns -1 for all errors, 0 for not ready,
`and 1 for ready.
`
`;************************************************************;
`
`cProc
`parmB
`parmW
`cBegin
`
`ioctl_char_status,PUBLIC
`output flag
`handle
`
`mov
`and
`add
`
`al,outputflag
`al, 1
`al,6
`
`Get outputflag.
`Keep only lsb.
`AL = 06H for input status, 07H for output
`status.
`Get handle.
`Set function code.
`Call MS-DOS.
`Branch if no error.
`Return error code.
`
`bx,handle
`ah,44h
`21h
`isnoerr
`ax,-1
`short isx
`
`mov
`mov
`int
`jnc
`mov
`jmp
`isnoerr:
`and
`
`isx:
`cEnd
`
`ax, 1
`
`Keep only lsb for return value.
`
`1330
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1340
`
`

`
`Interrupt 21H Function 44H Subfunction 08H
`
`Interrupt 21H (33)
`Function 44H (68) Subfunction.OSH
`IOCTL: Check If Block Device Is Removable
`
`3.0 and later
`
`Function 44H Subfunction 08H checks whether the specified block device contains a
`removable storage medium, such as a floppy disk.
`To Call
`AH =44H
`AL = 08H
`BL = drive number (0 = default drive, 1 = drive A, 2 = drive B, and so on)
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX =OOH
`OlH
`
`storage medium removable
`storage medium not removable
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error code:
`01H
`invalid function
`OFH
`invalid drive
`Programmer's Notes
`•
`This subfunction exists to allow an application to check for a removable disk so that
`the user can be prompted to change disks if a required file is not found.
`• When the carry flag is set, error code 01H normally means that MS-DOS did not recog(cid:173)
`nize the function call. However, this error can also mean that the device driver does
`not support Subfunction 08H. In this case, MS-DOS assumes that the storage medium
`is not removable.
`Function 59H (Get Extended Error Information) provides further information on any
`erro£- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`None
`
`•
`
`Section V.· System Calls
`
`1331
`
`
`
`ZTE (USA) 1007, Page 1341
`
`

`
`Interrupt 21H F

This document is available on Docket Alarm but you must sign up to view it.


Or .

Accessing this document will incur an additional charge of $.

After purchase, you can access this document again without charge.

Accept $ Charge
throbber

Still Working On It

This document is taking longer than usual to download. This can happen if we need to contact the court directly to obtain the document and their servers are running slowly.

Give it another minute or two to complete, and then try the refresh button.

throbber

A few More Minutes ... Still Working

It can take up to 5 minutes for us to download a document if the court servers are running slowly.

Thank you for your continued patience.

This document could not be displayed.

We could not find this document within its docket. Please go back to the docket page and check the link. If that does not work, go back to the docket and refresh it to pull the newest information.

Your account does not support viewing this document.

You need a Paid Account to view this document. Click here to change your account type.

Your account does not support viewing this document.

Set your membership status to view this document.

With a Docket Alarm membership, you'll get a whole lot more, including:

  • Up-to-date information for this case.
  • Email alerts whenever there is an update.
  • Full text search for other cases.
  • Get email alerts whenever a new case matches your search.

Become a Member

One Moment Please

The filing “” is large (MB) and is being downloaded.

Please refresh this page in a few minutes to see if the filing has been downloaded. The filing will also be emailed to you when the download completes.

Your document is on its way!

If you do not receive the document in five minutes, contact support at support@docketalarm.com.

Sealed Document

We are unable to display this document, it may be under a court ordered seal.

If you have proper credentials to access the file, you may proceed directly to the court's system using your government issued username and password.


Access Government Site

We are redirecting you
to a mobile optimized page.





Document Unreadable or Corrupt

Refresh this Document
Go to the Docket

We are unable to display this document.

Refresh this Document
Go to the Docket