Q(uick)BASIC Function: IOCTL$

Quick View

IOCTL$

A file I/O function that receives a control data string from 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)
Description/Parameter(s)

The filenumber is the BASIC file number used to open the device. The IOCTL$ function is most frequently used to test whether an IOCTL statement succeeded or failed or to obtain current status information.

Note: BASIC devices ( LPT1:, COM1:, COM2:, SCRN:, CONS:) and DOS block devices ( A: through Z:) do not support IOCTL.

You could use IOCTL$ to ask a communications device to return the current baud rate, information on the last error, logical line width, and so on. The exact information returned would depend on the specific device driver.

The IOCTL$ function 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 CALL INTERRUPT statement for more information.
    3. BASIC performs an OPEN statement on a file on that device.
Example

This example shows how to communicate with a device driver using a hypothetical device driver named ENGINE. The IOCTL statement sets the data mode in the driver and the IOCTL$ function tests the data mode.
Note: The IOCTL$ function works only if the device driver is installed and states that it processes IOCTL strings, and if BASIC performs an OPEN statement on the device. Do not run this example in its current form.

OPEN "DEVENGINE" FOR OUTPUT AS #1 IOCTL #1, "RAW" 'Tells the device that the data is 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:

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

Usage Notes

  • The IOCTL$ function is most frequently used to test whether an IOCTL statement succeeded or failed, or to obtain current status information.
  • You can use IOCTL$ to ask a communications device to return the current baud rate, information on the last error, logical line width, and so on. The exact information returned depends on the specific device driver. See the device driver documentation to find out what status information the device driver can send.

Important

  • 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.
  • BASIC devices ( LPTn, COMn, SCRN, CONS, PIPE) and DOS block devices (A through Z) do not support IOCTL.
  • The IOCTL$ function 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."
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: