Q(uick)BASIC Statement: IOCTL

Quick View

IOCTL

A file I/O statement that transmits a control data string to a device driver

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax
  • IOCTL [#]filenumber%, string$
  • IOCTL$([#]filenumber%)
Description/Parameter(s)
filenumber% The number of an open device.
string$ The control string sent to the device.
  • IOCTL control strings and the information returned by IOCTL$ depend on the device driver. See your device-driver documentation for information about IOCTL control strings and what is returned by IOCTL$.
Syntax
  • IOCTL [#]filenumber, string
Description/Parameter(s)

The filenumber is the BASIC file number used to open the device. The string is the command sent to the device. Commands are specific to the device driver. See the documentation for the device driver to find out what the valid IOCTL commands are. An IOCTL control data string can be up to 32,767 bytes long.

The IOCTL statement works only if all three of the following conditions are met:

    1. The device driver is installed.
    2. The device driver states that it processes IOCTL strings. See the documentation for the driver. You can also test for IOCTL support through DOS function &H44 by using interrupt &H21 and the CALL INTERRUPT routine. See the Microsoft MS-DOS Programmer's Reference and the CALL INTERRUPT statement for more information.
    3. BASIC performs an OPEN on a file on that device, and the file is still open.

Most standard DOS device drivers do not process IOCTL strings, and you must determine if the specific driver accepts the command.

Example

See the ⮜ IOCTL$ function programming example ⮞, which shows how both the IOCTL statement and IOCTL$ function are used with a device driver.
Note: Any use of the IOCTL statement is device-driver dependent. The IOCTL statement uses string arguments that are only documented in the driver manual.

See also:

Syntax
  • IOCTL [#]filenumber%, string$
Description/Parameter(s)

Usage Notes

  • An IOCTL control data string can be up to 32,767 bytes long.

Important

  • The IOCTL statement works only if all of the following conditions are met:
    1. The device driver is installed.
    2. The device driver states that it processes IOCTL strings. See the documentation for the driver.
    3. BASIC performs an OPEN operation on a file on that device, and the file is still open.
    Most standard DOS device drivers do not process IOCTL strings, and you must determine if the specific driver accepts the command. If the driver does not process IOCTL strings, BASIC generates the error message, "Illegal Function Call."
  • BASIC devices ( LPTn, COMn, SCRN, CONS, PIPE) and DOS block devices (A through Z) do not support IOCTL.
  • The IOCTL statement is not available in OS/2 protected mode. However, you can achieve the same effect by directly invoking the DosDevIOCtl OS/2 function.
Example

This example uses the IOCTL statement to set the data mode in the driver and the IOCTL$ function to test the data mode when communicating with a hypothetical device driver.
Note: The IOCTL$ function works only if the device driver is installed and states that it processes IOCTL strings, and only if BASIC performs an OPEN statement on the device. Do not run this example in its current form.

OPEN "\DEV\ENGINE" FOR OUTPUT AS #1 'Tells the device that the data is raw. IOCTL #1, "RAW" 'If the character driver "ENGINE" responds "false" from the 'raw data mode in the IOCTL statement, then the file is closed. IF IOCTL$(1) = "0" THEN CLOSE 1

See also: