en:docs:fapi:dosdevioctl2

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
en:docs:fapi:dosdevioctl2 [2021/08/20 04:37] – created prokusheven:docs:fapi:dosdevioctl2 [2023/11/26 12:37] (current) – [Remarks] prokushev
Line 1: Line 1:
 {{page>en:templates:fapiint}} {{page>en:templates:fapiint}}
  
 +====== DosDevIOCtl2 ======
 + 
 This call performs control functions on a device specified by an opened device handle. This call performs control functions on a device specified by an opened device handle.
  
-==Syntax== +===== Syntax ===== 
- DosDevIOCtl (Data, ParmList, Function, Category, DevHandle)+<code c> 
 + DosDevIOCtl2 (Data, DataLength, ParmList, ParmListLength, 
 +               Function, Category, DevHandle) 
 +</code> 
 +===== Parameters =====
  
-==Parameters== +  * Data ([[PVOID]]) - input : Address of the data area. 
-;Data (PVOID) - input : Address of the data area. +  * DataLength ([[USHORT]]) - input : Length of the data buffer. 
-;ParmList (PVOID) - input : Address of the command-specific argument list. +  * ParmList ([[PVOID]]) - input : Address of the command-specific argument list. 
-;Function (USHORT) - input : Device-specific function code. +  * ParmListLength ([[USHORT]]) - input : Length of the command-specific argument list. 
-;Category (USHORT) - input : Device category. +  * Function ([[USHORT]]) - input : Device-specific function code. 
-;DevHandle (HFILE) - input : Device handle returned by DosOpen or a standard (open) device handle.+  * Category ([[USHORT]]) - input : Device category. 
 +  * DevHandle ([[HFILE]]) - input : Device handle returned by DosOpen or a standard (open) device handle.
  
-==Return Code== +===== Return Code ===== 
-;rc (USHORT) - return:Return code descriptions are: + 
-* 0  NO_ERROR +rc ([[USHORT]]) - return:Return code descriptions are: 
-* 1  ERROR_INVALID_FUNCTION + 
-* 6  ERROR_INVALID_HANDLE +  * 0 NO_ERROR 
-* 15  ERROR_INVALID_DRIVE +  * 1 ERROR_INVALID_FUNCTION 
-* 31  ERROR_GEN_FAILURE +  * 6 ERROR_INVALID_HANDLE 
-* 87  ERROR_INVALID_PARAMETER +  *15 ERROR_INVALID_DRIVE 
-*115  ERROR_PROTECTION_VIOLATION +  *31 ERROR_GEN_FAILURE 
-*117  ERROR_INVALID_CATEGORY +  *87 ERROR_INVALID_PARAMETER 
-*119  ERROR_BAD_DRIVER_LEVEL +  *115 ERROR_PROTECTION_VIOLATION 
-*163  ERROR_UNCERTAIN_MEDIA +  *117 ERROR_INVALID_CATEGORY 
-*165  ERROR_MONITORS_NOT_SUPPORTED+  *119 ERROR_BAD_DRIVER_LEVEL 
 +  *163 ERROR_UNCERTAIN_MEDIA 
 +  *165 ERROR_MONITORS_NOT_SUPPORTED 
 + 
 +===== Remarks =====
  
-==Remarks== 
 Values returned in the range hex FF00 through FFFF are user dependent error codes. Values returned in the range hex FE00 through FEFF are device driver dependent error codes. Values returned in the range hex FF00 through FFFF are user dependent error codes. Values returned in the range hex FE00 through FEFF are device driver dependent error codes.
  
-Refer to the ''IBM Operating System/2 Version 1.2 I/O Subsystems And Device Support Volume 1'' for a complete listing of control functions (DevHlp calls). +Refer to the [[http://www.os2museum.com/files/docs/os212pti/64F3959_OS2_V1_2_PTI_IO_Subsystems_and_Device_Support_Vol_1_Device_Drivers.pdf|IBM Operating System/2 Version 1.2 I/O Subsystems And Device Support Volume 1]] for a complete listing of control functions (DevHlp calls).
  
-===Family API Considerations=== +This function provides a generic, expandable IOCTL facility.
-Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following considerations apply to DosDevIOCtl when coding for the DOS mode.+
  
-The level of support for DosDevIOCtl is identified by category and function code with a noted restriction if it is not supported by DOS 2.X or DOS 3.X Functions tend to be more restrictive in lower version numbers of DOS.+A null (zero) value for Data specifies that this parameter is not defined for the generic IOCTL function being specified. A null value for Data causes the value passed in DataLength to be ignored.
  
-*Category 1 supported as follows: +A null (zero) value for ParmList specifies that this parameter is not defined for the generic IOCTL function being specified. A null value for ParmList causes the value passed in ParmListLength to be ignored.
-**41H Set Baud Rate +
-**42H Set Line Control +
-**All other category 1 functions are not supported for DOS 2.X and DOS 3.X.  +
-*Category 2 not supported in FAPI +
-*Category 3 not supported in FAPI +
-*Category 4 not supported in FAPI +
-*Category 5 supported in FAPI as follows: +
-**42H Set Frame control - supports IBM Graphics Printers only +
-**44H Set Infinite Retry - for DOS 2.X and DOS 3.X, the function is in effect only for the duration of the calling program +
-**46H Initialize printer +
-**62H Get Frame Control - not supported for DOS 2.X and DOS 3.X +
-**64H Get Infinite Retry +
-**66H Get Printer Status. +
-*Category 6 not supported in FAPI +
-*Category 7 not supported in FAPI +
-*Category 8 supported in FAPI as follows: +
-**00H Lock Drive - not supported for versions below DOS 3.2 +
-**01H Unlock Drive - not supported for versions below DOS 3.2 +
-**02H Redetermine Media - not supported for versions below DOS 3.2 +
-**03H Set Logical Map - not supported for versions below DOS 3.2 +
-**20H Block Removable - not supported for versions below DOS 3.2 +
-**21H Get Logical Map - not supported for versions below DOS 3.2 +
-**43H Set Device Parameters - not supported for DOS 2.X and DOS 3.X +
-**44H Write Track - not supported for DOS 2.X and DOS 3.X +
-**45H Format Track - not supported for DOS 2.X and DOS 3.X +
-**63H Get Device Parameters - not supported for DOS 2.X and DOS 3.X +
-**64H Read Track - not supported for DOS 2.X and DOS 3.X +
-**65H Verify Track - not supported for DOS 2.X and DOS 3.X.  +
-*Category 9 is reserved +
-*Category 10 (0AH) not supported in FAPI +
-*Category 11 (0BH) not supported in FAPI.+
  
-==Bindings== +The kernel formats a generic IOCTL packet and call the device driver. Since V1.0 and V1.1 device drivers do not understand generic IOCTL packets with DataLength and ParmListLength, the kernel does not pass these fields to the device driver. Device drivers that are marked as being level 2 or higher must support receipt of the generic IOCTL packets with associated length fields. 
-===C=== + 
-<PRE>+Do not pass a non-null pointer with a zero length. 
 + 
 +===== Bindings ===== 
 + 
 +==== C ==== 
 + 
 +<code c>
 #define INCL_DOSDEVICES #define INCL_DOSDEVICES
  
-USHORT  rc = DosDevIOCtl(Data, ParmList, Function, Category, DevHandle);+USHORT  rc = DosDevIOCtl2(Data, ParmList, Function, Category, DevHandle);
  
 PVOID   Data;          /* Data area */ PVOID   Data;          /* Data area */
 +USHORT  DataLength     /* Data area length */
 PVOID   ParmList;      /* Command arguments */ PVOID   ParmList;      /* Command arguments */
 +USHORT  ParmListLength /* Command arguments list length */
 USHORT  Function;      /* Device function */ USHORT  Function;      /* Device function */
 USHORT  Category;      /* Device category */ USHORT  Category;      /* Device category */
Line 84: Line 70:
  
 USHORT  rc;            /* return code */ USHORT  rc;            /* return code */
-</PRE>+</code>
  
-===MASM=== +==== MASM ==== 
-<PRE> + 
-EXTRN  DosDevIOCtl:FAR+<code asm> 
 +EXTRN  DosDevIOCtl2:FAR
 INCL_DOSDEVICES     EQU 1 INCL_DOSDEVICES     EQU 1
  
-PUSH@  OTHER   Data          ;Data area +PUSH@  OTHER   Data           ;Data area 
-PUSH@  OTHER   ParmList      ;Command arguments +PUSH   WORD    DataLength     ;Data area length 
-PUSH   WORD    Function      ;Device function +PUSH@  OTHER   ParmList       ;Command arguments 
-PUSH   WORD    Category      ;Device category +PUSH   WORD    ParmListLength ;Command arguments list length 
-PUSH   WORD    DevHandle     ;Device handle +PUSH   WORD    Function       ;Device function 
-CALL   DosDevIOCtl+PUSH   WORD    Category       ;Device category 
 +PUSH   WORD    DevHandle      ;Device handle 
 +CALL   DosDevIOCtl2
  
-Returns WORD +</code>
-</PRE>+
  
 +Returns WORD
  
 {{page>en:templates:fapi}} {{page>en:templates:fapi}}