home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tolkit45.zip / os2tk45 / book / addendum.inf (.txt) next >
OS/2 Help File  |  1999-05-11  |  233KB  |  12,049 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Edition Notice ΓòÉΓòÉΓòÉ
  3.  
  4. Note  Before using this information and the product it supports, read the 
  5.       general information under Notices. 
  6.  
  7. First Edition (May 1999) 
  8.  
  9. This edition applies to OS/2 Warp Server for e-business and to all subsequent 
  10. releases and modifications until otherwise indicated in new editions. 
  11.  
  12.  
  13. ΓòÉΓòÉΓòÉ 2. About this book ΓòÉΓòÉΓòÉ
  14.  
  15. This book is a technical reference for application programmers creating OS/2 
  16. (R) control program (kernel) functions. It contains APIs for OS/2 Warp Server 
  17. for e-business. This book is intended to be used in conjunction with other 
  18. books containing APIs that apply to OS/2 Warp Server. 
  19.  
  20.  
  21. ΓòÉΓòÉΓòÉ 2.1. Who should read this book ΓòÉΓòÉΓòÉ
  22.  
  23. This book is intended for application programmers who want to use kernel 
  24. functions in their programs. This reference provides technical information 
  25. about functions and data structures available to the developer. 
  26.  
  27.  
  28. ΓòÉΓòÉΓòÉ 2.2. Conventions and terminology used in this book ΓòÉΓòÉΓòÉ
  29.  
  30. The following conventions are used in this book 
  31.  
  32.      Boldface type indicates the name of an item you need to select, field 
  33.       names, parameters, and folder names. It also indicates controls (when 
  34.       used in procedures), for example 
  35.  
  36.         -  Menu bar choices 
  37.  
  38.         -  Radio buttons 
  39.  
  40.         -  Push buttons 
  41.  
  42.         -  List boxes 
  43.  
  44.         -  Check boxes 
  45.  
  46.         -  Entry fields 
  47.  
  48.         -  Read-only entry fields 
  49.  
  50.      Italic type indicates new terms, book and diskette titles, or variable 
  51.       information that must be replaced by an actual value. It also indicates 
  52.       words of emphasis and technical terms when introduced. 
  53.  
  54.      Monospace type indicates an example (such as how to enter a command), 
  55.       text that is displayed on the screen, text you type, or special 
  56.       characters. 
  57.  
  58.      UPPERCASE TYPE indicates a file and directory name, command name, or 
  59.       acronym. 
  60.  
  61.  
  62. ΓòÉΓòÉΓòÉ 2.3. Prerequisite and related information ΓòÉΓòÉΓòÉ
  63.  
  64. This reference is intended for application designers and programmers who are 
  65. familiar with the following 
  66.  
  67.      C Programming Language 
  68.  
  69.      Information contained in the following books  Control Programming Guide, 
  70.       Presentation Manager, OS/2 LAN Programming Guide and Reference, and 
  71.       Physical Device Driver Reference. 
  72.  
  73.  
  74. ΓòÉΓòÉΓòÉ 3. DosDebug Commands ΓòÉΓòÉΓòÉ
  75.  
  76. This chapter contains an alphabetic list of the following debug commands. 
  77.  
  78. Cmd No.  Command Name                 Description
  79. 33       DBG_C_Attach                 Attach to a Process
  80.                                       Command
  81. 34       DBG_C_Detach                 Detach from a Process
  82.                                       under Debug Command
  83. 35       DBG_C_RegDebug               JIT (Just-in_Time)
  84.                                       Debugger
  85.                                       Registration/De-Registrati
  86.                                       Command
  87. 36       DBG_C_QueryDebug             Query JIT (Just-in-Time)
  88.                                       Debugger Registered
  89.                                       Command
  90.  
  91.  
  92. ΓòÉΓòÉΓòÉ 3.1. DBG_C_Attach ΓòÉΓòÉΓòÉ
  93.  
  94.  Debug Command 33  Debug Attach Command 
  95.  
  96. Parameters 
  97.  
  98.  Addr   Possible values are shown in the list below 
  99.  
  100.         0x00000000     The default action is to sever the connection between 
  101.                        the debugger and the program being debugged, if a system 
  102.                        resource is being held. 
  103.  
  104.         0x00000001     The sever action is not wanted between the debugger and 
  105.                        the program being debugged. 
  106.  
  107.  Pid    Process ID of debuggee 
  108.  
  109.  Tid    Reserved, must be zero 
  110.  
  111.  Cmd    DBG_C_Attach 
  112.  
  113.  Value  Debugging Level Number 
  114.  
  115.         The only permitted debugging level number is shown in the following 
  116.         list 
  117.  
  118.         1        = DBG_L_386 
  119.  
  120.  This must be the first DosDebug command called when dynamically attaching to a 
  121.  process. No other DosDebug command will be accepted until the debugging 
  122.  connection has been established except for DBG_C_RegDebug to register a JIT 
  123.  (Just-in-time) debugger on a per-process basis and DBG_C_QueryDebug to query 
  124.  the JIT debug information. See DBG_C_RegDebug and DBG_C_QueryDebug for more 
  125.  information. 
  126.  
  127.  Returns 
  128.  
  129.  This command establishes a debugging connection. It must be the initial 
  130.  command, since it verifies the buffer format for the rest of the connection. 
  131.  
  132.  Because DosDebug usually cannot be ported to new machines without changing the 
  133.  format of the buffer, this command is needed to establish that the debugger is 
  134.  capable of handling the desired buffer format. 
  135.  
  136.  If the requested debugging level is not supported, an error is returned, and 
  137.  the connection is not made. This gives the debugger a chance to try again or 
  138.  to start automatically a different debugger process that uses a different 
  139.  buffer format. 
  140.  
  141.  For this command, the machine-independent and PID portion of the buffer is 
  142.  examined. This portion includes the Pid, Tid, Cmd, and Value fields. This 
  143.  makes it possible to port the DosDebug buffer from one machine to another 
  144.  without returning an error to the debugger on the initial DosDebug command. 
  145.  
  146.  The only DosDebug notifications that are returned by this command are 
  147.  DBG_N_Success and DBG_N_Error. 
  148.  
  149.  Restrictions 
  150.  
  151.  This DBG_C_Attach command does not require that the session for the program 
  152.  being debugged tohave been started with EXEC_TRACE, or SSF_TRACEOPT_XXX option 
  153.  by DosExecPgm or DosStartSession, as DBG_C_Connect requires. 
  154.  
  155.  If a connection to the program being debugged is established by a debugger, 
  156.  then another debug session cannot attach to the program being debugged while 
  157.  the first debugger is attached. 
  158.  
  159.  Remarks 
  160.  
  161.  If Addr is not 0, the connection between the debugger and the program being 
  162.  debugged is not severed. If any threads of the program being debugged, other 
  163.  than the thread that encountered the debug event, are holding system 
  164.  semaphores, they will be allowed to run until they release the semaphores. 
  165.  They will then be stopped, and the notification will be delivered. 
  166.  
  167.  If the thread encountering the debug event is holding a system semaphore, the 
  168.  connection between the debugger and the program being debugged is severed by 
  169.  terminating the program being debugged and returning a DBG_N_Error 
  170.  notification to the debugger with the value field set to 0 and the register 
  171.  set filled in. No further DosDebug commands will be accepted by the program 
  172.  being debugged, nor will it generate any other notifications. 
  173.  
  174.  If a DBG_C_Stop is issued, and a thread owning a system semaphore is about to 
  175.  generate a DBG_N_AsyncStop notification, it will be allowed to continue 
  176.  execution until it releases the semaphore. It will then be stopped, and the 
  177.  notification will be delivered. This is the only exception to the severing of 
  178.  the debugger/debugbee rule. 
  179.  
  180.  If Addr is set to 0, the connection between the debugger and the program being 
  181.  debugged is severed if a system resource is being held, in which case DosDebug 
  182.  returns 
  183.  
  184.  Tid    Thread owning semaphore 
  185.  
  186.  Cmd    DBG_N_Error 
  187.  
  188.  Value  ERROR_EXCL_SEM_ALREADY_OWNED 
  189.  
  190.  If the debugger needs to present some information to the user or use the 
  191.  thread holding the system resource, the debugger must terminate the program 
  192.  being debugged. Any other action might result in a system halt. 
  193.  
  194.  Upon attach to a process, a series of notifications will occur. The 
  195.  notifications include the current EXE module notification, thread (all that 
  196.  exist in the debuggee) create notifications, and currently loaded modules 
  197.  (DLLs) notifications. The notifications occur as DBG_NPModuleLoad, 
  198.  DBG_N_ThreadCreate, etc, just as they do with the DBG_C_Connect command. 
  199.  
  200.  
  201. ΓòÉΓòÉΓòÉ 3.2. DBG_C_Detach ΓòÉΓòÉΓòÉ
  202.  
  203.  Debug Command 34  Debug Detach Command 
  204.  
  205. Parameters 
  206.  
  207.  Pid    Process of ID of debuggee 
  208.  
  209.  Cmd    DBG_C_Detach 
  210.  
  211.  Returns 
  212.  
  213.  This command detaches from the debugee connection. It is the last comand 
  214.  issued before resuming the process. 
  215.  
  216.  The only DosDebug notifications that are returned by this command are 
  217.  DBG_N_Success and DBG_N_Error. 
  218.  
  219.  Restrictions 
  220.  
  221.  Detach only works on a debuggee process currently under debug using the attach 
  222.  command, DBG_C_Attach.  You cannot use DBG_C_Detach if you used DBG_C_Connect. 
  223.  DBG_C_Attach and DBG_C_Detach are paired and are used for debugging a process 
  224.  that is already running. 
  225.  
  226.  Remarks 
  227.  
  228.  By using this function, a debugger can only remove debug context of a given 
  229.  debuggee process as stated above.  If the debugger needs to detach and have 
  230.  the debuggee terminate, it is neccessary to use DBG_C_Term command instead of 
  231.  DBG_C_Detach.  This will terminate the debuggee process and remove attach 
  232.  information. 
  233.  
  234.  
  235. ΓòÉΓòÉΓòÉ 3.3. DBG_C_RegDebug ΓòÉΓòÉΓòÉ
  236.  
  237.  Debug Command 35 JIT (Just-in-Time) Debugger Registration/De-Registration 
  238. Command 
  239.  
  240. Parameters 
  241.  
  242.  Pid    Process of ID of debuggee 
  243.  
  244.  Cmd    DBG_C_RegDbg 
  245.  
  246.  Buffer Pointer to JIT Debugger path name and arguments 
  247.  
  248.         Address of the buffer in which the fully-qualified path name of the JIT 
  249.         debugger is specified.  The path name can be followed by an optional 
  250.         arguments to the JIT debugger.  If %d is found in the arguments, the 
  251.         system will replace %d with the ID of the failing process.  If %d is 
  252.         not found in the arguments, the system will assume argument one is the 
  253.         process ID. 
  254.  
  255.         A coded example of this follows 
  256.  
  257.         Assume the ID of the failing process is 99. 
  258.  
  259.         If Buffer contains "C \OS2\MYJITDBG.EXE /Tn /K /P%d",  the system will 
  260.         launch the JIT debugger as "C \OS2\MYJITDBG.EXE /Tn /K /P99" 
  261.  
  262.         If Buffer contains "C \OS2\MYJITDBG.EXE /Tn /K",  the system will 
  263.         launch the JIT debugger as "C \OS2\MYJITDBG.EXE 99 /Tn /K" 
  264.  
  265.  Len    0 or the size of Buffer in bytes 
  266.  
  267.         A Len of 0 is used to deregister the JIT debugger from the given 
  268.         process. Buffer is ignored in this case. If Len is 0 and no JIT 
  269.         debugger is registered the system will return error code 
  270.         ERROR_INSUFFICIENT_BUFFER. 
  271.  
  272.  Addr   Registration Flags 
  273.  
  274.         JIT_REG_INHERIT Enable children processes to inherit registered 
  275.                        per-process JIT debugger from parent. (This is the 
  276.                        default.) 
  277.  
  278.         JIT_REG_NONINHERIT Do not allow inheritance of per-process JIT debugger 
  279.                        to the children of that parent process. 
  280.  
  281.         If Inheritance is being used with DosStartSession() on a PM 
  282.         application, the inheritance link is broken. This is due to the design 
  283.         of sessions management for DosStartSession() which causes all children 
  284.         processes to always inherit from the PM. The recommended way to start a 
  285.         child process is through DosExecPgm() under the same session type. The 
  286.         parent-child relationship will be set up correctly and the JIT will be 
  287.         inherited. Otherwise the parent application has to register the JIT on 
  288.         every DosStartSession() child process. The JIT could also be registered 
  289.         on the main PMSHELL.EXE process. This would cause all future 
  290.         DosStartSession() processes to inherit the JIT information from PM. 
  291.         This works around the DosStartSession() inheritance problem above. 
  292.  
  293.  Value  Return error code, if any 
  294.  
  295.  Returns 
  296.  
  297.  The only DosDebug notifications that are returned by this command are 
  298.  DBG_N_Success and DBG_N_Error. 
  299.  
  300.  Valid Field return error return code(s) 
  301.  
  302.  ERROR_FILE_NOT_FOUND File was not found in specified path 
  303.  
  304.  ERROR_INSUFFICIENT BUFFER Returned if JIT Debugger not registered and a Len of 
  305.            0 passed into register 
  306.  
  307.  Restrictions 
  308.  
  309.  This is one of the only DosDebug commands that can be called without having to 
  310.  issue a DBG_C_Connect or DBG_C_Attach first. This command is usually called 
  311.  after starting a process using DosExecPgm() or DosStartSession() in order to 
  312.  gather the PID to use with the registration command. Another way of gathering 
  313.  PID information is to use the DosQuerySysState(). This will return all of the 
  314.  current Process ID's running in the system. See DosQuerySysState() for more 
  315.  information. The registration of the debugger must use a fully-qualified path 
  316.  name and executable for per-process and global registration.  Registration 
  317.  will not occur if the debugger is not physically found on the disk upon 
  318.  registration.  If you make multiple calls to DosDebug with the DBG_C_RegDbg 
  319.  command, the previous debugger will be deleted and the newest one will be 
  320.  registered. If the DBG_C_RegDbg is called with the size field of 0 and a JIT 
  321.  debugger exists, the JIT debugger will be unregistered. This only applies for 
  322.  per-process JIT registration. Global registration cannot be unregistered. This 
  323.  is set for a systemwide level. 
  324.  
  325.  If a per-process JIT registration exists, it will be used over the global JIT 
  326.  registration specified in the CONFIG.SYS. 
  327.  
  328.  Remarks 
  329.  
  330.  The JIT debugger is invoked when an application process encounters a trap or 
  331.  exception not serviced by that application's exception management.  Under 
  332.  normal operations, where a JIT debugger has not been registered with the OS, 
  333.  the application would be terminated by the user on a Hard Error Popup. This 
  334.  disallowed state information from being gathered.  By registering a JIT 
  335.  debugger with the OS, the OS will launch the JIT debugger in place of the Hard 
  336.  Error popup. 
  337.  
  338.  The JIT debugger should attach to the dying process allowing the user to debug 
  339.  the dying process using a conventional debug program or just gather state 
  340.  debugger (unattended).  A state debugger would gather required information to 
  341.  determine the state of the process dying; e.g., stack, registers, addresses, 
  342.  storage, etc.  Once the state is gathered, the state debugger could save it to 
  343.  a log and terminate the offending process and/or start a new process in place 
  344.  of the old. This is completely customizable in the JIT debugger. 
  345.  
  346.  There are two types of JIT registration supported in OS/2.  The first type is 
  347.  global registration.  This allows the user to register a global debugger for 
  348.  the entire OS in the CONFIG.SYS.  This debugger will be launched for any 
  349.  process in the OS that has an error.  The global debugger will not support 
  350.  launching a PM (Presentation Manager(R)) JIT debugger.  This has to be a VIO 
  351.  application (or one that produces no screen output) because of the 
  352.  organization of the boot cycle at which a JIT debugger can be invoked.  The 
  353.  global JIT registration is done before the loading of device drivers, IFS, 
  354.  CALLS, and RUNS.  This enables JIT support for all of these types of files. 
  355.  
  356.  The syntax for the CONFIG.SYS is as follows 
  357.  
  358.  JITDBGREG=[JIT_PathName] [arguments] 
  359.  
  360.  Refer to Buffer under parameters section above to see how [JIT_PathName] and 
  361.  [arguments] are used. 
  362.  
  363.  Example 
  364.  
  365.  JITDBGREG=c \os2\MYJITDBG.EXE /Tn /K /PID%d 
  366.  
  367.  The second type of JIT registration is the per-process registration. This type 
  368.  of registration allows the user to register any type of debugger including PM 
  369.  and VIO using the DBG_C_RegDbg command above. 
  370.  
  371.  Attention  The JIT debugger writer needs to be aware of the environment that 
  372.  the JIT is being used in because of PM and VIO considerations for starting the 
  373.  debugger in regards session management and screen groups. 
  374.  
  375.  Note:  For kernel debugger users there is an option to turn off the JIT 
  376.         debugger support when trying to catch traps in the kernel debugger. See 
  377.         the .on, .of and .oq switches in the kernel debugger help. 
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ 3.4. DBG_C_QueryDebug ΓòÉΓòÉΓòÉ
  381.  
  382. Debug Command 36  Query JIT (Just-in-Time) Debugger Registered Command 
  383.  
  384. Parameters 
  385.  
  386.  Pid    Process of ID of debuggee (Required for per-process entry) 
  387.  
  388.  Cmd    DBG_C_QueryDebug 
  389.  
  390.  Addr   Registration Flags 
  391.  
  392.         DBGQ_JIT_GLOBAL Query registered global debugger 
  393.  
  394.         DBGQ_JIT_PERPROC Query registered per-process debugger 
  395.  
  396.  Buffer A pointer to the buffer where the fully-qualified path name of the JIT 
  397.         debugger is returned. 
  398.  
  399.  Len    Size of Buffer in bytes 
  400.  
  401.  Value  Error code, if any 
  402.  
  403.         ERROR_INSUFFICIENT_BUFFER Buffer too small 
  404.  
  405.         ERROR_INVALID_FLAG_NUMBER Invalid Registration Flag 
  406.  
  407.  Returns 
  408.  
  409.  This command returns the specified query form the operating system of the 
  410.  registered debugger. The buffer will contain NULL if no debugger is 
  411.  registered. 
  412.  
  413.  The only DosDebug notifications that are returned by this command are 
  414.  DBG_N_Success and DBG_N_Error. 
  415.  
  416.  Remarks 
  417.  
  418.  The DBG_C_QueryDbg command returns the registered JIT debugger from a process 
  419.  or the system (Global). The buffer contains the JIT debugger full path name 
  420.  and any arguments specified to the debugger. 
  421.  
  422.  
  423. ΓòÉΓòÉΓòÉ 4. Device Helper (DevHlp) Services and Function Codes ΓòÉΓòÉΓòÉ
  424.  
  425. DevHlp services include 
  426.  
  427. Service                 Code    Description
  428. DevHlp_CloseFile        80h     Close file (system
  429.                                 initialization time only)
  430. DevHlp_FreeCtxHook      64h     Free context hook
  431. DevHlp_FileOpen         7Fh     Open file (at initialization)
  432. DevHlp_GetDosVar        24h     Return address of kernel
  433.                                 variable
  434. DevHlp_KillProc         7Dh     Kill process unconditionally
  435. DevHlp_OpenFile         7Fh     Open file (system initialization
  436.                                 time only)
  437. DevHlp_PerfSysTrace     45h     Write Software Trace information
  438.                                 to STRACE buffer
  439. DevHlp_QSysState        7Eh     Get system status information
  440. DevHlp_ReadFile         81h     Read (system initialization time
  441.                                 only)
  442. DevHlp_ReadFileAt       82h     Seek and read (system
  443.                                 initialization time only)
  444. DevHlp_RegisterKDD      83h     Register driver with kernel
  445.                                 debugger
  446. DevHlp_SysTrace         28h     Add information to System Trace
  447.                                 buffer
  448.  
  449. System event notification 
  450.  
  451. Event                 Index     Description
  452. event_POWER           9         Power off event
  453.  
  454.  
  455. ΓòÉΓòÉΓòÉ 4.1. DevHlp_CloseFile ΓòÉΓòÉΓòÉ
  456.  
  457. DevHlp_CloseFile is used by base device drivers to close a file previously 
  458. opened using DevHlp_OpenFile. 
  459.  
  460.  Calling Sequence in Assembler 
  461.  
  462.                       LES   DI, FileClose
  463.                       MOV   DL, DevHlp_CloseFile
  464.  
  465.                       CALL  [Device_Help]
  466.  
  467.            ES  DI points to a FILEIOINFO structure defined as follows 
  468.  
  469.                       FILEIOINFO struc
  470.                       length        dw     2    ; length of imbedded fle system operation structure
  471.                       ;                           must contain value 2 for CloseFile
  472.                       FCLOSE struc
  473.                       reserved      dw     ?    ; reserved
  474.                       FCLOSE        ends
  475.                       ;
  476.                       FILEIOINFO    ends
  477.  
  478.  Results in Assembler 
  479.  
  480.             C  Clear if the file is closed. AX = zero.. 
  481.  
  482.             C  Set if error. AX = Error Code. Possible errors 
  483.  
  484.            24 ERROR_BAD_LENGTH The length in the FILEIOINFO structure is 
  485.                           invalid. 
  486.  
  487.  Calling Sequence in C 
  488.  
  489.                       #include  "dhcalls.h"
  490.  
  491.            USHORT APIENTRY DevHlp_CloseFile ( PFILEIOINFO pFileClose) 
  492.  
  493.            pFILEIOINFO  input Pointer to the FILEIOINFO structure defined as 
  494.                           follows 
  495.  
  496.                                                     typedef struct FOPEN {
  497.                                                             PSZ    FileName;   /* (input) pointer to file name */
  498.                                                             ULONG  FileSize;   /* (output) size of file returned by FileOPen */
  499.                                                     } FILEOPEN;
  500.  
  501.                                                     typedef struct FCLOSE {
  502.                                                             USHORT  reserved   /* reserved */
  503.                                                     } FILECLOSE;
  504.  
  505.                                                     typedef struct FREAD {
  506.                                                             PBYTE Buffer;      /* (input) pointer to input buffer */
  507.                                                             ULONG ReadSize;    /* (input) number of bytes to read fromfile */
  508.                                                     } FILEREAD;
  509.  
  510.                                                     typedef struct FREADAT {
  511.                                                             PBYTE Buffer;        /* (input) pointer to input buffer */
  512.                                                             ULONG ReadSize;      /* (input) number of bytes to read from file */
  513.                                                             ULONG StartPosition  /* (input) starting file position relative to
  514.                                                                                      the beginning of the file */
  515.                                                     } FILEREADAT;
  516.  
  517.                                                     typedef union FILEIOOP {
  518.                                                             struct FOPEN FileOpen;
  519.                                                             struct FCLOSE FileClose;
  520.                                                             struct FREAD FileRead;
  521.                                                             struct FREADAT FileReadAt;
  522.                                                     } FILEIOOP;
  523.  
  524.                                                     typedef struc _DDFileIo {
  525.                                                             USHORT Length; /* (input) length of imbedded structure */
  526.                                                             FILEIOOP Data; /* (input) imbedded file system operation structure */
  527.                                                     } FILEIOINFO, FAR * PFILEIOINFO
  528.  
  529.  Results in C 
  530.            Success Indicator  0 if file was closed.. 
  531.  
  532.            24 ERROR_BAD_LENGTH Length in the FILEIOINFO structure is invalid. 
  533.  
  534.  Remarks 
  535.            DevHlp_FileClose may be called at initialization time only. It 
  536.            provides a primitive interface to the mini-IFS or micro_IFS at 
  537.            initialization. 
  538.  
  539.            Using this interface, one file only may be opened at a time. No 
  540.            handle is assigned by open. The file closed is assumed to be the 
  541.            most recent opened using DevHlp_OpenFile. 
  542.  
  543.  
  544. ΓòÉΓòÉΓòÉ 4.2. DevHlp_FreeCtxHook ΓòÉΓòÉΓòÉ
  545.  
  546. DevHlp_FreeCtxHook frees a context hook allocated by the 
  547. DevHlp_AllocateCtxHook. 
  548.  
  549.  Calling Sequence in Assembler 
  550.  
  551.                       MOV   EAX, Hook_Handle
  552.                       MOV   DL,  DevHlp FreeCtxHook
  553.                       CALL   Device Help
  554.  
  555.  Results in Assembler 
  556.  
  557.            C               C  Clear if hook freed. 
  558.  
  559.                           EAX = 0 
  560.  
  561.            C               C  Set if error. 
  562.  
  563.                           EAX = Error code 
  564.  
  565.  Calling Sequence in C 
  566.  
  567.                       #include  "dhcalls.h"
  568.  
  569.            USHORT APIENTRY DevHelp_FreeCtxHook ( ULONG HookHandle) 
  570.  
  571.  Results in C 
  572.            Success Indicator  0 if hook successfully freed. 
  573.  
  574.  Remarks 
  575.            The state of the interrupt flag is not preserved across calls to 
  576.            this DevHlp. 
  577.  
  578.  
  579. ΓòÉΓòÉΓòÉ 4.3. DevHlp_GetDosVar ΓòÉΓòÉΓòÉ
  580.  
  581. DevHlp_GetDosVar returns the address of a kernel variable. 
  582.  
  583.  Calling Sequence in Assembler 
  584.  
  585.                       MOV   AL, index                ; Index wanted.
  586.                       MOV   CX, VarMember            ; Only used by index 14 and 16.
  587.                       MOV   DL, DevHlp GetDOSVar
  588.  
  589.                       CALL   Device Help
  590.  
  591.  Results in Assembler 
  592.  
  593.             C  Clear if successful. AX BX points to the index. 
  594.  
  595.             C  Set if error. 
  596.  
  597.  Calling Sequence in C 
  598.  
  599.                       #include  "dhcalls.h"
  600.  
  601.            USHORT APIENTRY DevHelp_GetDOSVar ( USHORT VarNumber, USHORT 
  602.                           VarMember, PPVOID KernelVar ) 
  603.  
  604.  VarNumber (USHORT) 
  605.            The index into the list of read only variables 
  606.  
  607.                       DHGETDOSV_SYSINFOSEG                                       1
  608.                       DHGETDOSV_LOCINFOSEG                                       2
  609.                       DHGETDOSV_VECTORSDF                                        4
  610.                       DHGETDOSV_VECTORREBOOT                                     5
  611.                       DHGETDOSV_VECTORMSATS                                      6
  612.                       DHGETDOSV_YIELDFLAG                                        7
  613.                       DHGETDOSV_TCYIELDFLAG                                      8
  614.                       DHGETDOSV_DOSCODEPAGE                                      11
  615.                       DHGETDOSV_INTERRUPTLEV                                     13
  616.                       DHGETDOSV_DEVICECLASSTABLE                                 14
  617.                       DHGETDOSV_DMQSSELECTOR                                     15
  618.                       DHGETDOSV_APMINFO                                          16
  619.                       DHGETDOSV_APM11INFO                                        17
  620.                       DHGETDOSV_CPUMODE                                          18
  621.                       DHGETDOSV_CPUMODE                                          19
  622.                       DHGETDOSV_TOTALCPUS                                        20
  623.  
  624.  VarMember (USHORT) 
  625.            Applicable only to VarNumber 14 or 16. 
  626.  
  627.            For VarNumber = 14 
  628.  
  629.                       VarMember=1                     (Disk) has a maximum of 32
  630.                                                       entries in the DCT.
  631.                       VarMember=2                     Mouse) has a maximum of 3
  632.                                                       entries in the DCT.
  633.  
  634.            For VarNumber = 16 
  635.  
  636.                       VarMember=0                     Query presence of APM BIOS.
  637.                       VarMember=1                     Query presence of APM BIOS and
  638.                                                       establish connection.
  639.  
  640.  KernelVar (PPVOID) 
  641.            Pointer to the address of requested variable to be returned. 
  642.  
  643.  Results in C 
  644.  
  645.   Success Indicator               Clear if successful; returns
  646.                                   address of the requested
  647.                                   variable in KernelVar.
  648.   Possible errors                 None.
  649.  
  650.  Remarks 
  651.  
  652.  The following table contains the list of read-only variables 
  653.  
  654.   Index      Variable Description
  655.     1        GlobalInfoSeg WORD.  Valid at task time and interrupt
  656.              time, but not at INIT time.  See below.
  657.     2        LocalInfoSeg DWORD.  Selector/segment address of local
  658.              information segment for the current Local Descriptor
  659.              Table (LDT).  Valid only at task time.  See below.
  660.     3        Reserved.
  661.     4        VectorSDF DWORD.  Pointer to the stand-alone dump
  662.              facility. Valid at task time and interrupt time.
  663.     5        VectorReboot DWORD.  Pointer to restart the operating
  664.              system. Valid at task time and interrupt time.
  665.     6        Reserved.
  666.     7        YieldFlag BYTE.  Indicator for performing yields.
  667.              Valid only at task time.
  668.     8        TCYieldFlag BYTE.  Indicator for performing
  669.              time-critical yields. Valid only at task time.
  670.     9        Reserved.
  671.    10        Reserved.
  672.    11        DOS session Code Page Tag pointer  DWORD.
  673.              Segment offset of the DOS session s current code page
  674.              tag.  Valid only at task time.
  675.    12        Reserved.
  676.    13        Interrupt Level
  677.    14        DeviceClass Table (See DH_RegisterDeviceClass)
  678.    15        DMQS Selector   Point to XGA adapter.  DMQS
  679.              information offset is assumed to start at zero.
  680.    16        APMInfo APMStruc. Advanced Power Management BIOS
  681.              Information
  682.   17         APMInfo  APMStruc version 1.1. Advanced Power
  683.              Management BIOS Information
  684.   18         SMP_Active  DWORD Information on the operating system
  685.              (OS) support for more than 1 CPU. Returns 1 if the OS
  686.              has SMP support and 0 if the OS has uniprocessor
  687.              support.
  688.   19         PSDInfo.psd_flags  DWORD PSD status area where several
  689.              pieces of useful information about the PSD can be
  690.              obtained. After obtaining the variable address, the
  691.              caller must test the bit for the desired aspect of the
  692.              PSD. The PSD flags definition is as follows
  693.              PSD_INITIALIZED (0x80000000) PSD has been initialized
  694.              PSD_INSTALLED (0x40000000) PSD has been installed
  695.              PSD_ADV_INT_MODE (0x20000000) PSD is in advaanced
  696.              interrupt mode PSD_KERNEL_PIC (0x10000000) Let the
  697.              kernel interrupt manager EOI
  698.   20         cProcessors  DWORD Information for the Multi-Processor
  699.              environment. Indicates the number of processors
  700.              currently running in the MP environment. A value of 1
  701.              is returned in Uni-Processor environment.
  702.  
  703.  GlobalInfoSeg (PSEL)  Address of the global information segment structure, as 
  704.                        defined below 
  705.  
  706.                        Time (ULONG)                   Time in seconds since 
  707.                                                       1/1/1970. 
  708.  
  709.                        Millisecs (ULONG)              Time in milliseconds. 
  710.  
  711.                        Hours (UCHAR)                  Current hour. 
  712.  
  713.                        Minute (UCHAR)                 Current minute. 
  714.  
  715.                        Seconds (UCHAR)                Current second. 
  716.  
  717.                        HundredSec (UCHAR)             Current hundreth of a 
  718.                                                       second. 
  719.  
  720.                        TimeZone (USHORT)              Minutes from UTC.  If 
  721.                                                       FFFFH, TimeZone is 
  722.                                                       undefined. 
  723.  
  724.                        Interval (USHORT)              Timer interval in tenths 
  725.                                                       of milliseconds. 
  726.  
  727.                        Day (UCHAR)                    Day. 
  728.  
  729.                        Month (UCHAR)                  Month. 
  730.  
  731.                        Year (USHORT)                  Year. 
  732.  
  733.                        Weekday (UCHAR)                Day of the week 
  734.  
  735.                                                       0       Sunday 
  736.                                                       1       Monday 
  737.                                                       2       Tuesday 
  738.                                                       3       Wednesday 
  739.                                                       4       Thursday 
  740.                                                       5       Friday 
  741.                                                       6       Saturday 
  742.  
  743.                        MajorVersion (UCHAR)           Major version number. 
  744.  
  745.                        MinorVersion (UCHAR)           Minor version number. 
  746.  
  747.                        Revision (UCHAR)               Revision letter. 
  748.  
  749.                        CurrentSession (UCHAR)         Current foreground 
  750.                                                       full-screen session. 
  751.  
  752.                        MaxNumSessions (UCHAR)         Maximum number of 
  753.                                                       full-screen sessions. 
  754.  
  755.                        HugeShift (UCHAR)              Shift count for huge 
  756.                                                       segments. 
  757.  
  758.                        ProtModeInd (UCHAR)            Protect-mode-only 
  759.                                                       indicator 
  760.  
  761.                                                       0       DOS and OS/2 
  762.                                                               sessions. 
  763.                                                       1       OS/2 session 
  764.                                                               only. 
  765.  
  766.                        LastProcess (USHORT)           Process ID of the current 
  767.                                                       foreground process. 
  768.  
  769.                        DynVarFlag (UCHAR)             Dynamic variation flag 
  770.  
  771.                                                       0       Absolute. 
  772.                                                       1       Enabled. 
  773.  
  774.                        MaxWait (UCHAR)                Maximum wait in seconds. 
  775.  
  776.                        MinTimeSlice (USHORT)          Minimum time slice in 
  777.                                                       milliseconds. 
  778.  
  779.                        MaxTimeSlice (USHORT)          Maximum time slice in 
  780.                                                       milliseconds. 
  781.  
  782.                        BootDrive (USHORT)             Drive from which the 
  783.                                                       system startup occurred 
  784.  
  785.                                                       1       Drive A 
  786.                                                       2       Drive B 
  787.                                                       n       Drive n. 
  788.  
  789.                        TraceFlags (UCHAR)             Thirty-two system trace 
  790.                                                       major code flags.  Each 
  791.                                                       bit corresponds to a 
  792.                                                       trace major code 00H-FFH. 
  793.                                                       The most significant bit 
  794.                                                       (left-most) of the first 
  795.                                                       byte corresponds to major 
  796.                                                       code 00H.  Values are 
  797.  
  798.                                                       0       Trace disabled. 
  799.                                                       1       Trace enabled. 
  800.  
  801.                        MaxTextSessions (UCHAR)        Maximum number of VIO 
  802.                                                       windowable sessions. 
  803.  
  804.                        MaxPMSessions (UCHAR)          Maximum number of 
  805.                                                       Presentation Manager 
  806.                                                       sessions. 
  807.  
  808.  LocalInfoSeg (PSEL)   Address of the selector for the local information 
  809.                        segment structure, as defined below 
  810.  
  811.                        ProcessID (PID)                 Current Process ID. 
  812.  
  813.                        ParentProcessID (PID)           Parent Process ID. 
  814.  
  815.                        ThreadPrty (USHORT)             Priority of current 
  816.                                                        thread. 
  817.  
  818.                        ThreadID (TID)                  Current Thread ID. 
  819.  
  820.                        SessionID (USHORT)              Current Session ID. 
  821.  
  822.                        ProcStatus (UCHAR)              Process status. 
  823.  
  824.                        Unused (UCHAR)                  Unused. 
  825.  
  826.                        ForegroundProcess (BOOL)        Current process is in 
  827.                                                        foreground (has keyboard 
  828.                                                        focus) 
  829.  
  830.                                                         1       Implies YES 
  831.                                                        0        Implies NO. 
  832.  
  833.                        TypeProcess (UCHAR)             Type of process 
  834.  
  835.                                                        0       Full screen 
  836.                                                                protect-mode 
  837.                                                                session. 
  838.                                                        1       Requires real 
  839.                                                                mode. 
  840.                                                        2       VIO windowable 
  841.                                                                protect-mode 
  842.                                                                session. 
  843.                                                        3       Presentation 
  844.                                                                Manager 
  845.                                                                protect-mode 
  846.                                                                session. 
  847.                                                        4       Detached 
  848.                                                                protect-mode 
  849.                                                                process. 
  850.  
  851.                        Unused (UCHAR)                  Unused. 
  852.  
  853.                        EnvironmentSel (SEL)            Environment selector. 
  854.  
  855.                        CmdLineOff (USHORT)             Command line offset in 
  856.                                                        the segment addressed by 
  857.                                                        EnvironmentSel. 
  858.  
  859.                        DataSegLen (USHORT)             Length of the data 
  860.                                                        segment in bytes. 
  861.  
  862.                        StackSize (USHORT)              Stack size in bytes. 
  863.  
  864.                        HeapSize (USHORT)               Heap size in bytes. 
  865.  
  866.                        HModule (UHMODULE)              Module handle. 
  867.  
  868.                        DSSel (SEL)                     Data segment selector. 
  869.  
  870.  APMInfo               Advanced Power Management BIOS Information, as defined 
  871.                        below 
  872.  
  873.                        APM CodeSeg (WORD)             APM 16-bit code segment 
  874.                                                       (real-mode segment base 
  875.                                                       address). 
  876.  
  877.                                                                                                             From APM BIOS, INT 15h AX=5302H.
  878.  
  879.                        APM DataSeg (WORD)             APM 16-bit data segment 
  880.                                                       (real-mode segment base 
  881.                                                       address). 
  882.  
  883.                                                                                                             From APM BIOS, INT 15h AX=5302H.
  884.  
  885.                        APM Offset  (WORD)             Offset to entry point. 
  886.  
  887.                                                                                                             From APM BIOS, INT 15h AX=5302H.
  888.  
  889.                        APM Flags  (WORD)              APM capability flags. 
  890.  
  891.                                                                                                             From APM BIOS, INT 15h AX=5300H.
  892.  
  893.                        APM Level  (WORD)              APM revision level. 
  894.  
  895.                                                                                                             From APM BIOS, INT 15h AX=5300H.
  896.  
  897.                        APM CPUIdle (6 bytes (DF))     APM Services Entry Point 
  898.                                                       for CPU Idle and Busy 
  899.                                                       Functions. 
  900.  
  901.                        Note:  APM CodeSeg and APM DataSeg are segment 
  902.                               addresses, not selectors. It is the 
  903.                               responsibility of the device driver to convert 
  904.                               the segment address to a valid protect-mode 
  905.                               selector. 
  906.  
  907.  The first time GetDOSVar is called at device-driver initialization with index 
  908.  (AL) = 10H and CX = 1, the system sets the values for APM CodeSeg, APM 
  909.  DataSeg, APM Offset, APM Flags, and APM Level. On return, AX BX points to the 
  910.  APMInfo structure. 
  911.  
  912.  If GetDOSVar is called at device-driver initialization with index (AL) = 10h 
  913.  and CX = 0, the system sets the values for APM Flags and APM Level. On return, 
  914.  AX BX points to the APMInfo structure. Other fields in the APMInfo structure 
  915.  might have been set by a previous call to GetDOSVar with index = 10h and CX = 
  916.  1. 
  917.  
  918.  If GetDOSVar is called after device-driver initialization with index (AL) = 
  919.  10H, no information in the APMInfo structure is modified. On return, AX BX 
  920.  points to the APMInfo structure. 
  921.  
  922.  APM CPUIdle contains the address of the CPU Idle and Busy processing routines 
  923.  from the Power Management Services device driver. This variable is initially 
  924.  empty (NULL) until Power Management Services loads and places the addresses 
  925.  for the CPU Idle and Busy routines into the variable area. The variable 
  926.  address must be the 16 16 Selector Offset. The Offset is 0-extended to 32 
  927.  bits, and the value must be represented in 16 32 format. The APM CPUIdle 
  928.  function utilizes the AX register as the control selection flag for BUSY 
  929.  (AX=00001H) and IDLE (AX=0000H) requests. 
  930.  
  931.  These variables are maintained by the kernel for the benefit of physical 
  932.  device drivers.  Notice that the address returned is the address of the 
  933.  indicated variable; the variable can contain a vector to some facility, or it 
  934.  can contain a structure. 
  935.  
  936.  
  937. ΓòÉΓòÉΓòÉ 4.4. DevHlp_KillProc ΓòÉΓòÉΓòÉ
  938.  
  939. DevHlp_KillProc kills a process unconditionally. 
  940.  
  941.  Calling Sequence in Assembler 
  942.  
  943.                       MOV   BX, pid
  944.                       MOV   DL, DevHlp_KillProc
  945.  
  946.                       CALL  [Device_Help]
  947.  
  948.  Results in Assembler 
  949.  
  950.             C  Clear if the process is killed. AX = zero. 
  951.  
  952.             C  Set if error. AX = Error code. 
  953.  
  954.            Possible errors 
  955.  
  956.            217 ERROR_ZOMBIE_PROCESS Process is already dead pending collection 
  957.                           of result codes by parent. 
  958.  
  959.            303 ERROR_INVALID_PROCID PID is invalid. 
  960.  
  961.  Calling Sequence in C 
  962.            There is no direct C calling Sequence. 
  963.  
  964.  Remarks 
  965.            The process is killed unconditionally. Signal and exception handlers 
  966.            are not run. This Device Help may be called at Task Time only. 
  967.  
  968.  
  969. ΓòÉΓòÉΓòÉ 4.5. DevHlp_OpenFile ΓòÉΓòÉΓòÉ
  970.  
  971. DevHlp_OpenFile is used by base device drivers to open a file for read access 
  972. during initalization. 
  973.  
  974.  Calling Sequence in Assembler 
  975.  
  976.  
  977.                       LES   DI, FileOpen            ; Point to FILEIOINFO structure
  978.                       MOV   DL, DevHlp_OpenFile
  979.  
  980.                       CALL   [Device_Help]
  981.  
  982.            ES  DI points to a FILEIOINFO structure defined as follows 
  983.  
  984.                       FILEIOINFO struc
  985.                       length        dw     8    ; length of imbedded fle system operation structure
  986.                       ;
  987.                       FOPEN struc
  988.                       name          dd     ?    ; 16 16 pointer to ASCIZ pathname
  989.                       fsize         dd     ?    ; returned  size of file
  990.                       FOPEN         ends
  991.                       ;
  992.                       FILEIOINFO    ends
  993.  
  994.  Results in Assembler 
  995.  
  996.             C  Clear if file is opened. AX = zero. 
  997.  
  998.             C  Set if error. AX = Error code. Possible errors 
  999.  
  1000.            24 ERROR_BAD_LENGTH The length in the FILEIOINFO structure is 
  1001.                           invalid. 
  1002.  
  1003.  Calling Sequence in C 
  1004.  
  1005.                       #include  "dhcalls.h"
  1006.  
  1007.                       USHORT APIENTRY DevHelp_OpenFile (PFILEIOINFO pFileOpen);
  1008.  
  1009.            USHORT APIENTRY DevHlp_OpenFile ( PFILEIOINFO pFileOpen) 
  1010.  
  1011.            pFILEIOINFO  input Pointer to the FILEIOINFO structure defined as 
  1012.                           follows 
  1013.  
  1014.                                                     typedef struct FOPEN {
  1015.                                                             PSZ    FileName;   /* (input) pointer to file name */
  1016.                                                             ULONG  FileSize;   /* (output) size of file returned by FileOpen */
  1017.                                                     } FILEOPEN;
  1018.  
  1019.                                                     typedef struct FCLOSE {
  1020.                                                             USHORT  reserved   /* reserved */
  1021.                                                     } FILECLOSE;
  1022.  
  1023.                                                     typedef struct FREAD {
  1024.                                                             PBYTE Buffer;     /* (input) pointer to input buffer */
  1025.                                                             ULONG ReadSize;   /* (input) number of bytes to read fromfile */
  1026.                                                     } FILEREAD;
  1027.  
  1028.                                                     typedef struct FREADAT {
  1029.                                                             PBYTE Buffer;        /* (input) pointer to input buffer */
  1030.                                                             ULONG ReadSize;      /* (input) number of bytes to read from file */
  1031.                                                             ULONG StartPosition  /* (input) starting file position relative to
  1032.                                                                                      the beginning of the file */
  1033.                                                     } FILEREADAT;
  1034.  
  1035.                                                     typedef union FILEIOOP {
  1036.                                                             struct FOPEN FileOpen;
  1037.                                                             struct FCLOSE FileClose;
  1038.                                                             struct FREAD FileRead;
  1039.                                                             struct FREADAT FileReadAt;
  1040.                                                     } FILEIOOP;
  1041.  
  1042.                                                     typedef struc _DDFileIo {
  1043.                                                             USHORT Length; /* (input) length of imbedded structure */
  1044.                                                             FILEIOOP Data; /* (input) imbedded file system operation structure */
  1045.                                                     } FILEIOINFO, FAR * PFILEIOINFO
  1046.  
  1047.  Results in C 
  1048.            Success Indicator  0 if file was opened.. 
  1049.  
  1050.            24 ERROR_BAD_LENGTH Length in the FILEIOINFO structure is invalid. 
  1051.  
  1052.  Remarks 
  1053.            DevHlp_OpenFile may be called at initialization time only. It 
  1054.            provides a primitive interface to the mini-IFS or micro_IFS at 
  1055.            initialization time. 
  1056.  
  1057.            Drive and path information is ignored. The system searches for the 
  1058.            file in the root, \OS2 and \OS2\BOOT directories of the boot 
  1059.            drive/device. 
  1060.  
  1061.            Using this interface, one file only may be opened at a time. No 
  1062.            handle is assigned. Subsequent read and close requests assume the 
  1063.            file is the most recent opened using DevHlp_OpenFile. 
  1064.  
  1065.  
  1066. ΓòÉΓòÉΓòÉ 4.6. DevHlp_PerfSysTrace ΓòÉΓòÉΓòÉ
  1067.  
  1068. DevHlp_PerfSysTrace writes software trace information to the STRACE buffer. 
  1069.  
  1070.  Calling Sequence in Assembler 
  1071.  
  1072.                       MOV   AX, MajorCode
  1073.                       MOV   BX, TraceSize
  1074.                       MOV   CX, MinorCode
  1075.                       LDS   SI, TraceData
  1076.                       MOV   DL, DevHlp_PerfSysTrace
  1077.                       CALL  DevHlp
  1078.                       JC    Error
  1079.  
  1080.  Results in Assembler 
  1081.  
  1082.            AX = return code. 
  1083.  
  1084.            Possible values 
  1085.  
  1086.            0 NO_ERROR     Data written to trace buffer. 
  1087.  
  1088.            32902 ERROR_NOMEMORY Trace buffer has not been allocated. 
  1089.  
  1090.  Calling Sequence in C 
  1091.  
  1092.                       #include "dhcalls.h"
  1093.            USHORT APIENTRY DevHelp_PerfSysTrace (USHORT Major, USHORT 
  1094.            Minor,USHORT TraceSize, PBYTE TraceData) 
  1095.  
  1096.  Remarks 
  1097.            A trace buffer must be allocated, wia the STRACE INIT command, 
  1098.            before attempting to write trace data. 
  1099.  
  1100.            Tracing stops once the trace buffer fills up. No error indication is 
  1101.            returned. Subsequent calls to DevHelp_PerfSysTrace return 
  1102.            immediately without writing any data. 
  1103.  
  1104.  
  1105. ΓòÉΓòÉΓòÉ 4.7. DevHlp_QSysState ΓòÉΓòÉΓòÉ
  1106.  
  1107. DevHlp_QSysState is used by physical device drivers to obtain system status 
  1108. information.. 
  1109.  
  1110.  CallingSequence in Assembler 
  1111.  
  1112.                       MOV   EAX, EntityList
  1113.                       MOV   EBX, EntityLevel
  1114.                       MOV   EDI, pidtid
  1115.                       MOV   ESI, pDataBuf
  1116.                       MOV   ECX, cbDataBuf
  1117.                       MOV   DL,  DevHlp_QSysState
  1118.                       CALL  [Device_Help]
  1119.  
  1120.  
  1121.  Results in Assembler 
  1122.  
  1123.            'C' Clear if process killed. AX = zero. 
  1124.  
  1125.            'C" Set if error. 
  1126.  
  1127.            Possible errors 
  1128.  
  1129.            87 ERROR_INVALID_PARAMETER Invalid parameter specified. 
  1130.  
  1131.            111 ERROR_BUFFER_OVERFLOW Data buffer is too small to hold all 
  1132.                           returned information. 
  1133.  
  1134.            115 ERROR_PROTECTION_VIOLATION Unable to store in to data buffer. 
  1135.  
  1136.            124 ERROR_INVALID_LEVEL Data buffer is too small to hold all 
  1137.                           returned information. 
  1138.  
  1139.  Calling Sequence in C 
  1140.            There is no direct C calling Sequence. 
  1141.  
  1142.  Remarks 
  1143.            DevHlp_QSysState is functionally equivalent to DosQuerySysState. See 
  1144.            DosQuerySysState for information on the entities that may be 
  1145.            requested and the format of the entities returned. This Device Help 
  1146.            may be call at Task Time only. 
  1147.  
  1148.  
  1149. ΓòÉΓòÉΓòÉ 4.8. DevHlp_ReadFile ΓòÉΓòÉΓòÉ
  1150.  
  1151. DevHlp_ReadFile is used by base device drivers to read a file previously opened 
  1152. using DevHlp_OpenFile. 
  1153.  
  1154.  Calling Sequence in Assembler 
  1155.  
  1156.                       LES   DI, ReadFile
  1157.                       MOV   DL, DevHlp_ReadFile
  1158.  
  1159.                       CALL  [Device_Help]
  1160.  
  1161.            ES  DI points to a FILEIOINFO structure defined as follows 
  1162.  
  1163.                       FILEIOINFO struc
  1164.                       length        dw     8    ; length of imbedded fle system operation structure
  1165.                       ;
  1166.                       FREAD struc
  1167.                       Buffer        dd     ?    ; 16 16 pointer to the input buffer
  1168.                       ReadSize      dd     ?    ; length of data to read
  1169.                       FREAD         ends
  1170.                       ;
  1171.                       FILEIOINFO    ends
  1172.  
  1173.  Results in Assembler 
  1174.  
  1175.             C  Clear if the file is closed. AX = zero. 
  1176.  
  1177.             C  Set if error. Possible errors 
  1178.  
  1179.            24 ERROR_BAD_LENGTH The length in the FILEIOINFO structure is 
  1180.                           invalid. 
  1181.  
  1182.  Calling Sequence in C 
  1183.  
  1184.                       #include  "dhcalls.h"
  1185.  
  1186.            USHORT APIENTRY DevHelp_ReadFile ( PFILEIOINFO pfileread) 
  1187.  
  1188.            Pointer to the FILEIOINFO structure defined as follows 
  1189.  
  1190.                       typedef struct FOPEN {
  1191.                               PSZ    FileName;   /* (input) pointer to file name */
  1192.                               ULONG  FileSize;   /* (output) size of file returned by FileOpen */
  1193.                       } FILEOPEN;
  1194.  
  1195.                       typedef struct FCLOSE {
  1196.                               USHORT  reserved   /* reserved */
  1197.                       } FILECLOSE;
  1198.  
  1199.                       typedef struct FREAD {
  1200.                               PBYTE Buffer;      /* (input) pointer to input buffer */
  1201.                               ULONG ReadSize;    /* (input) number of bytes to read fromfile */
  1202.                       } FILEREAD;
  1203.  
  1204.                       typedef struct FREADAT {
  1205.                               PBYTE Buffer;        /* (input) pointer to input buffer */
  1206.                               ULONG ReadSize;      /* (input) number of bytes to read from file */
  1207.                               ULONG StartPosition  /* (input) starting file position relative to
  1208.                                                        the beginning of the file */
  1209.                       } FILEREADAT;
  1210.  
  1211.                       typedef union FILEIOOP {
  1212.                               struct FOPEN FileOpen;
  1213.                               struct FCLOSE FileClose;
  1214.                               struct FREAD FileRead;
  1215.                               struct FREADAT FileReadAt;
  1216.                       } FILEIOOP;
  1217.  
  1218.                       typedef struc _DDFileIo {
  1219.                               USHORT Length; /* (input) length of imbedded structure */
  1220.                               FILEIOOP Data; /* (input) imbedded file system operation structure */
  1221.                       } FILEIOINFO, FAR * PFILEIOINFO
  1222.  
  1223.  Results in C 
  1224.            Success Indicator  0 if file was read. 
  1225.  
  1226.            24 ERROR_BAD_LENGTH Length in the FILEIOINFO structure is invalid. 
  1227.  
  1228.  Remarks 
  1229.            DevHlp_FileRead may be called at initialization time only. It 
  1230.            provides a primitive interface to the mini-IFS or micro_IFS at 
  1231.            initialization time. 
  1232.  
  1233.            The file is read from the current file position. After a successful 
  1234.            read, the current file position is updated. 
  1235.  
  1236.            Using this interface only one file may be opened at a time. No 
  1237.            handle is assigned by open. The file read is assumed to be the most 
  1238.            recent opened using DevHlp_OpenFile. 
  1239.  
  1240.  
  1241. ΓòÉΓòÉΓòÉ 4.9. DevHlp_ReadFileAt ΓòÉΓòÉΓòÉ
  1242.  
  1243. DevHlp_ReadFileAt is used by base device drivers to read a file previously 
  1244. opened using DevHlp_OpenFile from a specified file location. 
  1245.  
  1246.  Calling Sequence in Assembler 
  1247.  
  1248.                       LES   DI, ReadFileAt
  1249.                       MOV   DL, DevHlp_ReadFileAt
  1250.  
  1251.                       CALL  [Device_Help]
  1252.  
  1253.            ES  DI points to a FILEIOINFO structure defined as follows 
  1254.  
  1255.                       FILEIOINFO struc
  1256.                       length        dw   12    ; length of imbedded fle system operation structure
  1257.                       ;
  1258.                       FREADAT struc
  1259.                       Buffer        dd   ?    ; 16 16 pointer to input buffer
  1260.                       Readsize      dd   ?    ; length of data to read
  1261.                       StartPosition dd   ?    ; starting position relative to the beginning of the file
  1262.                       FREADAT       ends
  1263.                       ;
  1264.                       FILEIOINFO    ends
  1265.  
  1266.  Results in Assembler 
  1267.  
  1268.             C  Clear if file is closed. AX = zero. 
  1269.  
  1270.             C  Set if error. AX = Error code. Possible errors 
  1271.  
  1272.            24 ERROR_BAD_LENGTH The length in the FILEIOINFO structure is 
  1273.                           invalid. 
  1274.  
  1275.  Calling Sequence in C 
  1276.  
  1277.                       #include  "dhcalls.h"
  1278.  
  1279.            USHORT APIENTRY DevHelp_FileReadAt (PFILEIOINFO pFileReadAt) 
  1280.  
  1281.            Pointer to the FILEIOINFO structure defined as follows 
  1282.  
  1283.                       typedef struct FOPEN {
  1284.                               PSZ    FileName;   /* (input) pointer to file name */
  1285.                               ULONG  FileSize;   /* (output) size of file returned by FileOpen */
  1286.                       } FILEOPEN;
  1287.  
  1288.                       typedef struct FCLOSE {
  1289.                               USHORT  reserved   /* reserved */
  1290.                       } FILECLOSE;
  1291.  
  1292.                       typedef struct FREAD {
  1293.                               PBYTE Buffer;     /* (input) pointer to input buffer */
  1294.                               ULONG ReadSize;   /* (input) number of bytes to read from file */
  1295.                       } FILEREAD;
  1296.  
  1297.                       typedef struct FREADAT {
  1298.                               PBYTE Buffer;        /* (input) pointer to input buffer */
  1299.                               ULONG ReadSize;      /* (input) number of bytes to read from file */
  1300.                               ULONG StartPosition  /* (input) starting file position relative to
  1301.                                                        the beginning of the file */
  1302.                       } FILEREADAT;
  1303.  
  1304.                       typedef union FILEIOOP {
  1305.                               struct FOPEN FileOpen;
  1306.                               struct FCLOSE FileClose;
  1307.                               struct FREAD FileRead;
  1308.                               struct FREADAT FileReadAt;
  1309.                       } FILEIOOP;
  1310.  
  1311.                       typedef struc _DDFileIo {
  1312.                               USHORT Length; /* (input) length of imbedded structure */
  1313.                               FILEIOOP Data; /* (input) imbedded file system operation structure */
  1314.                       } FILEIOINFO, FAR * PFILEIOINFO
  1315.  
  1316.  Results in C 
  1317.            Success Indicator  0 if file was read. 
  1318.  
  1319.            24 ERROR_BAD_LENGTH Length in the FILEIOINFO structure is invalid. 
  1320.  
  1321.  Remarks 
  1322.            DevHlp_ReadFileAt may be called at initialization time only. It 
  1323.            provides a primitive interface to the mini-IFS or micro_IFS at 
  1324.            initialization time. 
  1325.  
  1326.            The current file position is set according to the StartPosition. The 
  1327.            file is read from that file position. After a successful read, the 
  1328.            current file position is updated. 
  1329.  
  1330.            Using this interface, one file only may be opened at a time. No 
  1331.            handle is assigend by open. The file read is assumed to be the most 
  1332.            recent opened using DevHlp_OpenFile. 
  1333.  
  1334.  
  1335. ΓòÉΓòÉΓòÉ 4.10. DevHlp_SysTrace ΓòÉΓòÉΓòÉ
  1336.  
  1337. DevHlp_SysTrace function provides a service for device drivers to add 
  1338. information to the System Trace buffer. 
  1339.  
  1340.  Calling Sequence in Assembler 
  1341.  
  1342.                       MOV    AX, Major Code
  1343.                       MOV    BX, Length
  1344.                       MOV    CX, Minor Code
  1345.  
  1346.                       LDS    SI, Data
  1347.  
  1348.                       MOV    DL, 28H
  1349.  
  1350.                       CALL   [Device_Help]
  1351.  
  1352.  Results in Assembler 
  1353.  
  1354.            If CF = 0, trace record placed in trace buffer 
  1355.  
  1356.            Else data not traced. 
  1357.  
  1358.            Possible errors 
  1359.  
  1360.                Tracing suspended 
  1361.  
  1362.                Minor code not being traced 
  1363.  
  1364.                PID not being traced 
  1365.  
  1366.                Trace overrun 
  1367.  
  1368.  Calling Sequence in C 
  1369.  
  1370.                       #include  "dhcalls.h"
  1371.  
  1372.            USHORT APIENTRY DevHlp_SysTrace ( USHORT Major, USHORT Minor, USHORT 
  1373.                           Size, PBYTE Datar ) 
  1374.  
  1375.            Major (USHORT) Major trace event code (240 255). 
  1376.  
  1377.            Minor (USHORT) Minor trace event code (0 255). 
  1378.  
  1379.            Size(USHORT)   Length of the variable length area to be recorded (0 
  1380.                           512). 
  1381.  
  1382.            Data (PBYTE)   Pointer to the area to be traced. 
  1383.  
  1384.  Results in C 
  1385.            Success indicator  0. 
  1386.  
  1387.            Possible errors 
  1388.  
  1389.                Data not traced, e.g., major event code is not currently 
  1390.                 selected for tracing. 
  1391.  
  1392.  Remarks 
  1393.            The trace facility maintains an array of 32 bytes (256 bits), in 
  1394.            which each bit represents a major event code. This array is updated 
  1395.            each time the user enables or disables tracing of a major event. The 
  1396.            device driver must check this array before calling DevHlp_SysTrace 
  1397.            to ensure that the major event specified is currently enabled for 
  1398.            tracing. This array is located in the Global InfoSegAll registers 
  1399.            are preserved. 
  1400.  
  1401.            Interrupts are disabled while the trace data is saved and then 
  1402.            re-enabled if they were initially enabled. 
  1403.  
  1404.            DevHlp_SysTrace is synonymous with DevHlp_RAS. 
  1405.  
  1406.  
  1407. ΓòÉΓòÉΓòÉ 5. Control Program Functions ΓòÉΓòÉΓòÉ
  1408.  
  1409. This chapter contains an alphabetic list of the following Control Program 
  1410. functions. 
  1411.  
  1412.      DosAliasMem 
  1413.  
  1414.      DosCancelLockRequestL 
  1415.  
  1416.      DosClose 
  1417.  
  1418.      DosCreateEventSem 
  1419.  
  1420.      DosCreateThread2 
  1421.  
  1422.      DosDumpProcess 
  1423.  
  1424.      DosFindFirst 
  1425.  
  1426.      DosFindNext 
  1427.  
  1428.      DosForceSystemDump 
  1429.  
  1430.      DosGetProcessorStatus 
  1431.  
  1432.      DosListIO 
  1433.  
  1434.      DosListIOL 
  1435.  
  1436.      DosOpen 
  1437.  
  1438.      DosOpenL 
  1439.  
  1440.      DosPerfSystemCall 
  1441.  
  1442.      DosProtectOpenL 
  1443.  
  1444.      DosProtectQueryFileInfo 
  1445.  
  1446.      DosProtectSetFileInfo 
  1447.  
  1448.      DosProtectSetFileLocksL 
  1449.  
  1450.      DosProtectSetFilePrtL 
  1451.  
  1452.      DosProtectSetFileSizeL 
  1453.  
  1454.      DosQueryABIOSSuport 
  1455.  
  1456.      DosQueryFileInfo 
  1457.  
  1458.      DosQueryMemState 
  1459.  
  1460.      Dos16QueryModFromCS 
  1461.  
  1462.      DosQueryModFromEIP 
  1463.  
  1464.      DosQueryPathInfo 
  1465.  
  1466.      DosQuerySysInfo 
  1467.  
  1468.      DosQuerySysState 
  1469.  
  1470.      DosQueryThreadAffinity 
  1471.  
  1472.      DosRead 
  1473.  
  1474.      DosReplaceModule 
  1475.  
  1476.      DosSetFileInfo 
  1477.  
  1478.      DosSetFileLocksL 
  1479.  
  1480.      DosSetFilePtr 
  1481.  
  1482.      DosSetFilePtrL 
  1483.  
  1484.      DosSetFileSizeL 
  1485.  
  1486.      DosSetPathInfo 
  1487.  
  1488.      DosSetProcessorStatus 
  1489.  
  1490.      DosSetThreadAffinity 
  1491.  
  1492.      Dos16SysTrace 
  1493.  
  1494.      DosTmrQueryFreq 
  1495.  
  1496.      DosTmrQueryTime 
  1497.  
  1498.      DosVerifyPidTid 
  1499.  
  1500.      DosWrite 
  1501.  
  1502.  The following APIs, from the list above, are Raw File System APIs. 
  1503.  
  1504.      DosClose 
  1505.  
  1506.      DosListIO 
  1507.  
  1508.      DosOpen 
  1509.  
  1510.      DosRead 
  1511.  
  1512.      DosSetFilePtr 
  1513.  
  1514.      DosWrite 
  1515.  
  1516.  The OS/2 raw file system provides an interface for applications to manage data 
  1517.  efficiently on the logical partitions or physical hard drives installed in a 
  1518.  system.  Some of the raw file system function is available by using a 
  1519.  combination of the DosPhysicalDisk and DosDevIOCtl application programming 
  1520.  interfaces. 
  1521.  
  1522.  The OS/2 raw file system provides a programming abstraction that treats each 
  1523.  logical partition or physical disk as one large file that can be opened, 
  1524.  locked, seeked, read from, written to, and closed. Logical partitions are 
  1525.  identified using the Universal Naming Convention (UNC) in the form of '\\.\X 
  1526.  ', where 'X' can be substituted with the letter corresponding the logical 
  1527.  partition desired on any hard drive, floppy disk or CD-ROM drive. Physical 
  1528.  disks are identified using UNC naming in the form of '\\.\Physical_Disk#', 
  1529.  where '#' is replaced with the physical disk number corresponding to the 
  1530.  number found in the LVM command. The combination of the naming convention and 
  1531.  use of the common file system application programming interfaces (APIs) 
  1532.  provides a greatly simplified migration path for applications. 
  1533.  
  1534.  Traditionally, raw file systems have been utilized by applications that manage 
  1535.  large amounts of data under heavy workloads. Typically, this has been 
  1536.  commercial database servers performing on-line transaction processing.  Disk 
  1537.  I/O can become a bottleneck under these conditions and the use of an efficient 
  1538.  raw file system can be very useful in improving system performance, through 
  1539.  reduced path length and serialization. 
  1540.  
  1541.  
  1542. ΓòÉΓòÉΓòÉ 5.1. DosAliasMem ΓòÉΓòÉΓòÉ
  1543.  
  1544. Purpose 
  1545.  
  1546. DosAliasMem creates a private Read/Write alias or an LDT code segment alias to 
  1547. part of an existing memory object. The alias object is accessible only to the 
  1548. process that created it. The original object must be accessible to the caller 
  1549. of DosAliasMem. 
  1550.  
  1551. Syntax 
  1552.  
  1553. #define INCL_DOSMEMMGR
  1554. #include  os2.h>
  1555.  
  1556.  APIRET APIENTRY DosAliasMem (PVOID pMem, ULONG cbSize, PPVOID ppAlias, ULONG 
  1557.            flags) 
  1558.  
  1559.  Parameters 
  1560.  
  1561.  pMem (PMEM)  input 
  1562.            Contains the address of the memory to be aliased. It must be on a 
  1563.            page boundary (that is, 4K aligned), but may specify an address 
  1564.            within a memory object. 
  1565.  
  1566.  cbSize (CBSIZE)  input 
  1567.            Specifies the size in bytes for the memory to alias. The entire 
  1568.            range must lie within a single memory object and must be committed 
  1569.            if OBJ_SELMAPALL is specified. 
  1570.  
  1571.  ppAlias (PPALIAS)  output 
  1572.            Address of a location in which the address of the aliased memory is 
  1573.            returned. The corresponding LDT selector is not explicitly returned 
  1574.            but may be calculated by using the Compatibility Mapping Algorithm 
  1575.  
  1576.                       sel = (SEL) ((ULONG) (*ppAlias) >> 13 | 7)
  1577.  
  1578.   flags (FLAGS)  input 
  1579.            Flags are defined as follows 
  1580.  
  1581.            OBJ_SELMAPALL (0x00000800) OBJ_SELMAPALL creates a Read/Write 32 bit 
  1582.                           alias to the address specified. The entire range must 
  1583.                           be committed, start on page boundary and be within 
  1584.                           the extent of a single memory object. An LDT selector 
  1585.                           is created to map the entire range specified. 
  1586.  
  1587.                           If OBJ_SELMAPALL is not specified, then size is 
  1588.                           rounded up to a 4K multiple and the alias created 
  1589.                           inherits the permissions from the pages of the 
  1590.                           original object. 
  1591.  
  1592.                           OBJ_TILE may be specified, but currently this is 
  1593.                           enforced whether or not specified. This forces LDT 
  1594.                           selectors to be based on 64K boundaries. 
  1595.  
  1596.            SEL_CODE (0x00000001) Marks the LDT alias selector(s) 
  1597.                           Read-Executable code selectors. 
  1598.  
  1599.            SEL_USE32 (0x00000002) Used with OBJ_SELMAPALL, otherwise ignored. 
  1600.                           Marks the first alias LDT selector as a 32 bit 
  1601.                           selector by setting the BIG/C32 bit. 
  1602.  
  1603.  Returns 
  1604.  
  1605.  ulrc (APIRET)  returns 
  1606.            Return Code. 
  1607.  
  1608.            DosAliasMem returns one of the following values 
  1609.  
  1610.            0              NO_ERROR 
  1611.  
  1612.            8              ERROR_NOT_ENOUGH_MEMORY 
  1613.  
  1614.            87             ERROR_INVALID_PARAMETER 
  1615.  
  1616.            95             ERROR_INTERRUPT 
  1617.  
  1618.            32798          ERROR_CROSSES_OBJECT_BOUNDARY 
  1619.  
  1620.  Remarks 
  1621.  
  1622.  An export for DosAliasMem does not appear in versions of OS2386.LIB 
  1623.  distributed prior to Warp Server for e-business. When using older versions, 
  1624.  the following statements should be added to the link edit .DEF file 
  1625.  
  1626.   imports
  1627.   DosAliasMem = DOSCALLS.298
  1628.  
  1629.  An alias is removed by calling DosFreeMem with the alias address. 
  1630.  
  1631.  Though it is possible to create a Read/Write alias to a code segment to allow 
  1632.  code modification this is not recommended. On Pentium(R) processors, and 
  1633.  later, pipe-lining techniques used by the  processor might allow the processor 
  1634.  not to be aware of the modified code, if appropriate pipe-line serialization 
  1635.  is not performed by the programmer. For further information see the processor 
  1636.  documentation. 
  1637.  
  1638.  Related Functions 
  1639.  
  1640.      DosAllocMem 
  1641.  
  1642.      DosAllocSharedMem 
  1643.  
  1644.      DosFreeMem 
  1645.  
  1646.  Example Code 
  1647.  
  1648.   #define INCL_DOSMEMMGR
  1649.   #include int main(int argc, char *argv[], char *envp[])
  1650.   {
  1651.      PVOID pAlias;
  1652.      PVOID pMem;
  1653.      APIRET rc;
  1654.  
  1655.      /* alias a read-only shared memory object as a private read/write */
  1656.      /* object. This will allow clients of this object to read only    */
  1657.      /* while allowing the owner to update it.                         */
  1658.  
  1659.      rc=DosAllocSharedMem( pMem,NULL,128*1024,
  1660.         PAG_READ+PAG_COMMIT+OBJ_GIVEABLE);
  1661.  
  1662.      rc = DosAliasMem(pMem, 128*1024,  pAlias, OBJ_TILE);
  1663.  
  1664.      .
  1665.      .
  1666.      .
  1667.      .
  1668.  
  1669.      return 0;
  1670.   }
  1671.  
  1672.  
  1673. ΓòÉΓòÉΓòÉ 5.2. DosCancelLockRequestL ΓòÉΓòÉΓòÉ
  1674.  
  1675. Purpose 
  1676.  
  1677. DosCancelLockRequestL cancels an outstanding DosSetFileLocksL request. 
  1678.  
  1679. Syntax 
  1680.  
  1681. #define INCL DOSFILEMGR
  1682. #include  os2.h
  1683.  
  1684.  APIRET DosCancelLockRequestL (HFILE hFile, PFILELOCKL pflLock) 
  1685.  
  1686.  Parameters 
  1687.  
  1688.  hFile  HFILE)  input 
  1689.            File handle used in the DosSetFileLocksL function that is to be 
  1690.            cancelled. 
  1691.  
  1692.  pflLockL  PFILELOCKL)  input 
  1693.            Address of the structure describing the lock request to cancel. 
  1694.  
  1695.  Returns 
  1696.  
  1697.  ulrc  APIRET)  returns 
  1698.            Return Code. 
  1699.  
  1700.            DosCancelLockRequestL returns one of the following values 
  1701.  
  1702.            0              NO_ERROR 
  1703.  
  1704.            6              ERROR_INVALID_HANDLE 
  1705.  
  1706.            87             ERROR_INVALID_PARAMETER 
  1707.  
  1708.            173            ERROR_CANCEL_VIOLATION 
  1709.  
  1710.  Remarks 
  1711.  
  1712.  DosCancelLockRequestL allows a process to cancel the lock range request of an 
  1713.  outstanding DosSetFileLocksL function. 
  1714.  
  1715.  If two threads in a process are waiting on a lock file range, and another 
  1716.  thread issues DosCancelLockRequestL for that lock file range, then both 
  1717.  waiting threads are released. 
  1718.  
  1719.  Not all file-system drivers (FSDs) can cancel an outstanding lock request. 
  1720.  
  1721.  Local Area Network (LAN) servers cannot cancel an outstanding lock request if 
  1722.  they use a version of the operating system prior to OS/2 Version 2.00. 
  1723.  
  1724.  Related Functions 
  1725.  
  1726.      DosSetFileLocksL 
  1727.  
  1728.  Example Code 
  1729.  
  1730.  This example opens a file named  CANLOCK.DAT , locks a block of the data, 
  1731.  writes some data to it, and then cancels the lock request. 
  1732.  
  1733.   #define INCL_DOSFILEMGR       /* File Manager values */
  1734.   #define INCL_DOSERRORS        /* DOS Error values    */
  1735.   #include  os2.h
  1736.   #include  stdio.h
  1737.   #include  string.h
  1738.  
  1739.   int main(VOID)
  1740.  
  1741.   HFILE     FileHandle   = NULLHANDLE;  /* File handle */
  1742.   ULONG     Action       = 0,           /* Action taken by DosOpenL */
  1743.   Wrote        = 0;           /* Number of bytes written by DosWrite */
  1744.   CHAR      FileData 40  = "Forty bytes of demonstration text data\r\n";
  1745.   APIRET    rc           = NO_ERROR;    /* Return code */
  1746.  
  1747.   FILELOCKL  LockArea     =  0 ,         /* Area of file to lock */
  1748.   UnlockArea   =  0 ;         /* Area of file to unlock */
  1749.  
  1750.   rc = DosOpenL("canlock.dat",                 /* File to open */
  1751.    FileHandle,                   /* File handle */
  1752.    Action,                       /* Action taken */
  1753.   256,                           /* File primary allocation */
  1754.   FILE_ARCHIVED,                 /* File attributes */
  1755.   FILE_OPEN | FILE_CREATE,       /* Open function type */
  1756.   OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE,
  1757.   0L);                           /* No extended attributes */
  1758.   if (rc != NO_ERROR)                         /* If open failed */
  1759.   printf("DosOpenL error  return code = %u\n", rc);
  1760.   return 1;
  1761.  
  1762.   LockArea.lOffset = 0;               /* Start locking at beginning of file */
  1763.   LockArea.lRange =  40;              /* Use a lock range of 40 bytes       */
  1764.   UnLockArea.lOffset = 0;             /* Start unlocking at beginning of file */
  1765.   UnLockArea.lRange =  0;             /* Use a unlock range of 0 bytes       */
  1766.  
  1767.   rc = DosSetFileLocksL(FileHandle,        /* File handle   */
  1768.    UnlockArea,       /* No unlock area */
  1769.    LockArea,         /* Lock current record */
  1770.   2000L,             /* Lock time-out value of 2 seconds */
  1771.   0L);               /* Exclusive lock, not atomic */
  1772.   if (rc != NO_ERROR)
  1773.   printf("DosSetFileLocks error  return code = %u\n", rc);
  1774.   return 1;
  1775.  
  1776.  
  1777.   rc = DosWrite(FileHandle, FileData, sizeof(FileData),  Wrote);
  1778.   if (rc != NO_ERROR)
  1779.   printf("DosWrite error  return code = %u\n", rc);
  1780.   return 1;
  1781.  
  1782.   /* Should check if (rc != NO_ERROR) here... */
  1783.  
  1784.   LockArea.lOffset = 0;               /* Start locking at beginning of file */
  1785.   LockArea.lRange =  0;               /* Use a lock range of 40 bytes       */
  1786.   UnLockArea.lOffset = 0;             /* Start locking at beginning of file */
  1787.   UnLockArea.lRange = 40;             /* Use a lock range of 40 bytes       */
  1788.  
  1789.   rc = DosSetFileLocksL(FileHandle,        /* File handle   */
  1790.    UnlockArea,       /* Unlock area */
  1791.    LockArea,         /* No Lock */
  1792.   2000L,             /* Lock time-out value of 2 seconds */
  1793.   0L);               /* Exclusive lock, not atomic */
  1794.   if (rc != NO_ERROR)
  1795.   printf("DosSetFileLocksL error  return code = %u\n", rc);
  1796.   return 1;
  1797.    rc = DosClose(FileHandle);
  1798.   /* Should check if (rc != NO_ERROR) here... */
  1799.  
  1800.   return NO_ERROR;
  1801.    rc = DosClose(FileHandle);
  1802.   /* Should check if (rc != NO_ERROR) here... */
  1803.  
  1804.   return NO_ERROR;
  1805.  
  1806.  
  1807. ΓòÉΓòÉΓòÉ 5.3. DosClose ΓòÉΓòÉΓòÉ
  1808.  
  1809. Purpose 
  1810.  
  1811. DosClose closes a handle to a disk. 
  1812.  
  1813. Syntax 
  1814.  
  1815. #define INCL_DOSFILEMGR
  1816. #include  os2.h>
  1817.  
  1818.  APIRET DosClose (HFILE hFile) 
  1819.  
  1820.  Parameters 
  1821.  
  1822.  hFile (HFILE)  input 
  1823.            The handle returned by DosOpen. 
  1824.  
  1825.  Returns 
  1826.  
  1827.  ulrc (APIRET)  returns 
  1828.            Return Code. 
  1829.  
  1830.            DosClose returns one of the following values 
  1831.  
  1832.            0              NO_ERROR 
  1833.  
  1834.            2               ERROR_FILE_NOT_FOUND 
  1835.  
  1836.            5              ERROR_ACCESS_DENIED 
  1837.  
  1838.            6              ERROR_INVALID_HANDLE 
  1839.  
  1840.  Remarks 
  1841.  
  1842.  The disk can no longer be accessed using this handle. If opened with the 
  1843.  OPEN_SHARE_DENYREADWRITE flag, the disk is unlocked. 
  1844.  
  1845.  Related Functions 
  1846.  
  1847.      DosOpen 
  1848.  
  1849.  Example Code 
  1850.  
  1851.  The following is NOT a complete usable program.  It is simply intended  to 
  1852.  provide an idea of how to use Raw I/O File System APIs (e.g. DosOpen, DosRead, 
  1853.  DosWrite, DosSetFilePtr, and DosClose). 
  1854.  
  1855.  This example opens physical disk #1 for reading and physical disk #2 for 
  1856.  writing.  DosSetFilePtr is used to set the pointer to the beginning of the 
  1857.  disks. Using DosRead and DosWrite, 10 megabytes of data is transferred from 
  1858.  disk #1 to disk #2. Finally, DosClosed is issued to close the disk handles. 
  1859.  
  1860.  It is assumed that the size of each of the two disks is at least 10 megabytes. 
  1861.  
  1862.   #define INCL_DOSFILEMGR          /* Include File Manager APIs */
  1863.   #define INCL_DOSMEMMGR           /* Includes Memory Management APIs */
  1864.   #define INCL_DOSERRORS           /* DOS Error values */
  1865.   #include  os2.h>
  1866.   #include  stdio.h>
  1867.   #include  string.h>
  1868.  
  1869.   #define SIXTY_FOUR_K 0x10000
  1870.   #define ONE_MEG     0x100000
  1871.   #define TEN_MEG     10*ONE_MEG
  1872.  
  1873.   #define UNC_DISK1  "\\\\.\\Physical_Disk1"
  1874.   #define UNC_DISK2  "\\\\.\\Physical_Disk2"
  1875.  
  1876.   int main(void) {
  1877.      HFILE  hfDisk1        = 0;      /* Handle for disk #1 */
  1878.      HFILE  hfDisk2        = 0;      /* Handle for disk #2 */
  1879.      ULONG  ulAction       = 0;      /* Action taken by DosOpen */
  1880.      ULONG  cbRead         = 0;      /* Bytes to read */
  1881.      ULONG  cbActualRead   = 0;      /* Bytes read by DosRead */
  1882.      ULONG  cbWrite        = 0;      /* Bytes to write */
  1883.      ULONG  ulLocation     = 0;
  1884.      ULONG  cbActualWrote  = 0;      /* Bytes written by DosWrite */
  1885.      UCHAR  uchFileName1[20]  = UNC_DISK1, /* UNC Name of disk 1 */
  1886.             uchFileName2[20]  = UNC_DISK2; /* UNC Name of disk 2 */
  1887.      PBYTE  pBuffer        = 0;
  1888.      ULONG  cbTotal        = 0;
  1889.  
  1890.      APIRET rc             = NO_ERROR;            /* Return code */
  1891.  
  1892.      /* Open a raw file system disk #1 for reading */
  1893.      rc = DosOpen(uchFileName1,               /* File name */
  1894.                    hfDisk1,                   /* File handle */
  1895.                    ulAction,                  /* Action taken by DosOpen */
  1896.                   0L,                         /* no file size */
  1897.                   FILE_NORMAL,                /* File attribute */
  1898.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  1899.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  1900.                   OPEN_ACCESS_READONLY,
  1901.                   0L);                        /* No extented attributes */
  1902.      if (rc != NO_ERROR) {
  1903.         printf("DosOpen error rc = %u\n", rc);
  1904.         return(1);
  1905.      } /* endif */
  1906.  
  1907.      /* Set the pointer to the begining of the disk */
  1908.      rc = DosSetFilePtr(hfDisk1,      /* Handle for disk 1 */
  1909.                         0L,           /* Offset must be multiple of 512 */
  1910.                         FILE_BEGIN,   /* Begin of the disk */
  1911.                          ulLocation); /* New pointer location */
  1912.      if (rc != NO_ERROR) {
  1913.         printf("DosSetFilePtr error rc = %u\n", rc);
  1914.         return(1);
  1915.      } /* endif */
  1916.  
  1917.      /* Open a raw file system disk #2 for writing */
  1918.      rc = DosOpen(uchFileName2,               /* File name */
  1919.                    hfDisk2,                   /* File handle */
  1920.                    ulAction,                  /* Action taken by DosOpen */
  1921.                   0L,                         /* no file size */
  1922.                   FILE_NORMAL,                /* File attribute */
  1923.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  1924.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  1925.                   OPEN_ACCESS_READWRITE,
  1926.                   0L);                        /* No extented attributes */
  1927.      if (rc != NO_ERROR) {
  1928.         printf("DosOpen error rc = %u\n", rc);
  1929.         return(1);
  1930.      } /* endif */
  1931.  
  1932.      /* Set the pointer to the begining of the disk */
  1933.      rc = DosSetFilePtr(hfDisk2,      /* Handle for disk 1 */
  1934.                         0L,           /* Offset must be multiple of 512 */
  1935.                         FILE_BEGIN,   /* Begin of the disk */
  1936.                          ulLocation); /* New pointer location */
  1937.      if (rc != NO_ERROR) {
  1938.         printf("DosSetFilePtr error rc = %u\n", rc);
  1939.         return(1);
  1940.      } /* endif */
  1941.  
  1942.  
  1943.      /* Allocate 64K of memory for transfer operations */
  1944.      rc = DosAllocMem((PPVOID) pBuffer, /* Pointer to buffer */
  1945.                        SIXTY_FOUR_K,      /* Buffer size */
  1946.                        PAG_COMMIT |     /* Allocation flags */
  1947.                        PAG_READ |
  1948.                        PAG_WRITE);
  1949.      if (rc != NO_ERROR) {
  1950.         printf("DosAllocMem error rc = %u\n", rc);
  1951.         return(1);
  1952.      } /* endif */
  1953.  
  1954.      cbRead = SIXTY_FOUR_K;
  1955.      while (rc == NO_ERROR    cbTotal   TEN_MEG) {
  1956.  
  1957.         /* Read from #1 */
  1958.         rc = DosRead(hfDisk1,         /* Handle for disk 1 */
  1959.                      pBuffer,         /* Pointer to buffer */
  1960.                      cbRead,          /* Size must be multiple of 512 */
  1961.                       cbActualRead);  /* Actual read by DosOpen */
  1962.         if (rc) {
  1963.            printf("DosRead error  return code = %u\n", rc);
  1964.            return 1;
  1965.         }
  1966.  
  1967.         /* Write to disk #2 */
  1968.         cbWrite = cbActualRead;
  1969.         rc = DosWrite(hfDisk2,         /* Handle for disk 2 */
  1970.                       pBuffer,         /* Pointer to buffer */
  1971.                       cbWrite,         /* Size must be multiple of 512 */
  1972.                        cbActualWrote); /* Actual written by DosOpen */
  1973.         if (rc) {
  1974.            printf("DosWrite error  return code = %u\n", rc);
  1975.            return 1;
  1976.         }
  1977.         if (cbActualRead != cbActualWrote) {
  1978.            printf("Bytes read (%u) does not equal bytes written (%u)\n",
  1979.                   cbActualRead, cbActualWrote);
  1980.            return 1;
  1981.         }
  1982.         cbTotal += cbActualRead; /* Update total transferred */
  1983.      }
  1984.  
  1985.      printf("Transfer successfully %d bytes from disk #1 to disk #2.\n",
  1986.             cbTotal);
  1987.  
  1988.      /* Free allocated memmory */
  1989.      rc = DosFreeMem(pBuffer);
  1990.      if (rc != NO_ERROR) {
  1991.         printf("DosFreeMem error  return code = %u\n", rc);
  1992.         return 1;
  1993.      }
  1994.  
  1995.      rc = DosClose(hfDisk1);
  1996.      if (rc != NO_ERROR) {
  1997.         printf("DosClose error  return code = %u\n", rc);
  1998.         return 1;
  1999.      }
  2000.  
  2001.      rc = DosClose(hfDisk2);
  2002.      if (rc != NO_ERROR) {
  2003.         printf("DosClose error  return code = %u\n", rc);
  2004.         return 1;
  2005.      }
  2006.   return NO_ERROR;
  2007.   }
  2008.  
  2009.  
  2010. ΓòÉΓòÉΓòÉ 5.4. DosCreateEventSem ΓòÉΓòÉΓòÉ
  2011.  
  2012. Purpose 
  2013.  
  2014. DosCreateEventSem creates an event semaphore. 
  2015.  
  2016. Syntax 
  2017.  
  2018. #define INCL DOSSEMAPHORES
  2019. #include  os2.h
  2020.  
  2021.  APIRET DosCreateEventSem (PSZ pszName, PHEV phev, ULONG flAttr, BOOL32 fState) 
  2022.  
  2023.  Parameters 
  2024.  
  2025.  pszName  PSZ)  input 
  2026.            A pointer to the ASCIIZ name of the semaphore. 
  2027.  
  2028.            Semaphore names are validated by the file system, and must include 
  2029.            the prefix \SEM32\. A maximum of 255 characters is allowed. If these 
  2030.            requirements are not met, ERROR_INVALID_NAME is returned. If the 
  2031.            semaphore already exists, ERROR_DUPLICATE_NAME is returned. 
  2032.  
  2033.            If this field is null, the semaphore is unnamed. Unnamed event 
  2034.            semaphores can be either private or shared, depending on flAttr. 
  2035.            They are identified by the semaphore handle that phev points to. 
  2036.  
  2037.            By default, all named semaphores are shared. 
  2038.  
  2039.  phev  PHEV)  output 
  2040.            A pointer to the handle of the event semaphore. 
  2041.  
  2042.  flAttr  ULONG)  input 
  2043.            A set of flags that specify the attributes of the event semaphore. 
  2044.  
  2045.            DC_SEM_SHARED  If the DC_SEM_SHARED bit is set, the semaphore is 
  2046.                           shared. Otherwise, this flag should be set to 0L. 
  2047.                           This bit is checked only if the semaphore is unnamed 
  2048.                           (that is, if pszName is null), because all named 
  2049.                           semaphores are shared. 
  2050.  
  2051.            DCE_AUTORESET (0x1000) Causes the semaphore to be reset 
  2052.                           automatically at the time it is posted. 0x1000 
  2053.  
  2054.            DCE_POSTONE (0x0800) Causes one thread only to be posted where 
  2055.                           multiple threads are waiting on an event semaphore 
  2056.                           created with this attribut. DCE_POSTONE also causes 
  2057.                           the semaphore to be reset automatically when it is 
  2058.                           posted. 
  2059.  
  2060.  fState  BOOL32)  input 
  2061.            Initial state of the semaphore. 
  2062.  
  2063.            Possible values are defined in the list below 
  2064.  
  2065.            0        FALSE 
  2066.  
  2067.                     The initial state of the semaphore is  reset. 
  2068.  
  2069.            1        TRUE 
  2070.  
  2071.                     The initial state of the semaphore is  posted. 
  2072.  
  2073.  Returns 
  2074.  
  2075.  ulrc  APIRET)  returns 
  2076.            Return Code. 
  2077.  
  2078.            DosCreateEventSem returns one of the following values 
  2079.  
  2080.            0              NO_ERROR 
  2081.  
  2082.            8              ERROR_NOT_ENOUGH_MEMORY 
  2083.  
  2084.            87             ERROR_INVALID_PARAMETER 
  2085.  
  2086.            123            ERROR_INVALID_NAME 
  2087.  
  2088.            285            ERROR_DUPLICATE_NAME 
  2089.  
  2090.            290            ERROR_TOO_MANY_HANDLES 
  2091.  
  2092.      DosCloseEventSem 
  2093.  
  2094.      DosOpenEventSem 
  2095.  
  2096.      DosPostEventSem 
  2097.  
  2098.      DosQueryEventSem 
  2099.  
  2100.      DosResetEventSem 
  2101.  
  2102.      DosWaitEventSem 
  2103.  
  2104.  Example Code 
  2105.  
  2106.  This example creates an event semaphore, and the asynchronous timer posts to 
  2107.  it when its time interval expires. Finally, the event semaphore is closed. 
  2108.  
  2109.   #define INCL_DOSSEMAPHORES   /* Semaphore values */
  2110.   #define INCL_DOSDATETIME     /* Timer support    */
  2111.   #define INCL_DOSERRORS       /* DOS error values */
  2112.   #include  os2.h
  2113.   #include  stdio.h
  2114.  
  2115.   int main(VOID)
  2116.  
  2117.   PSZ     szSemName  = "\\SEM32\\TIMER\\THREAD1\\EVENT1"; /* Semaphore name */
  2118.   HEV     hevEvent1     = 0;                   /* Event semaphore handle    */
  2119.   HTIMER  htimerEvent1  = 0;                   /* Timer handle              */
  2120.   APIRET  rc            = NO_ERROR;            /* Return code               */
  2121.  
  2122.   rc = DosCreateEventSem(szSemName,      /* Name of semaphore to create  */
  2123.    hevEvent1,     /* Handle of semaphore returned */
  2124.   DC_SEM_SHARED,  /* Shared semaphore             */
  2125.   FALSE);         /* Semaphore is in RESET state  */
  2126.   if (rc != NO_ERROR)
  2127.   printf("DosCreateEventSem error  return code = %u\n", rc);
  2128.   return 1;
  2129.  
  2130.   rc = DosAsyncTimer(7000L,    /* 7 second interval            */
  2131.   (HSEM) hevEvent1,            /* Semaphore to post            */
  2132.    htimerEvent1);              /* Timer handler (returned)     */
  2133.   if (rc != NO_ERROR)
  2134.   printf("DosAsyncTimer error  return code = %u\n", rc);
  2135.   return 1;
  2136.     else
  2137.   printf("Timer will expire in about 7 seconds...\n");
  2138.  
  2139.  
  2140.   /* ... add your other processing here... */
  2141.  
  2142.   rc = DosWaitEventSem(hevEvent1,            /* Wait for AsyncTimer event */
  2143.   (ULONG) SEM_INDEFINITE_WAIT);              /* As long as it takes       */
  2144.   if (rc != NO_ERROR)
  2145.   printf("DosWaitEventSem error  return code = %u\n", rc);
  2146.   return 1;
  2147.  
  2148.  
  2149.   rc = DosCloseEventSem(hevEvent1);      /* Get rid of semaphore       */
  2150.   if (rc != NO_ERROR)
  2151.   printf("DosCloseEventSem error  return code = %u", rc);
  2152.   return 1;
  2153.  
  2154.  
  2155.   return NO_ERROR;
  2156.  
  2157.  
  2158. ΓòÉΓòÉΓòÉ 5.5. DosCreateThread2 ΓòÉΓòÉΓòÉ
  2159.  
  2160. Purpose 
  2161.  
  2162. DosCreateThread2 creates an asynchronous thread of execution under the current 
  2163. process using a pre-allocated stack. 
  2164.  
  2165. Syntax 
  2166.  
  2167. #define INCL_DOSPROCESS
  2168. #include  os2.h>
  2169.  
  2170.  APIRET DosCreateThread2 (PTHREADCREATE ptc, ULONG cbSize, PTID pTid, PFNTHREAD 
  2171.            pfnStart, ULONG lParam, ULONG lFlag, PBYTE pStack, ULONG cbStack) 
  2172.  
  2173.  Parameters 
  2174.  
  2175.  ptc(PTHREADCREATE)  input/output 
  2176.            Address of the thread create data structure 
  2177.  
  2178.                       typedef struct_THREADCREATE{
  2179.                          ULONG       cbSize;
  2180.                          PTID        pTid;
  2181.                          PFNTHREAD   pfnStart;
  2182.                          ULONG       lParam;
  2183.                          ULONG       lFlag;
  2184.                          PBYTE       pStack;
  2185.                          ULONG       cbStack;
  2186.                       }  THREADCREATE;
  2187.                       typedef THREADCREATE *PTHREADCREATE;
  2188.  
  2189.  cbSize (ULONG)  input 
  2190.            The size, in bytes, of the thread create structure. 
  2191.  
  2192.  pTid (PTID)  output 
  2193.            The thread identifier of the created thread is returned. 
  2194.  
  2195.  pfnStart (PFNTHREAD)  input 
  2196.            Address of the code to be executed when the thread begins execution. 
  2197.  
  2198.            This function is called using a 32 bit near-call, accepts a single 
  2199.            parameter, lParam, and returns a doubleword exit status (see 
  2200.            DosExit). Returning from the function without executing DosExit 
  2201.            causes the thread to end. In this case, the exit status is the value 
  2202.            in the EAX register when the thread ends. 
  2203.  
  2204.  lParam (ULONG)  input 
  2205.            An argument that is passed to the target thread routine as a 
  2206.            parameter. It is usually a pointer to a parameter block. 
  2207.  
  2208.  lFlag (ULONG)  input 
  2209.            Thread flags. 
  2210.  
  2211.            Possible values are a combination of the following 
  2212.  
  2213.            CREATE_READY (0x00000000) The new thread starts immediately. 
  2214.  
  2215.            CREATE_SUSPEND (0x00000001) The thread is created in the suspended 
  2216.                           state, and the creator of the thread must issue 
  2217.                           DosResumeThread to start the new thread's execution. 
  2218.  
  2219.            STACK_SPARSE (0x00000000) The system uses the default method for 
  2220.                           initializing the thread's stack. 
  2221.  
  2222.            STACK_COMMITTED (0x00000002) The system precommits all the pages in 
  2223.                           the stack. One page is 4KB 
  2224.  
  2225.  pStack (PBYTE)  input 
  2226.            Address of the top of the stack (not the bottom of the stack). 
  2227.  
  2228.  cbStack (ULONG)  input 
  2229.            The size, in bytes, of the new thread's stack. 
  2230.  
  2231.  Returns 
  2232.  
  2233.  ulrc (APIRET)  returns 
  2234.            Return Code. 
  2235.  
  2236.            DosCreateThread2 returns one of the following values 
  2237.  
  2238.            0              NO_ERROR 
  2239.  
  2240.            8              ERROR_NOT_ENOUGH_MEMORY 
  2241.  
  2242.            87             ERROR_INVALID_PARAMETER 
  2243.  
  2244.            95             ERROR_INTERRUPT 
  2245.  
  2246.            115            ERROR_PROTECTION_VIOLATION 
  2247.  
  2248.            164            ERROR_MAX_THRDS_REACHED 
  2249.  
  2250.  Remarks 
  2251.  
  2252.  The difference between DosCreateThread and DosCreateThread2 is the use and 
  2253.  management  of the thread's stack. 
  2254.  
  2255.  Using DosCreateThread, the application is not responsible for allocating the 
  2256.  stack.  The application simply supplies the size of the stack, and the 
  2257.  operating system will  manage the allocation and location of that storage on 
  2258.  behalf of the application.  DosCreateThread also employs guard pages and 
  2259.  exception handling for stack related situations, such as stack growth.  One of 
  2260.  the problems with DosCreateThread is that for each thread, a minimum 64K of 
  2261.  virtual address space is reserved, but only 8K of  physical storage is 
  2262.  actually committed.  Therefore, 56K of virtual address space is wasted 
  2263.  initially. 
  2264.  
  2265.  Using DosCreateThread2, the application is responsible for allocating the 
  2266.  stack before calling the API.  With DosCreateThread2, the operating system 
  2267.  gives the application total control over stack size and location.  Therefore, 
  2268.  more efficient use of virtual address space within the system can be achieved. 
  2269.  
  2270.  The address of the stack, pStack, must be in the compatibility region, that 
  2271.  is, the first 512MB (0x20000000). If DosCreateThread2 is called with a stack 
  2272.  address higher than 512MB, ERROR_INVALID_PARAMETER will be returned. 
  2273.  
  2274.  Related Functions 
  2275.  
  2276.      DosCreateThread 
  2277.  
  2278.  Example Code 
  2279.  
  2280.  In this example, the main thread first allocates 64K worth of memory.  It then 
  2281.  calls  DosCreateThread2 four times to create 4 child threads.  Each child 
  2282.  thread has 16K of stack space.  Finally, the main thread sets the termination 
  2283.  flag to allow all child threads to terminate. 
  2284.  
  2285.  Compile this example with MULTITHREAD LIBRARIES. If you are using CSet/2 or 
  2286.  VisualAge(R)  C/C++, use the /Gm+ switch. 
  2287.  
  2288.   #define INCL_DOSMEMMGR
  2289.   #define INCL_DOSPROCESS
  2290.   #define INCL_DOSERRORS
  2291.  
  2292.   #include  os2.h>
  2293.   #include  stdio.h>
  2294.   #include  stdlib.h>
  2295.  
  2296.   #define _64K 64*1024
  2297.   #define _48K 48*1024
  2298.   #define _32K 32*1024
  2299.   #define _16K 16*1024
  2300.  
  2301.   void _System TestThread1(void);
  2302.   void _System TestThread2(void);
  2303.   void _System TestThread3(void);
  2304.   void _System TestThread4(void);
  2305.  
  2306.   BOOL flTerminate = FALSE;
  2307.  
  2308.   int main (VOID) {
  2309.  
  2310.      APIRET rc;               /* Return code */
  2311.      void *pStackBase;        /* Pointer to stack base */
  2312.      THREADCREATE tc[4]={0};  /* Thread create structures */
  2313.      int i;
  2314.  
  2315.      /* Allocate 64K of memory */
  2316.  
  2317.      rc = DosAllocMem( pStackBase, _64K, PAG_COMMIT | PAG_WRITE);
  2318.  
  2319.      if (rc != NO_ERROR) {
  2320.         printf("DosAllocMem failed, rc=%d\n", rc);
  2321.         return(1);
  2322.      }
  2323.  
  2324.      /* Set up thread structures (4 threads). */
  2325.  
  2326.      tc[0].cbSize   = sizeof(THREADCREATE);
  2327.      tc[0].pfnStart = (PFNTHREAD) TestThread1
  2328.      tc[0].pStack   = (PBYTE)pStackBase + _64K;    /* Top of stack (not bottom) */
  2329.      tc[0].lFlag    = CREATE_READY | STACK_SPARSE;
  2330.      tc[0].cbStack  = _16K;                        /* Each thread has 16K stack */
  2331.  
  2332.      tc[1].cbSize   = sizeof(THREADCREATE);
  2333.      tc[1].pfnStart = (PFNTHREAD) TestThread2
  2334.      tc[1].pStack   = (PBYTE)pStackBase + _48K;    /* Top of stack (not bottom) */
  2335.      tc[1].lFlag    = CREATE_READY | STACK_SPARSE;
  2336.      tc[1].cbStack  = _16K;                        /* Each thread has 16K stack */
  2337.  
  2338.      tc[2].cbSize   = sizeof(THREADCREATE);
  2339.      tc[2].pfnStart = (PFNTHREAD) TestThread3
  2340.      tc[2].pStack   = (PBYTE)pStackBase + _32K;    /* Top of stack (not bottom) */
  2341.      tc[2].lFlag    = CREATE_READY | STACK_SPARSE;
  2342.      tc[2].cbStack  = _16K;                        /* Each thread has 16K stack */
  2343.  
  2344.      tc[3].cbSize   = sizeof(THREADCREATE);
  2345.      tc[3].pfnStart = (PFNTHREAD) TestThread4
  2346.      tc[3].pStack   = (PBYTE)pStackBase + _16K;    /* Top of stack (not bottom) */
  2347.      tc[3].lFlag    = CREATE_READY | STACK_SPARSE;
  2348.      tc[3].cbStack  = _16K;                        /* Each thread has 16K stack */
  2349.  
  2350.      /* Create 4 child threads. */
  2351.  
  2352.      for (i=0; i 4; i++) {
  2353.         rc = DosCreateThread2( tc[i]);
  2354.         if (rc != NO_ERROR) {
  2355.           printf( "DosCreateThread2 failed, rc = %d\n", rc);
  2356.           return(1);
  2357.         } else
  2358.              printf("DosCreateThread2 was successful, tid=%d\n", tc[i].pTid);
  2359.      }
  2360.  
  2361.      flTerminate = TRUE;
  2362.  
  2363.      /* Wait for all child threads to terminate. */
  2364.      for (i=0; i 4; i++) {
  2365.         DosWaitThread( (tc[i].pTid), DCWW_WAIT);
  2366.      }
  2367.  
  2368.      DosFreeMem(pStackBase);
  2369.      return(0);
  2370.   }
  2371.  
  2372.   void _System TestThread1(void)
  2373.   {
  2374.      APIRET rc;
  2375.      PTIB   ptib;
  2376.      PPIB   ppib;
  2377.  
  2378.      rc = DosGetInfoBlocks( ptib,  ppib);
  2379.      if (rc != NO_ERROR) {
  2380.         printf("TestThread1  DosGetInfoBlocks failed rc = %d\n", rc);
  2381.         return;
  2382.      }
  2383.  
  2384.      printf("TestThread1  base of stack at 0x%08X, top of stack at 0x%08X\n",
  2385.                ptib->tib_pstack, ptib->tib_pstacklimit);
  2386.  
  2387.      while (flTerminate == FALSE) {
  2388.         DosSleep(1000);
  2389.      }
  2390.   }
  2391.  
  2392.   void _System TestThread2(void)
  2393.   {
  2394.      APIRET rc;
  2395.      PTIB   ptib;
  2396.      PPIB   ppib;
  2397.  
  2398.      rc = DosGetInfoBlocks( ptib,  ppib);
  2399.      if (rc != NO_ERROR) {
  2400.         printf("TestThread2  DosGetInfoBlocks failed rc = %d\n", rc);
  2401.         return;
  2402.      }
  2403.  
  2404.      printf("TestThread2  base of stack at 0x%08X, top of stack at 0x%08X\n",
  2405.                ptib->tib_pstack, ptib->tib_pstacklimit);
  2406.  
  2407.      while (flTerminate == FALSE) {
  2408.         DosSleep(1000);
  2409.      }
  2410.   }
  2411.  
  2412.   void _System TestThread3(void)
  2413.   {
  2414.      APIRET rc;
  2415.      PTIB   ptib;
  2416.      PPIB   ppib;
  2417.  
  2418.      rc = DosGetInfoBlocks( ptib,  ppib);
  2419.      if (rc != NO_ERROR) {
  2420.         printf("TestThread3  DosGetInfoBlocks failed rc = %d\n", rc);
  2421.         return;
  2422.      }
  2423.  
  2424.      printf("TestThread3  base of stack at 0x%08X, top of stack at 0x%08X\n",
  2425.                ptib->tib_pstack, ptib->tib_pstacklimit);
  2426.  
  2427.      while (flTerminate == FALSE) {
  2428.         DosSleep(1000);
  2429.      }
  2430.   }
  2431.  
  2432.   void _System TestThread4(void)
  2433.   {
  2434.      APIRET rc;
  2435.      PTIB   ptib;
  2436.      PPIB   ppib;
  2437.  
  2438.      rc = DosGetInfoBlocks( ptib,  ppib);
  2439.      if (rc != NO_ERROR) {
  2440.         printf("TestThread4  DosGetInfoBlocks failed rc = %d\n", rc);
  2441.         return;
  2442.      }
  2443.  
  2444.      printf("TestThread4  base of stack at 0x%08X, top of stack at 0x%08X\n",
  2445.                ptib->tib_pstack, ptib->tib_pstacklimit);
  2446.  
  2447.      while (flTerminate == FALSE) {
  2448.         DosSleep(1000);
  2449.      }
  2450.   }
  2451.  
  2452.  
  2453. ΓòÉΓòÉΓòÉ 5.6. DosDumpProcess ΓòÉΓòÉΓòÉ
  2454.  
  2455. Purpose 
  2456.  
  2457. DosDumpProcess initiates a process dump from a specified process. This may be 
  2458. used as part of an error handling routine to gather information about an error 
  2459. that may be analyzed later using the OS/2 System Dump Formatter. Configuration 
  2460. of Process Dump may be done using the PDUMPSYS, PDUMPUSR, and PROCDUMP 
  2461. commands. 
  2462.  
  2463. Syntax 
  2464.  
  2465. #define INCL_DOSMISC
  2466. #include  os2.h>
  2467.  
  2468.  APIRET APIENTRY DosDumpProcess (ULONG Flag, ULONG Drive, PID Pid) 
  2469.  
  2470.  Parameters 
  2471.  
  2472.  flag (ULONG)  input 
  2473.            Flags specify the function to be performed 
  2474.  
  2475.            DDP_DISABLEPROCDUMP 0x00000000L Disable process dumps. 
  2476.  
  2477.            DDP_ENABLEPROCDUMP 0x00000001L Enable process dumps. 
  2478.  
  2479.            DDP_PERFORMPROCDUMP 0x00000002L Perform process dump. 
  2480.  
  2481.  drive (ULONG)  input 
  2482.            The ASCII character for the drive on which process dump files are to 
  2483.            be created. This is required only with the DDP_ENABLEPROCDUMP. 
  2484.  
  2485.            Note:  Use the PROCDUMP command to customize fully the drive and 
  2486.                   path. 
  2487.  
  2488.  pid (PID)  input 
  2489.            The process to be dumped. 0L specified the current process; 
  2490.            otherwise a valid process ID must be specified. 
  2491.  
  2492.            Note:  Use the PDUMPUSR command to specify what information will be 
  2493.                   dumped. Use the PROCDUMP command to customize options per 
  2494.                   process and in particular to specify whether child or parent 
  2495.                   process will be dumped. This parameter is actioned only with 
  2496.                   DDP_PERFORMPROCDUMP. 
  2497.  
  2498.  Returns 
  2499.  
  2500.  ulrc (APIRET)  returns 
  2501.            Return Code. 
  2502.  
  2503.            DosDumpProcess returns the following value 
  2504.  
  2505.            87             ERROR_INVLAID PARAMETER 
  2506.  
  2507.  Remarks 
  2508.  
  2509.  For maximum flexibility the use of DosDumpProcess should be limited to the 
  2510.  DDP_PERFORMPROCDUMP function. This allows you to specify whether Process Dump 
  2511.  should be enabled through the use of the PROCDUMP command. You may customize 
  2512.  Process Dump completely through use of the PDUMPUSR, PDUMPSYS, AND PROCDUMP 
  2513.  commands. For further information, see PROCDUMP.DOC in the OS2\SYSTEM\RAS 
  2514.  directory. DDP_ENABLEPROCDUMP and DDP_DISABLEPROCDUMP are provided for 
  2515.  backwards compatibility only. 
  2516.  
  2517.  Related Functions 
  2518.  
  2519.      DosForceSystemDump 
  2520.  
  2521.      DosSysTrace 
  2522.  
  2523.  Example Code 
  2524.  
  2525.   int main (int argc, char *argv[], char *envp[])
  2526.   {
  2527.      APIRET rc;
  2528.  
  2529.      /* Take a process dump;leave drive specification as specified by the user in the   */
  2530.      /* PROCDUMP command. If the user has not enabled process dump using PROCDUMP ON, then  */
  2531.      /* ERROR_INVALID_PARAMETER is returned.   */
  2532.      rc=DosDumpProcess(DDP_PERFORMPROCDUMP,0L,0L);
  2533.      if (rc!=0) {
  2534.         printf("DosDumpProcess returned %u\n",rc);
  2535.         return rc;
  2536.      } /* endif */
  2537.  
  2538.      return 0;
  2539.   }
  2540.  
  2541.  
  2542. ΓòÉΓòÉΓòÉ 5.7. DosFindFirst ΓòÉΓòÉΓòÉ
  2543.  
  2544. Purpose 
  2545.  
  2546. DosFindFirst finds the first file object or group of file objects whose names 
  2547. match the specification. The specification can include extended attributes (EA) 
  2548. associated with a file or directory. 
  2549.  
  2550. Syntax 
  2551.  
  2552. #define INCL DOSFILEMGR
  2553. #include  os2.h
  2554.  
  2555.  APIRET DosFindFirst (PSZ pszFileSpec, PHDIR phdir, ULONG flAttribute, PVOID 
  2556.            pfindbuf, ULONG cbBuf, PULONG pcFileNames, ULONG ulInfoLevel) 
  2557.  
  2558.  Parameters 
  2559.  
  2560.  pszFileSpec  PSZ)  input 
  2561.            Address of the ASCIIZ path name of the file or subdirectory to be 
  2562.            found. 
  2563.  
  2564.            The name component can contain global file name characters. 
  2565.  
  2566.  phdir  PHDIR)  in/out 
  2567.            Address of the handle associated with this DosFindFirst request. 
  2568.  
  2569.            The values that can be specified for the handle are 
  2570.  
  2571.            HDIR_SYSTEM (0x00000001) 
  2572.                     The system assigns the handle for standard output, which is 
  2573.                     always available to a process. 
  2574.  
  2575.            HDIR_CREATE (0xFFFFFFFF) 
  2576.                     The system allocates and returns a handle. Upon return to 
  2577.                     the caller, phdir contains the handle allocated by the 
  2578.                     system. 
  2579.  
  2580.            The DosFindFirst handle is used with subsequent DosFindNext 
  2581.            requests. Reuse of this handle in another DosFindFirst request 
  2582.            closes the association with the previous DosFindFirst request, and 
  2583.            opens a new association with the current DosFindFirst request. 
  2584.  
  2585.  flAttribute  ULONG)  input 
  2586.            Attribute value that determines the file objects to be searched for. 
  2587.  
  2588.            The bit values are shown in the following list 
  2589.  
  2590.            Bits           Description 
  2591.  
  2592.            31 14          Reserved; must be 0. 
  2593.  
  2594.            13             MUST_HAVE_ARCHIVED (0x00002000) 
  2595.  
  2596.                           Must-Have Archive bit; excludes files without the 
  2597.                           archive bit set if bit 13 is set to 1. Files may have 
  2598.                           the Archive bit set if bit 13 is set to 0. 
  2599.  
  2600.            12             MUST_HAVE_DIRECTORY (0x00001000) 
  2601.  
  2602.                           Must-Have Subdirectory bit; excludes files that are 
  2603.                           not subdirectories if bit 12 is set to 1. Files may 
  2604.                           have the Subdirectory bit set if bit 12 is set to 0. 
  2605.  
  2606.            11             Reserved; must be 0. 
  2607.  
  2608.            10             MUST_HAVE_SYSTEM (0x00000400) 
  2609.  
  2610.                           Must-Have System File bit; excludes nonsystem files 
  2611.                           if bit 10 is set to 1. Files may be system files if 
  2612.                           bit 10 is set to 0. 
  2613.  
  2614.            9              MUST_HAVE_HIDDEN (0x00000200) 
  2615.  
  2616.                           Must-Have Hidden File bit; excludes nonhidden files 
  2617.                           if bit 9 is set to 1. Files may be nonhidden if bit 9 
  2618.                           is set to 0. 
  2619.  
  2620.            8              MUST_HAVE_READONLY (0x00000100) 
  2621.  
  2622.                           Must-Have Read-Only File bit; excludes writeable 
  2623.                           files if bit 8 is set to 1. Files may be read-only if 
  2624.                           bit 8 is set to 0. 
  2625.  
  2626.            7 6            Reserved; must be 0. 
  2627.  
  2628.            5              FILE_ARCHIVED (0x00000020) 
  2629.  
  2630.                           May-Have Archive bit; includes files with the Archive 
  2631.                           bit set if bit 5 is set to 1. Excludes files with the 
  2632.                           Archive bit set if bit 5 is set to 0. 
  2633.  
  2634.            4              FILE_DIRECTORY (0x00000010) 
  2635.  
  2636.                           May-Have Subdirectory bit; includes files that are 
  2637.                           subdirectories if bit 4 is set to 1. Excludes files 
  2638.                           that are subdirectories if bit 4 is set to 0. 
  2639.  
  2640.            3              Reserved; must be 0. 
  2641.  
  2642.            2              FILE_SYSTEM (0x00000004) 
  2643.  
  2644.                           May-Have System File bit; includes system files if 
  2645.                           bit 2 is set to 1. Excludes system files if bit 2 is 
  2646.                           set to 0. 
  2647.  
  2648.            1              FILE_HIDDEN (0x00000002) 
  2649.  
  2650.                           May-Have Hidden File bit; includes hidden files if 
  2651.                           bit 1 is set to 1. Excludes hidden files if bit 1 is 
  2652.                           set to 0. 
  2653.  
  2654.            0              FILE_READONLY (0x00000001) 
  2655.  
  2656.                           May-Have Read-Only File bit; includes read only files 
  2657.                           if bit 0 is set to 1. Excludes read only files if bit 
  2658.                           0 is set to 0. 
  2659.  
  2660.            These bits may be set individually or in combination. For example, 
  2661.            an attribute value of 0x00000021 (bits 5 and 0 set to 1) indicates 
  2662.            searching for read-only files that have been archived. 
  2663.  
  2664.            Bits 8 through 13 are  Must-Have  flags. These allow you to obtain 
  2665.            files that definitely have the given attributes. For example, if the 
  2666.            Must-Have Subdirectory bit is set to 1, then all returned items are 
  2667.            subdirectories. 
  2668.  
  2669.            If a Must-Have bit is set to 1, and the corresponding May-Have bit 
  2670.            is set to 0, no items are returned for that attribute. 
  2671.  
  2672.            The attribute FILE_NORMAL (0x00000000) can be used to include files 
  2673.            with any of the above bits set. 
  2674.  
  2675.            flAttribute cannot specify the volume label. Volume labels are 
  2676.            queried using DosQueryFSInfo. 
  2677.  
  2678.  pfindbuf  PVOID)  in/out 
  2679.            Result buffer. 
  2680.  
  2681.            The result buffer from DosFindFirst should be less than 64 KB. 
  2682.  
  2683.            Address of the directory search structures for file object 
  2684.            information Levels 1 through 3 and 13. The structure required for 
  2685.            pfindbuf is dependent on the value specified for ulInfoLevel. The 
  2686.            information returned reflects the most recent call to DosClose or 
  2687.            DosResetBuffer. 
  2688.  
  2689.            Level 1 File Information (ulInfoLevel == FIL_STANDARD) 
  2690.                    On output, pfindbuf contains the FILEFINDBUF3 data structure 
  2691.                    without the last two fields  cchName and achName. This is 
  2692.                    used without EAs. 
  2693.  
  2694.                    The oNextEntryOffset field indicates the number of bytes 
  2695.                    from the beginning of the current structure to the beginning 
  2696.                    of the next structure. When this field is 0, the last 
  2697.                    structure has been reached. 
  2698.  
  2699.            Level 11 File Information (ulInfoLevel == FIL_STANDARDL) 
  2700.                    pInfo contains the FILESTATUS3L data structure, to which 
  2701.                    file information is returned. 
  2702.  
  2703.            Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) 
  2704.                    On output, pfindbuf contains the FILEFINDBUF4 data structure 
  2705.                    without the last two fields  cchName and achName. This is 
  2706.                    used with EAs. 
  2707.  
  2708.                    The cbList field contains the size, in bytes, of the file s 
  2709.                    entire EA set on disk. You can use this field to calculate 
  2710.                    the maximum size of the buffer needed for Level 3 file 
  2711.                    information. The size of the buffer required to hold the 
  2712.                    entire EA set is less than or equal to twice the size of the 
  2713.                    EA set on disk. 
  2714.  
  2715.            Level 12 File Information (ulInfoLevel == FIL_QUERYEASIZEL) 
  2716.                    pInfo contains the FILESTATUS4L data structure. This is 
  2717.                    similar to the Level 11 structure, with the addition of the 
  2718.                    cbList field after the attrFile field. 
  2719.  
  2720.                    The cbList field is a ULONG. On output, this field contains 
  2721.                    the size, in bytes, of the file s entire extended attribute 
  2722.                    (EA) set on disk. You can use this value to calculate the 
  2723.                    size of the buffer required to hold the EA information 
  2724.                    returned when a value of 3 is specified for ulInfoLevel. The 
  2725.                    buffer size is less than or equal to twice the size of the 
  2726.                    file s entire EA set on disk. 
  2727.  
  2728.            Level 3 File Information (ulInfoLevel == FIL_QUERYEASFROMLIST) 
  2729.                    On input, pfindbuf contains an EAOP2 data structure. 
  2730.                    fpGEA2List contains a pointer to a GEA2 list, which defines 
  2731.                    the attribute names whose values are to be returned. Entries 
  2732.                    in the GEA2 list must be aligned on a doubleword boundary. 
  2733.                    Each oNextEntryOffset field must contain the number of bytes 
  2734.                    from the beginning of the current entry to the beginning of 
  2735.                    the next entry. 
  2736.  
  2737.                    On output, pfindbuf contains a structure with a set of 
  2738.                    records, each aligned on a doubleword boundary. These 
  2739.                    records represent the directory entry and associated EAs for 
  2740.                    the matched file object. pfindbuf has the following format 
  2741.  
  2742.                        The EAOP2 data structure, with the fpFEA2List pointer 
  2743.                         incorrect. 
  2744.  
  2745.                         The EAOP2 data structure occurs only once in the 
  2746.                         pfindbuf buffer. The rest of these records are repeated 
  2747.                         for the remainder of the file objects found. 
  2748.  
  2749.                        A FILEFINDBUF3 data structure without the last two 
  2750.                         fields  cchName and achName. 
  2751.  
  2752.                        A FEA2LIST data structure contained in and related to 
  2753.                         the FILEFINDBUF3 returned. 
  2754.  
  2755.                        Length of the name string of the file object (cbName) 
  2756.  
  2757.                        Name of the file object matched by the input pattern 
  2758.                         (achName) 
  2759.  
  2760.                    Even if there is not enough room to hold all of the 
  2761.                    requested information, as for return code 
  2762.                    ERROR_BUFFER_OVERFLOW, the cbList field of the FEA2LIST data 
  2763.                    structure is valid if there is at least enough space to hold 
  2764.                    it. 
  2765.  
  2766.                    When buffer overflow occurs, cbList contains the size on 
  2767.                    disk of the entire EA set for the file, even if only a 
  2768.                    subset of its attributes was requested. The size of the 
  2769.                    buffer required to hold the EA set is less than or equal to 
  2770.                    twice the size of the EA set on disk. If no error occurs, 
  2771.                    cbList includes the pad bytes (for doubleword alignment) 
  2772.                    between FEA2 structures in the list. 
  2773.  
  2774.                    If a particular attribute is not attached to the object, 
  2775.                    pfindbuf has an FEA2 structure containing the name of the 
  2776.                    attribute, and the length value is 0. 
  2777.  
  2778.                    The GEA2 list contained inside pfindbuf during a Level 3 
  2779.                    DosFindFirst and DosFindNext call is not  read-only ; it is 
  2780.                    used by the operating system. When the function returns, the 
  2781.                    list is restored to its original state, but inside the 
  2782.                    function, the list is manipulated by the operating system. 
  2783.                    This is of concern to a multithreaded application, where two 
  2784.                    different threads might use the same GEA2 list as input. If 
  2785.                    one thread calls DosFindFirst or DosFindNext while another 
  2786.                    thread is inside DosFindFirst or DosFindNext, the second 
  2787.                    thread will fail with a return code of ERROR_BAD_FORMAT. 
  2788.  
  2789.            For Level 13 File Information (ulInfoLevel == FIL_QUERYEASFROMLISTL) 
  2790.                    On input, pfindbuf contains an EAOP2 data structure. 
  2791.                    fpGEA2List contains a pointer to a GEA2 list, which defines 
  2792.                    the attribute names whose values are to be returned. Entries 
  2793.                    in the GEA2 list must be aligned on a doubleword boundary. 
  2794.                    Each oNextEntryOffset field must contain the number of bytes 
  2795.                    from the beginning of the current entry to the beginning of 
  2796.                    the next entry. 
  2797.  
  2798.                    On output, pfindbuf contains a structure with a set of 
  2799.                    records, each aligned on a doubleword boundary. These 
  2800.                    records represent the directory entry and associated EAs for 
  2801.                    the matched file object. pfindbuf has the following format 
  2802.  
  2803.                        The EAOP2 data structure, with the fpFEA2List pointer 
  2804.                         incorrect. 
  2805.  
  2806.                         The EAOP2 data structure occurs only once in the 
  2807.                         pfindbuf buffer. The rest of these records are repeated 
  2808.                         for the remainder of the file objects found. 
  2809.  
  2810.                        A FILEFINDBUF3L data structure without the last two 
  2811.                         fields  cchName and achName. 
  2812.  
  2813.                        A FEA2LIST data structure contained in and related to 
  2814.                         the FILEFINDBUF3L returned. 
  2815.  
  2816.                        Length of the name string of the file object (cbName) 
  2817.  
  2818.                        Name of the file object matched by the input pattern 
  2819.                         (achName) 
  2820.  
  2821.                    Even if there is not enough room to hold all of the 
  2822.                    requested information, as for return code 
  2823.                    ERROR_BUFFER_OVERFLOW, the cbList field of the FEA2LIST data 
  2824.                    structure is valid if there is at least enough space to hold 
  2825.                    it. 
  2826.  
  2827.                    When buffer overflow occurs, cbList contains the size on 
  2828.                    disk of the entire EA set for the file, even if only a 
  2829.                    subset of its attributes was requested. The size of the 
  2830.                    buffer required to hold the EA set is less than or equal to 
  2831.                    twice the size of the EA set on disk. If no error occurs, 
  2832.                    cbList includes the pad bytes (for doubleword alignment) 
  2833.                    between FEA2 structures in the list. 
  2834.  
  2835.                    If a particular attribute is not attached to the object, 
  2836.                    pfindbuf has an FEA2 structure containing the name of the 
  2837.                    attribute, and the length value is 0. 
  2838.  
  2839.                    The GEA2 list contained inside pfindbuf during a Level 13 
  2840.                    DosFindFirst and DosFindNext call is not  read-only ; it is 
  2841.                    used by the operating system. When the function returns, the 
  2842.                    list is restored to its original state, but inside the 
  2843.                    function, the list is manipulated by the operating system. 
  2844.                    This is of concern to a multithreaded application, where two 
  2845.                    different threads might use the same GEA2 list as input. If 
  2846.                    one thread calls DosFindFirst or DosFindNext while another 
  2847.                    thread is inside DosFindFirst or DosFindNext, the second 
  2848.                    thread will fail with a return code of ERROR_BAD_FORMAT. 
  2849.  
  2850.  cbBuf  ULONG)  input 
  2851.            The length, in bytes, of pfindbuf. 
  2852.  
  2853.  pcFileNames  PULONG)  in/out 
  2854.            Pointer to the number of entries 
  2855.  
  2856.            Input        The address of the number of matching entries requested 
  2857.                         in pfindbuf. 
  2858.  
  2859.            Output       The number of entries placed into pfindbuf. 
  2860.  
  2861.  ulInfoLevel  ULONG)  input 
  2862.            The level of file information required. 
  2863.  
  2864.            Possible values are 
  2865.  
  2866.            1        FIL_STANDARD Level 1 file information (return standard file 
  2867.                     information). 
  2868.  
  2869.            11       FIL_STANDARDL 
  2870.  
  2871.                     Level 11 file information 
  2872.  
  2873.            2        FIL_QUERYEASIZE 
  2874.  
  2875.                     Level 2 file information 
  2876.  
  2877.            12       FIL_QUERYEASIZEL 
  2878.  
  2879.                     Level 12 file information 
  2880.  
  2881.            3        FIL_QUERYEASFROMLIST Level 3 file information (return 
  2882.                     requested EA). 
  2883.  
  2884.            13       FIL_QUERYEASFROMLISTL Level 13 file information (return 
  2885.                     requested EA). 
  2886.  
  2887.            The structures described in pfindbuf indicate the information 
  2888.            returned for each of these levels. 
  2889.  
  2890.            Regardless of the level specified, a DosFindFirst request (and an 
  2891.            associated DosFindNext request on a handle returned by DosFindFirst) 
  2892.            always includes Level 1 information as part of the information that 
  2893.            is returned; however, when Level 1 information is specifically 
  2894.            requested, and flAttribute specifies hidden files, system files, or 
  2895.            subdirectory files, an inclusive search is made. That is, all normal 
  2896.            file entries plus all entries matching any specified attributes are 
  2897.            returned. Normal files are files without any mode bits set. They may 
  2898.            be read from or written to. 
  2899.  
  2900.  Returns 
  2901.  
  2902.  ulrc  APIRET)  returns 
  2903.            Return Code. 
  2904.  
  2905.            DosFindFirst returns one of the following values 
  2906.  
  2907.            0              NO_ERROR 
  2908.  
  2909.            2              ERROR_FILE_NOT_FOUND 
  2910.  
  2911.            3              ERROR_PATH_NOT_FOUND 
  2912.  
  2913.            6              ERROR_INVALID_HANDLE 
  2914.  
  2915.            18             ERROR_NO_MORE_FILES 
  2916.  
  2917.            26             ERROR_NOT_DOS_DISK 
  2918.  
  2919.            87             ERROR_INVALID_PARAMETER 
  2920.  
  2921.            108            ERROR_DRIVE_LOCKED 
  2922.  
  2923.            111            ERROR_BUFFER_OVERFLOW 
  2924.  
  2925.            113            ERROR_NO_MORE_SEARCH_HANDLES 
  2926.  
  2927.            206            ERROR_FILENAME_EXCED_RANGE 
  2928.  
  2929.            208            ERROR_META_EXPANSION_TOO_LONG 
  2930.  
  2931.            254            ERROR_INVALID_EA_NAME 
  2932.  
  2933.            255            ERROR_EA_LIST_INCONSISTENT 
  2934.  
  2935.            275            ERROR_EAS_DIDNT_FIT 
  2936.  
  2937.  Remarks 
  2938.  
  2939.  The result buffer from DosFindFirst should be less than 64KB. 
  2940.  
  2941.  DosFindFirst returns directory entries (up to the number requested in 
  2942.  pcFileNames) and extended-attribute information for as many files or 
  2943.  subdirectories whose names, attributes, and EAs match the specification, and 
  2944.  whose information fits in pfindbuf. On output, pcFileNames contains the actual 
  2945.  number of directory entries returned. 
  2946.  
  2947.  The file name pointed to by pszFileSpec can contain global file-name 
  2948.  characters. 
  2949.  
  2950.  DosFindNext uses the directory handle associated with DosFindFirst to continue 
  2951.  the search started by the DosFindFirst request. 
  2952.  
  2953.  Any nonzero return code, except ERROR_EAS_DIDNT_FIT, indicates that no handle 
  2954.  has been allocated. This includes such non-error return codes as 
  2955.  ERROR_NO_MORE_FILES. 
  2956.  
  2957.  For ERROR_EAS_DIDNT_FIT, a search handle is returned, and a subsequent call to 
  2958.  DosFindNext gets the next matching entry in the directory. You can use 
  2959.  DosQueryPathInfo to retrieve the EAs for the matching entry by using the same 
  2960.  EA arguments used for the DosFindFirst call, and the name that was returned by 
  2961.  DosFindFirst. 
  2962.  
  2963.  For ERROR_EAS_DIDNT_FIT, only information for the first matching entry is 
  2964.  returned. This entry is the one whose extended attributes did not fit in the 
  2965.  buffer. The information returned is in the format of that returned for 
  2966.  information Level 2. No further entries are returned in the buffer, even if 
  2967.  they could fit in the remaining space. 
  2968.  
  2969.  The GEA2 list contained inside pfindbuf during a Level 3 DosFindFirst and 
  2970.  DosFindNext call is not  read-only , it is used by the operating system. When 
  2971.  the function returns, the list is restored to its original state, but inside 
  2972.  the function, the list is manipulated by the operating system. This is of 
  2973.  concern to a multithreaded application, where two different threads might use 
  2974.  the same GEA2 list as input. If one thread calls DosFindFirst or DosFindNext 
  2975.  while another thread is inside DosFindFirst or DosFindNext, the second thread 
  2976.  will fail with a return code of ERROR_BAD_FORMAT. 
  2977.  
  2978.  Related Functions 
  2979.  
  2980.      DosClose 
  2981.  
  2982.      DosFindClose 
  2983.  
  2984.      DosFindNext 
  2985.  
  2986.      DosQueryFileInfo 
  2987.  
  2988.      DosQueryPathInfo 
  2989.  
  2990.      DosQuerySysInfo 
  2991.  
  2992.      DosResetBuffer 
  2993.  
  2994.      DosSearchPath 
  2995.  
  2996.      DosSetFileInfo 
  2997.  
  2998.      DosSetPathInfo 
  2999.  
  3000.  Example Code 
  3001.  
  3002.  This example lists all the normal files that are in the directory from where 
  3003.  the example is invoked. 
  3004.  
  3005.   #define INCL_DOSFILEMGR   /* File Manager values */
  3006.   #define INCL_DOSERRORS    /* DOS error values */
  3007.   #include  os2.h
  3008.   #include  stdio.h
  3009.  
  3010.   int main (VOID)
  3011.   HDIR          hdirFindHandle = HDIR_CREATE;
  3012.   FILEFINDBUF3L FindBuffer     =  0 ;      /* Returned from FindFirst/Next */
  3013.   ULONG         ulResultBufLen = sizeof(FILEFINDBUF3L);
  3014.   ULONG         ulFindCount    = 1;        /* Look for 1 file at a time    */
  3015.   APIRET        rc             = NO_ERROR; /* Return code                  */
  3016.  
  3017.   rc = DosFindFirst( "*.*",                /* File pattern - all files     */
  3018.    hdirFindHandle,      /* Directory search handle      */
  3019.   FILE_NORMAL,          /* Search attribute             */
  3020.    FindBuffer,          /* Result buffer                */
  3021.   ulResultBufLen,       /* Result buffer length         */
  3022.    ulFindCount,         /* Number of entries to find    */
  3023.   FIL_STANDARDL);       /* Return Level 11 file info     */
  3024.  
  3025.   if (rc != NO_ERROR)
  3026.   printf("DosFindFirst error  return code = %u\n",rc);
  3027.   return 1;
  3028.     else
  3029.   printf ("%s\n", FindBuffer.achName);   /* Print file name             */
  3030.     /* endif */
  3031.  
  3032.   /* Keep finding the next file until there are no more files */
  3033.   while (rc != ERROR_NO_MORE_FILES)
  3034.   ulFindCount = 1;                      /* Reset find count.            */
  3035.  
  3036.   rc = DosFindNext(hdirFindHandle,      /* Directory handle             */
  3037.    FindBuffer,         /* Result buffer                */
  3038.   ulResultBufLen,      /* Result buffer length         */
  3039.    ulFindCount);       /* Number of entries to find    */
  3040.  
  3041.   if (rc != NO_ERROR    rc != ERROR_NO_MORE_FILES)
  3042.   printf("DosFindNext error  return code = %u\n",rc);
  3043.   return 1;
  3044.     else
  3045.   printf ("%s\n", FindBuffer.achName);    /* Print file name */
  3046.  
  3047.     /* endwhile */
  3048.  
  3049.   rc = DosFindClose(hdirFindHandle);    /* Close our directory handle */
  3050.   if (rc != NO_ERROR)
  3051.   printf("DosFindClose error  return code = %u\n",rc);
  3052.   return 1;
  3053.  
  3054.   return NO_ERROR;
  3055.  
  3056.  
  3057. ΓòÉΓòÉΓòÉ 5.8. DosFindNext ΓòÉΓòÉΓòÉ
  3058.  
  3059. Purpose 
  3060.  
  3061. DosFindNext finds the next set of file objects whose names match the 
  3062. specification in a previous call to DosFindFirst or DosFindNext. 
  3063.  
  3064. Syntax 
  3065.  
  3066. #define INCL DOSFILEMGR
  3067. #include  os2.h
  3068.  
  3069.  APIRET DosFindNext (HDIR hDir, PVOID pfindbuf, ULONG cbfindbuf, PULONG 
  3070.            pcFilenames) 
  3071.  
  3072.  Parameters 
  3073.  
  3074.  hDir  HDIR)  input 
  3075.            The handle of the directory. 
  3076.  
  3077.  pfindbuf  PVOID)  in/out 
  3078.            The address of the directory search information structure. 
  3079.  
  3080.            The information returned reflects the most recent call to DosClose 
  3081.            or DosResetBuffer. 
  3082.  
  3083.            For the continuation of a Level 3 (FIL_QUERYEASFROMLIST) File 
  3084.            Information search, this buffer should contain input in the same 
  3085.            format as a Level 3 File Information search by DosFindFirst. 
  3086.  
  3087.            See the description of the pfindbuf parameter in DosFindFirst for 
  3088.            information about the output data that the file system driver places 
  3089.            into this buffer. 
  3090.  
  3091.  cbfindbuf  ULONG)  input 
  3092.            The length, in bytes, of pfindbuf. 
  3093.  
  3094.  pcFilenames  PULONG)  in/out 
  3095.            Pointer to the number of entries. 
  3096.  
  3097.            Input        The address of the number of matching entries requested 
  3098.                         in pfindbuf. 
  3099.  
  3100.            Output       The number of entries placed into pfindbuf. 
  3101.  
  3102.  Returns 
  3103.  
  3104.  ulrc  APIRET)  returns 
  3105.            Return Code. 
  3106.  
  3107.            DosFindNext returns one of the following values 
  3108.  
  3109.            0              NO_ERROR 
  3110.  
  3111.            6              ERROR_INVALID_HANDLE 
  3112.  
  3113.            18             ERROR_NO_MORE_FILES 
  3114.  
  3115.            26             ERROR_NOT_DOS_DISK 
  3116.  
  3117.            87             ERROR_INVALID_PARAMETER 
  3118.  
  3119.            111            ERROR_BUFFER_OVERFLOW 
  3120.  
  3121.            275            ERROR_EAS_DIDNT_FIT 
  3122.  
  3123.  Remarks 
  3124.  
  3125.  If ERROR_BUFFER_OVERFLOW is returned, further calls to DosFindNext start the 
  3126.  search from the same entry. 
  3127.  
  3128.  If ERROR_EAS_DIDNT_FIT is returned, the buffer is too small to hold the 
  3129.  extended attributes (EAs) for the first matching entry being returned. A 
  3130.  subsequent call to DosFindNext gets the next matching entry. This enables the 
  3131.  search to continue if the extended attributes being returned are too large for 
  3132.  the buffer. You can use DosQueryPathInfo to retrieve the extended attributes 
  3133.  for the matching entry by using the same EA arguments used for the call to 
  3134.  DosFindFirst, and the name that was returned by DosFindFirst, 
  3135.  
  3136.  In the case of ERROR_EAS_DIDNT_FIT, only information for the first matching 
  3137.  entry is returned. This is the entry whose extended attributes did not fit in 
  3138.  the buffer. The information returned is in the format of Level 2 or Level 12 
  3139.  (FIL_QUERYEASIZE) File Information (FILEFINDBUF4 or FILEFINDBUF4L). No further 
  3140.  entries are returned in the buffer, even if they could fit in the remaining 
  3141.  space. 
  3142.  
  3143.  Related Functions 
  3144.  
  3145.      DosClose 
  3146.  
  3147.      DosFindClose 
  3148.  
  3149.      DosFindFirst 
  3150.  
  3151.      DosQueryFileInfo 
  3152.  
  3153.      DosQueryPathInfo 
  3154.  
  3155.      DosQuerySysInfo 
  3156.  
  3157.      DosResetBuffer 
  3158.  
  3159.      DosSearchPath 
  3160.  
  3161.      DosSetFileInfo 
  3162.  
  3163.      DosSetPathInfo 
  3164.  
  3165.  Example Code 
  3166.  
  3167.  This example lists all the normal files that are in the directory from where 
  3168.  the example is invoked. 
  3169.  
  3170.   #define INCL_DOSFILEMGR   /* File Manager values */
  3171.   #define INCL_DOSERRORS    /* DOS error values */
  3172.   #include  os2.h
  3173.   #include  stdio.h
  3174.  
  3175.   int main (VOID)
  3176.   HDIR          hdirFindHandle = HDIR_CREATE;
  3177.   FILEFINDBUF3L  FindBuffer     =  0 ;      /* Returned from FindFirst/Next */
  3178.   ULONG         ulResultBufLen = sizeof(FILEFINDBUF3L);
  3179.   ULONG         ulFindCount    = 1;        /* Look for 1 file at a time    */
  3180.   APIRET        rc             = NO_ERROR; /* Return code                  */
  3181.  
  3182.   rc = DosFindFirst( "*.*",                /* File pattern - all files     */
  3183.    hdirFindHandle,      /* Directory search handle      */
  3184.   FILE_NORMAL,          /* Search attribute             */
  3185.    FindBuffer,          /* Result buffer                */
  3186.   ulResultBufLen,       /* Result buffer length         */
  3187.    ulFindCount,         /* Number of entries to find    */
  3188.   FIL_STANDARDL);       /* Return level 1 file info     */
  3189.  
  3190.   if (rc != NO_ERROR)
  3191.   printf("DosFindFirst error  return code = %u\n",rc);
  3192.   return 1;
  3193.     else
  3194.   printf ("%s\n", FindBuffer.achName);   /* Print file name             */
  3195.     /* endif */
  3196.  
  3197.   /* Keep finding the next file until there are no more files */
  3198.   while (rc != ERROR_NO_MORE_FILES)
  3199.   ulFindCount = 1;                      /* Reset find count.            */
  3200.  
  3201.   rc = DosFindNext(hdirFindHandle,      /* Directory handle             */
  3202.    FindBuffer,         /* Result buffer                */
  3203.   ulResultBufLen,      /* Result buffer length         */
  3204.    ulFindCount);       /* Number of entries to find    */
  3205.  
  3206.   if (rc != NO_ERROR    rc != ERROR_NO_MORE_FILES)
  3207.   printf("DosFindNext error  return code = %u\n",rc);
  3208.   return 1;
  3209.     else
  3210.   printf ("%s\n", FindBuffer.achName);    /* Print file name */
  3211.  
  3212.     /* endwhile */
  3213.  
  3214.   rc = DosFindClose(hdirFindHandle);    /* Close our directory handle */
  3215.   if (rc != NO_ERROR)
  3216.   printf("DosFindClose error  return code = %u\n",rc);
  3217.   return 1;
  3218.  
  3219.   return NO_ERROR;
  3220.  
  3221.  
  3222. ΓòÉΓòÉΓòÉ 5.9. DosForceSystemDump ΓòÉΓòÉΓòÉ
  3223.  
  3224. Purpose 
  3225.  
  3226. DosForceSystemDump initiates a stand-alone dump. The system terminates abruptly 
  3227. without shutdown as soon as the dump is inititated. 
  3228.  
  3229. Syntax 
  3230.  
  3231. #define INCL_DOSMISC
  3232. #include  os2.h>
  3233.  
  3234.  APIRET APIENTRY DosForceSystemDump (ULONG reserved) 
  3235.  
  3236.  Parameters 
  3237.  
  3238.  reserved(ULONG)  input 
  3239.  
  3240.  Returns 
  3241.  
  3242.  ulrc (APIRET)  returns 
  3243.            Return Code. 
  3244.  
  3245.            DosForceSystemDump returns the following value 
  3246.  
  3247.            87             ERROR_INVALID_PARAMETER 
  3248.  
  3249.  Related Functions 
  3250.  
  3251.      DosDumpProcess 
  3252.  
  3253.      DosSysTrace 
  3254.  
  3255.  Example Code 
  3256.  
  3257.   int main(int argc, char *argv[], char *envp[])
  3258.   {
  3259.      APIRET rc;
  3260.  
  3261.      rc=DosForceSystemDump(0L);   /* will kill the system with a system dump */
  3262.                                   /* does not return unless an error occurs */
  3263.  
  3264.      printf("DosForceSystemDump returned %u\n",rc);
  3265.  
  3266.      return rc;
  3267.   }
  3268.  
  3269.  
  3270. ΓòÉΓòÉΓòÉ 5.10. DosGetProcessorStatus ΓòÉΓòÉΓòÉ
  3271.  
  3272. Purpose 
  3273.  
  3274. DosGetProcessorStatus returns the ONLINE or OFFLINE status of each processor of 
  3275. an SMP system. The processor status may be set using DosSetProcessorStatus. 
  3276. ONLINE status imples the processor is available for running work. OFFLINE 
  3277. status implies the porcessor is not available for running work. 
  3278.  
  3279. Syntax 
  3280.  
  3281. #define INCL_DOS
  3282. #define INCL_DOSSPINLOCK
  3283. #include  os2.h>
  3284.  
  3285.  APIRET APRIENTRY DosGetProcessorStatus (ULONG procid, PULONG status) 
  3286.  
  3287.  Parameters 
  3288.  
  3289.  procid (ULONG)  input 
  3290.            Procesor ID numbered 1 through n, where there are n processors in 
  3291.            total 
  3292.  
  3293.  status (PULONG)  output 
  3294.            Status is defined as follows 
  3295.  
  3296.            PROC_OFFLINE 0x00000000 Processor is offline 
  3297.  
  3298.            PROC_ONLINE 0x00000001 Processor is online 
  3299.  
  3300.  Returns 
  3301.  
  3302.  ulrc (APIRET)  returns 
  3303.            Return Code. 
  3304.  
  3305.            DosGetProcessorStatus returns one of the following values 
  3306.  
  3307.            0              NO_ERROR 
  3308.  
  3309.            87             ERROR_INVALID_PARAMETER 
  3310.  
  3311.  Related Functions 
  3312.  
  3313.      DosSetProcessorStatus 
  3314.  
  3315.  Example Code 
  3316.  
  3317.   int main(int argc, char *argv[], char *envp[])
  3318.   {
  3319.      APIRET rc=0;
  3320.      ULONG procid;
  3321.      ULONG status;
  3322.      int i;
  3323.  
  3324.      if (argc == 1) {
  3325.         for (procid=1; rc==0 ;++procid) {
  3326.            rc = DosGetProcessorStatus(procid,  status);
  3327.            if (rc==0) {
  3328.               if (status == PROC_OFFLINE) printf("Processor %u offline\n", procid);
  3329.               else printf("Processor %u online\n", procid);
  3330.            } /* endif */
  3331.         } /* endfor */
  3332.  
  3333.      } else for (i=1; i argc ; ++i) {
  3334.         procid = atol(argv[i]);
  3335.         rc = DosGetProcessorStatus(procid,  status);
  3336.         if (rc) printf("DosGetProcesorStatus returned %u\n",rc);
  3337.         else {
  3338.            if (status == PROC_OFFLINE) printf("Processor %u offline\n", procid);
  3339.            else printf("Processor %u online\n", procid);
  3340.         } /* endif */
  3341.      } /* endfor */
  3342.  
  3343.      return rc;
  3344.   }
  3345.  
  3346.  
  3347. ΓòÉΓòÉΓòÉ 5.11. DosListIO ΓòÉΓòÉΓòÉ
  3348.  
  3349. Purpose 
  3350.  
  3351. DosListIO performs the specified number of seek/read and/or seek/write 
  3352. operations. 
  3353.  
  3354. Syntax 
  3355.  
  3356. #define INCL_DOSFILEMGR
  3357. #include  os2.h>
  3358.  
  3359.  APIRET DosListIO (ULONG CmdMode, ULONG NumEntries, PLISTIO pListIO) 
  3360.  
  3361.  Parameters 
  3362.  
  3363.  CmdMode (ULONG)  input 
  3364.            This specifies the mode in which the operations should be performed. 
  3365.            Valid modes are 
  3366.  
  3367.            LISTIO_ORDERED 
  3368.                     Operations are performed synchronously in the given order. 
  3369.  
  3370.            LISTIO_UNORDERED 
  3371.                     Operations are performed independent of order. 
  3372.  
  3373.  NumEntries (ULONG)  input 
  3374.            The number of seek/read or seek/write operations in the list. 
  3375.  
  3376.  pListIO (PLISTIO)  input/output 
  3377.            Pointer to an array of NumEntries LISTIO data structures which 
  3378.            contain the information necessary to perform the seek/read and 
  3379.            seek/write operations. 
  3380.  
  3381.  Returns 
  3382.  
  3383.  ulrc (APIRET)  returns 
  3384.            Return Code. 
  3385.  
  3386.            DosListIO returns one of the following values 
  3387.  
  3388.            0              NO_ERROR 
  3389.  
  3390.            5              ERROR_ACCESS_DENIED 
  3391.  
  3392.            6              ERROR_INVALID_HANDLE 
  3393.  
  3394.            19             ERROR_WRITE_PROTECT 
  3395.  
  3396.            26             ERROR_NOT_DOS_DISK 
  3397.  
  3398.            29             ERROR_WRITE_FAULT 
  3399.  
  3400.            33             ERROR_LOCK_VIOLATION 
  3401.  
  3402.            87             ERROR_INVALID_PARAMETER 
  3403.  
  3404.            109            ERROR_BROKEN_PIPE 
  3405.  
  3406.            234            ERROR_MORE_DATA 
  3407.  
  3408.  Remarks 
  3409.  
  3410.  DosListIO applies the same restrictions for each seek/read and seek/write 
  3411.  control block as would be applied if the requests were issued separately with 
  3412.  DosSetFilePtr, DosRead, and DosWrite. 
  3413.  
  3414.  Each request control block contains fields for the Actual number of bytes 
  3415.  read/written and the operation return code. These fields are updated upon 
  3416.  completion of each request, therefore care must be taken that the memory 
  3417.  containing the control block array not be deallocated or manipulated by 
  3418.  another thread before the DosListIO request returns. 
  3419.  
  3420.  There are two valid modes for the list of I/O operations to be processed 
  3421.  
  3422.      Ordered - This mode guarantees the order in which the operations will be 
  3423.       performed. The API will return with an error code corresponding to the 
  3424.       first failed request and will leave the following requests unissued. This 
  3425.       provide a synchronous sequence of automatic seek/read and seek/write 
  3426.       requests. This is the only mode that is compatible with file systems 
  3427.       other than the raw file system. 
  3428.  
  3429.      Unordered - This mode does not guarantee the order of issue or completion 
  3430.       of the requests. The API will return with an error code if any request 
  3431.       fails. Additionally, each request in the list will be issued, even those 
  3432.       following a failed operation. This mode is valid for the raw file system 
  3433.       only. 
  3434.  
  3435.  Related Functions 
  3436.  
  3437.      DosOpen 
  3438.  
  3439.      DosSetFilePtr 
  3440.  
  3441.      DosRead 
  3442.  
  3443.      DosWrite 
  3444.  
  3445.  Example Code 
  3446.  
  3447.  The following is NOT a complete usable program.  It is simply intended to 
  3448.  provide an idea of how to use Raw I/O File System APIs (e.g. DosOpen, 
  3449.  DosListIO, and DosClose). 
  3450.  
  3451.  This example opens physical disk #1 for reading and physical disk #2  for 
  3452.  writing.  Using DosListIO, 10 megabytes of data is transferred disk #1 to disk 
  3453.  #2.  Finally, DosClosed is issued to close the disk handles. 
  3454.  
  3455.  It is assumed that the size of each of the two disks is at least 10 megabytes. 
  3456.  
  3457.   #define INCL_DOSFILEMGR          /* Include File Manager APIs */
  3458.   #define INCL_DOSMEMMGR           /* Includes Memory Management APIs */
  3459.   #define INCL_DOSERRORS           /* DOS Error values */
  3460.   #include  os2.h>
  3461.   #include  stdio.h>
  3462.   #include  stdlib.h>
  3463.   #include  string.h>
  3464.  
  3465.   #define SIXTY_FOUR_K 0x10000
  3466.   #define ONE_MEG     0x100000
  3467.   #define TEN_MEG     10*ONE_MEG
  3468.  
  3469.   #define UNC_DISK1  "\\\\.\\Physical_Disk1"
  3470.   #define UNC_DISK2  "\\\\.\\Physical_Disk2"
  3471.  
  3472.   int main(void) {
  3473.      LISTIO listIOCtrlBlks[2];          /* List IO control blocks   */
  3474.      ULONG  ulNumCtrlBlks;              /* Number of control blocks */
  3475.      HFILE  hfDisk1        = 0;         /* Handle for disk #1 */
  3476.      HFILE  hfDisk2        = 0;         /* Handle for disk #2 */
  3477.      ULONG  ulAction       = 0;         /* Action taken by DosOpen */
  3478.      UCHAR  uchFileName1[20]  = UNC_DISK1, /* UNC Name of disk 1 */
  3479.             uchFileName2[20]  = UNC_DISK2; /* UNC Name of disk 2 */
  3480.      PBYTE  pBuffer        = 0;
  3481.      ULONG  cbTotal        = 0;
  3482.  
  3483.      APIRET rc = NO_ERROR;              /* Return code */
  3484.  
  3485.      /* Open a raw file system disk #1 for reading */
  3486.      rc = DosOpen(uchFileName1,               /* File name */
  3487.                    hfDisk1,                   /* File handle */
  3488.                    ulAction,                  /* Action taken by DosOpen */
  3489.                   0L,                         /* no file size */
  3490.                   FILE_NORMAL,                /* File attribute */
  3491.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  3492.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  3493.                   OPEN_ACCESS_READONLY,
  3494.                   0L);                        /* No extented attributes */
  3495.      if (rc != NO_ERROR) {
  3496.         printf("DosOpen error rc = %u\n", rc);
  3497.         return(1);
  3498.      } /* endif */
  3499.  
  3500.      /* Open a raw file system disk #2 for writing */
  3501.      rc = DosOpen(uchFileName2,               /* File name */
  3502.                    hfDisk2,                   /* File handle */
  3503.                    ulAction,                  /* Action taken by DosOpen */
  3504.                   0L,                         /* no file size */
  3505.                   FILE_NORMAL,                /* File attribute */
  3506.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  3507.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  3508.                   OPEN_ACCESS_READWRITE,
  3509.                   0L);                        /* No extented attributes */
  3510.      if (rc != NO_ERROR) {
  3511.         printf("DosOpen error rc = %u\n", rc);
  3512.         return(1);
  3513.      } /* endif */
  3514.  
  3515.  
  3516.      /* Allocate 64K of memory for transfer operations */
  3517.      rc = DosAllocMem((PPVOID) pBuffer, /* Pointer to buffer */
  3518.                        SIXTY_FOUR_K,      /* Buffer size */
  3519.                        PAG_COMMIT |     /* Allocation flags */
  3520.                        PAG_READ |
  3521.                        PAG_WRITE);
  3522.      if (rc != NO_ERROR) {
  3523.         printf("DosAllocMem error rc = %u\n", rc);
  3524.         return(1);
  3525.      } /* endif */
  3526.  
  3527.      /* Initialize listIO control blocks */
  3528.      memset(listIOCtrlBlks, 0, sizeof(listIOCtrlBlks));
  3529.  
  3530.      listIOCtrlBlks[0].hFile = hfDisk1;       /* Handle for disk 1 */
  3531.      listIOCtrlBlks[0].CmdFlag = LISTIO_READ | /* Read operation */
  3532.                                  FILE_CURRENT;
  3533.      listIOCtrlBlks[0].Offset = 0;
  3534.      listIOCtrlBlks[0].pBuffer = (PVOID)pBuffer;
  3535.      listIOCtrlBlks[0].NumBytes = SIXTY_FOUR_K;
  3536.  
  3537.      listIOCtrlBlks[1].hFile = hfDisk2;        /* Handle for disk 2 */
  3538.      listIOCtrlBlks[1].CmdFlag = LISTIO_WRITE | /* Write operation */
  3539.                                  FILE_CURRENT;
  3540.      listIOCtrlBlks[1].Offset = 0;
  3541.      listIOCtrlBlks[1].pBuffer = (PVOID)pBuffer;
  3542.      listIOCtrlBlks[1].NumBytes = SIXTY_FOUR_K;
  3543.  
  3544.      while (cbTotal   TEN_MEG) {
  3545.  
  3546.  
  3547.         ulNumCtrlBlks = 2;
  3548.         rc = DosListIO(LISTIO_ORDERED,
  3549.                        ulNumCtrlBlks,
  3550.                        listIOCtrlBlks);
  3551.         if (rc != NO_ERROR) {
  3552.            printf("DosListIO error  rc = %u\n", rc);
  3553.            break;
  3554.         } else {
  3555.  
  3556.            /* Check return code from the read operation */
  3557.            if (listIOCtrlBlks[0].RetCode != NO_ERROR) {
  3558.               printf("DosListIO read operation failed, rc = %u\n",
  3559.                       listIOCtrlBlks[0].RetCode);
  3560.              return 1;
  3561.            }
  3562.  
  3563.            /* Check return code from the write operation */
  3564.            if (listIOCtrlBlks[0].RetCode != NO_ERROR) {
  3565.               printf("DosListIO write operation failed, rc = %u\n",
  3566.                       listIOCtrlBlks[0].RetCode);
  3567.               return 1;
  3568.            }
  3569.         }
  3570.  
  3571.         if (listIOCtrlBlks[0].Actual != listIOCtrlBlks[1].Actual) {
  3572.            printf("Bytes read (%u) does not equal bytes written (%u)\n",
  3573.                   listIOCtrlBlks[0].Actual, listIOCtrlBlks[1].Actual);
  3574.            return 1;
  3575.         }
  3576.  
  3577.         cbTotal += SIXTY_FOUR_K; /* Update total transferred */
  3578.  
  3579.      } /* end while */
  3580.  
  3581.      printf("Transfer successfully %d bytes from disk #1 to disk #2.\n",
  3582.             cbTotal);
  3583.  
  3584.      /* Free allocated memmory */
  3585.      rc = DosFreeMem(pBuffer);
  3586.      if (rc != NO_ERROR) {
  3587.         printf("DosFreeMem error  return code = %u\n", rc);
  3588.         return 1;
  3589.      }
  3590.  
  3591.      rc = DosClose(hfDisk1);
  3592.      if (rc != NO_ERROR) {
  3593.         printf("DosClose error  return code = %u\n", rc);
  3594.         return 1;
  3595.      }
  3596.  
  3597.      rc = DosClose(hfDisk2);
  3598.      if (rc != NO_ERROR) {
  3599.         printf("DosClose error  return code = %u\n", rc);
  3600.         return 1;
  3601.      }
  3602.   return NO_ERROR;
  3603.   }
  3604.  
  3605.  
  3606. ΓòÉΓòÉΓòÉ 5.12. DosListIOL ΓòÉΓòÉΓòÉ
  3607.  
  3608. Purpose 
  3609.  
  3610. DosListIOL performs the specified number of seek/read or seek/write operations 
  3611. or both. 
  3612.  
  3613. Syntax 
  3614.  
  3615. #define INCL_DOSFILEMGR
  3616. #include  os2.h>
  3617.  
  3618.  APIRET DosListIOL (LONG CmdMode, LONG NumEntries, PLISTIOL pListIO) 
  3619.  
  3620.  Parameters 
  3621.  
  3622.  CmdMode (LONG)  input 
  3623.            This specifies the mode in which the operations should be performed. 
  3624.            Valid modes are 
  3625.  
  3626.            LISTIO_ORDERED 
  3627.                     Operations are performed synchronously in the given order. 
  3628.  
  3629.            LISTIO_UNORDERED 
  3630.                     Operations are performed independent of order. 
  3631.  
  3632.  NumEntries (LONG)  input 
  3633.            The number of seek/read or seek/write operations in the list. 
  3634.  
  3635.  pListIOL (PLISTIO)  input/output 
  3636.            Pointer to an array of NumEntries LISTIO data structures which 
  3637.            contain the information necessary to perform the seek/read and 
  3638.            seek/write operations. 
  3639.  
  3640.  Returns 
  3641.  
  3642.  ulrc (APIRET)  returns 
  3643.            Return Code. 
  3644.  
  3645.            DosListIOL returns one of the following values 
  3646.  
  3647.            0              NO_ERROR 
  3648.  
  3649.            5              ERROR_ACCESS_DENIED 
  3650.  
  3651.            6              ERROR_INVALID_HANDLE 
  3652.  
  3653.            19             ERROR_WRITE_PROTECT 
  3654.  
  3655.            26             ERROR_NOT_DOS_DISK 
  3656.  
  3657.            29             ERROR_WRITE_FAULT 
  3658.  
  3659.            33             ERROR_LOCK_VIOLATION 
  3660.  
  3661.            87             ERROR_INVALID_PARAMETER 
  3662.  
  3663.            109            ERROR_BROKEN_PIPE 
  3664.  
  3665.            234            ERROR_MORE_DATA 
  3666.  
  3667.  Remarks 
  3668.  
  3669.  DosListIOL applies the same restrictions for each seek/read and seek/write 
  3670.  control block as would be applied if the requests were issued separately with 
  3671.  DosSetFilePtrL, DosRead, and DosWrite. 
  3672.  
  3673.  Each request control block contains fields for the Actual number of bytes 
  3674.  read/written and the operation return code. These fields are updated upon 
  3675.  completion of each request; therefore, care must be taken that the memory 
  3676.  containing the control block array not be deallocated or manipulated by 
  3677.  another thread before the DosListIOL request returns. 
  3678.  
  3679.  There are two valid modes for the list of I/O operations to be processed 
  3680.  
  3681.      Ordered - This mode guarantees the order in which the operations will be 
  3682.       performed. The API will return with an error code corresponding to the 
  3683.       first failed request and will leave the following requests unissued. This 
  3684.       provides a synchronous sequence of automatic seek/read and seek/write 
  3685.       requests. This is the only mode that is compatible with file systems 
  3686.       other than the raw file system. 
  3687.  
  3688.      Unordered - This mode does not guarantee the order of issue or completion 
  3689.       of the requests. The API will return with an error code if any request 
  3690.       fails. Additionally, each request in the list will be issued, even those 
  3691.       following a failed operation. This mode is valid for the raw file system 
  3692.       only. 
  3693.  
  3694.  Related Functions 
  3695.  
  3696.      DosOpenL 
  3697.  
  3698.      DosSetFilePtrL 
  3699.  
  3700.      DosRead 
  3701.  
  3702.      DosWrite 
  3703.  
  3704.  Example Code 
  3705.  
  3706.  In this example, the source file  SOURCE.DAT  is copied to  TARGET.DAT. 
  3707.  First, the information about the source file is obtained by calling 
  3708.  DosQueryPathInfo. Next, the target file is created with the same size as the 
  3709.  source file. Using a series of calls to DosListIO, the content of the source 
  3710.  file is copied to the target file. 
  3711.  
  3712.   #define INCL_DOSFILEMGR          /* File Manager values */
  3713.   #define INCL_DOSERRORS           /* DOS Error values    */
  3714.   #define INCL_LONGLONG
  3715.   #include #define SOURCE_PATHNAME "source.dat"
  3716.   #define TARGET_PATHNAME "target.dat"
  3717.   #define BUFFER_SIZE 4096
  3718.  
  3719.   int main(void) {
  3720.      FILESTATUS3L  fsSource = { {0} };          /* Buffer for information about source file  */
  3721.      LONGLONG llSize;                           /* Source file size (totalcopy size) */
  3722.      HFILE  hfSource   = 0L;                    /* Handle for source file */
  3723.      HFILE  hfTarget   = 0L;                    /* Handle for target file */
  3724.      ULONG  ulAction = 0;                       /* Action taken by DosOpen*/
  3725.      LISTIOL listIOCtrlBlks[2];                 /* List IO control blocks */
  3726.      ULONG  ulNumCtrlBlks;                      /* Number of control blocks*/
  3727.      BYTE   pData[BUFFER_SIZE];                 /* Buffer to hold copy data */
  3728.      ULONG  cbData;                             /* Size of data for each IO operation */
  3729.      APIRET rc = NO_ERROR;                      /* Return code */
  3730.  
  3731.      /* Query information about the source file to obtain its size */
  3732.      rc = DosQueryPathInfo(SOURCE_PATHNAME, FIL_STANDARDL,  fsSource, sizeof(fsSource));
  3733.      if (rc != NO_ERROR)
  3734.      {
  3735.         printf("DosQueryPathInfo failed, return code = %u\n", rc);
  3736.         return 1;
  3737.      }
  3738.  
  3739.      llSize = fsSource.cbFile;
  3740.  
  3741.      /* Open the source file for reading */
  3742.      rc = DosOpenL(SOURCE_PATHNAME,               /* File path name */
  3743.                    hfSource,                      /* File handle */
  3744.                    ulAction,                      /* Action taken */
  3745.                   0,                              /* File primary allocation */
  3746.                   FILE_ARCHIVED | FILE_NORMAL,    /* File attribute */
  3747.                   OPEN_ACTION_FAIL_IF_NEW |       /* Open existing file */
  3748.                   OPEN_ACTION_OPEN_IF_EXISTS,
  3749.                   OPEN_FLAGS_NOINHERIT |
  3750.                   OPEN_SHARE_DENYNONE  |
  3751.                   OPEN_ACCESS_READWRITE,          /* Open mode of the file */
  3752.                   0L);                            /* No extended attribute */
  3753.  
  3754.      if (rc != NO_ERROR)
  3755.      {
  3756.         printf("DosOpenL failed to open %s, rc = %u\n", SOURCE_PATHNAME, rc);
  3757.         return 1;
  3758.      }
  3759.  
  3760.      /* Open the target file for writing */
  3761.      rc = DosOpenL(TARGET_PATHNAME,               /* File path name */
  3762.                    hfTarget,                      /* File handle */
  3763.                    ulAction,                      /* Action taken */
  3764.                   llSize,                         /* Target equals source file size */
  3765.                   FILE_ARCHIVED | FILE_NORMAL,    /* File attribute */
  3766.                   OPEN_ACTION_CREATE_IF_NEW |     /* Open new file */
  3767.                   OPEN_ACTION_FAIL_IF_EXISTS,
  3768.                   OPEN_FLAGS_NOINHERIT |
  3769.                   OPEN_SHARE_DENYNONE  |
  3770.                   OPEN_ACCESS_READWRITE,          /* Open mode of the file */
  3771.                   0L);                            /* No extended attribute */
  3772.  
  3773.      if (rc != NO_ERROR)
  3774.      {
  3775.         printf("DosOpenL failed to create %s, rc = %u\n", TARGET_PATHNAME, rc);
  3776.         DosClose(hfSource);  /* Remember to close source file before exiting */
  3777.         return 1;
  3778.      }
  3779.   In this example, the source file "SOURCE.DAT" is copied to "TARGET.DAT." First,
  3780.   the information about the source file is obtained by calling DosQueryPathInfo.
  3781.   Next, the target file is created with the same size as the source file. Using
  3782.   a series of calls to DosListIO, the content of the source file is copied to
  3783.   the target file.   /* Initialize listIOL control blocks */
  3784.      memset(listIOCtrlBlks, 0, sizeof(listIOCtrlBlks));
  3785.  
  3786.      listIOCtrlBlks[0].hFile = hfSource;                      /* Source file handle */
  3787.      listIOCtrlBlks[0].CmdFlag = LISTIO_READ | FILE_CURRENT;  /* Read operation */
  3788.      listIOCtrlBlks[0].Offset = 0;
  3789.      listIOCtrlBlks[0].pBuffer = (PVOID)pData;
  3790.  
  3791.      listIOCtrlBlks[1].hFile = hfTarget;                      /* Target file handle */
  3792.      listIOCtrlBlks[1].CmdFlag = LISTIO_WRITE | FILE_CURRENT; /* Write operation */
  3793.      listIOCtrlBlks[1].Offset = 0;
  3794.      listIOCtrlBlks[1].pBuffer = (PVOID)pData;
  3795.  
  3796.      while (llSize) {
  3797.  
  3798.         if (llSize   BUFFER_SIZE) {
  3799.            cbData = llSize;
  3800.         } else {
  3801.            cbData = BUFFER_SIZE;
  3802.         }
  3803.         llSize = llSize - cbData;   /* adjust remaining copy size */
  3804.  
  3805.         listIOCtrlBlks[0].NumBytes = cbData;
  3806.         listIOCtrlBlks[1].NumBytes = cbData;
  3807.  
  3808.         ulNumCtrlBlks = 2;
  3809.         rc = DosListIOL(LISTIO_ORDERED,
  3810.                        ulNumCtrlBlks,
  3811.                        listIOCtrlBlks);
  3812.         if (rc != NO_ERROR)
  3813.         {
  3814.            printf("DosListIOL error  rc = %u\n", rc);
  3815.            break;
  3816.         }
  3817.         else
  3818.         {
  3819.  
  3820.            /* Check return code from the read operation */
  3821.            if (listIOCtrlBlks[0].RetCode != NO_ERROR)
  3822.            {
  3823.               printf("DosListIOL read operation failed, rc = %u\n", listIOCtrlBlks[0].RetCode);
  3824.               break;
  3825.            }
  3826.  
  3827.            /* Check return code from the write operation */
  3828.            if (listIOCtrlBlks[0].RetCode != NO_ERROR)
  3829.            {
  3830.               printf("DosListIOL write operation failed, rc = %u\n", listIOCtrlBlks[0].RetCode);
  3831.               break;
  3832.            }
  3833.         }
  3834.      } /* end while */
  3835.  
  3836.      DosClose(hfSource);                /* Close source file */
  3837.      DosClose(hfTarget);                /* Close target file */
  3838.  
  3839.      return NO_ERROR;
  3840.   }
  3841.  
  3842.  
  3843. ΓòÉΓòÉΓòÉ 5.13. DosOpen ΓòÉΓòÉΓòÉ
  3844.  
  3845. Purpose 
  3846.  
  3847. DosOpen opens a physical or logical disk and returns a handle to be used to 
  3848. perform operations upon the disk specified. 
  3849.  
  3850. Syntax 
  3851.  
  3852. #define INCL DOSFILEMGR
  3853. #include  os2.h
  3854.  
  3855.  APIRET DosOpen (PSZ pszFileName, PHFILE pHf, PULONG pulAction, ULONG cbFile, 
  3856.            ULONG ulAttribute, ULONG fsOpenFlags, ULONG fsOpenMode, PEAOP2 
  3857.            peaop2) 
  3858.  
  3859.  Parameters 
  3860.  
  3861.  pszFileName  PSZ)  input 
  3862.            Address of the ASCIIZ path name of the logical partition or physical 
  3863.            disk to be opened. 
  3864.  
  3865.  pHf  PHFILE)  output 
  3866.            Address of the handle for the disk. 
  3867.  
  3868.  pulAction  PULONG)  output 
  3869.            Address of the variable that receives the value that specifies the 
  3870.            action taken by the DosOpen function. 
  3871.  
  3872.            If DosOpen fails, this value has no meaning. Otherwise, the raw file 
  3873.            system should always reutn FILE_EXISTED (1). 
  3874.  
  3875.  cbFile  ULONG)  input 
  3876.            Not used by the raw file system. 
  3877.  
  3878.  ulAttribute  ULONG)  input 
  3879.            File attributes are ignored because disks are not created. 
  3880.  
  3881.  fsOpenFlags  ULONG)  input 
  3882.            Not used by the raw file system. 
  3883.  
  3884.  fsOpenMode  ULONG)  input 
  3885.            OPEN_ACCESS_READWRITE - Only valid access mode. 
  3886.  
  3887.            OPEN_SHARE_DENYNONE - Allows other processes to read/write from 
  3888.            disk. 
  3889.  
  3890.            OPEN_SHARE_DENYREADWRITE - Locks disk from access by other processes 
  3891.            and file systems. 
  3892.  
  3893.            Invalid flags are  OPEN_ACCESS_WRITEONLY, OPEN_ACCESS_READONLY, 
  3894.            OPEN_SHARE_DENYREAD, OPEN_SHARE_DENYWRITE, and OPEN_FLAGS_DASD. 
  3895.  
  3896.            Valid but unimplemented flags are  OPEN_FLAGS_NOINHERIT, 
  3897.            OPEN_FLAGS_RANDOMSEQUENTIAL, OPEN_FLAGS_RANDOM, 
  3898.            OPEN_FLAGS_SEQUENTIAL, OPEN_FLAGS_NO_LOCALITY, OPEN_FLAGS_NO_CACHE, 
  3899.            OPEN_FLAGS_FAIL_ON_ERROR, and OPEN_FLAGS_WRITE_THROUGH. 
  3900.  
  3901.  peaop2  PEAOP2)  in/out 
  3902.            Unused by raw file system. 
  3903.  
  3904.  Returns 
  3905.  
  3906.  ulrc  APIRET)  returns 
  3907.            Return Code. 
  3908.  
  3909.            DosOpen returns one of the following values 
  3910.  
  3911.            0              NO_ERROR 
  3912.  
  3913.            2              ERROR_FILE_NOT_FOUND 
  3914.  
  3915.            3              ERROR_PATH_NOT_FOUND 
  3916.  
  3917.            4              ERROR_TOO_MANY_OPEN_FILES 
  3918.  
  3919.            5              ERROR_ACCESS_DENIED 
  3920.  
  3921.            12             ERROR_INVALID_ACCESS 
  3922.  
  3923.            26             ERROR_NOT_DOS_DISK 
  3924.  
  3925.            32             ERROR_SHARING_VIOLATION 
  3926.  
  3927.            36             ERROR_SHARING_BUFFER_EXCEEDED 
  3928.  
  3929.            82             ERROR_CANNOT_MAKE 
  3930.  
  3931.            87             ERROR_INVALID_PARAMETER 
  3932.  
  3933.            99             ERROR_DEVICE_IN_USE 
  3934.  
  3935.            108            ERROR_DRIVE_LOCKED 
  3936.  
  3937.            110            ERROR_OPEN_FAILED 
  3938.  
  3939.            112            ERROR_DISK_FULL 
  3940.  
  3941.            206            ERROR_FILENAME_EXCED_RANGE 
  3942.  
  3943.            231            ERROR_PIPE_BUSY 
  3944.  
  3945.  Remarks 
  3946.  
  3947.  A successful DosOpen request returns a handle for accessing the disk. The 
  3948.  read/write pointer is set at the first byte of the disk. The position of the 
  3949.  pointer can be changed with DosSetFilePtr or by read and write operations on 
  3950.  the disk. 
  3951.  
  3952.  The direct open bit (OPEN_FLAGS_DASD) is not used with the raw file system. 
  3953.  However, when using the raw file system to access logical partitions and disk 
  3954.  locking is required, the following logic should be used.  First, the 
  3955.  application should lock the disk by passing the handle to DosDevIOCtl, 
  3956.  Category 8, DSK_LOCKDRIVE. Second, the application should perform the desired 
  3957.  operations on the disk. Lastly, the application should unlock the disk using 
  3958.  DosDevIOCtl Category 8, DSK_UNLOCKDRIVE. 
  3959.  
  3960.  If locking is desired when using the raw file system on physical disk, the 
  3961.  OPEN_SHARE_DENYREADWRITE flag should be used. The disk will automatically be 
  3962.  unlocked when the disk is closed with DosClose. 
  3963.  
  3964.  Related Functions 
  3965.  
  3966.      DosClose 
  3967.  
  3968.      DosDevIOCtl 
  3969.  
  3970.  Example Code 
  3971.  
  3972.  The following is NOT a complete usable program.  It is simply intended  to 
  3973.  provide an idea of how to use Raw I/O File System APIs (e.g. DosOpen, DosRead, 
  3974.  DosWrite, DosSetFilePtr, and DosClose). 
  3975.  
  3976.  This example opens physical disk #1 for reading and physical disk #2  for 
  3977.  writing.  DosSetFilePtr is used to set the pointer to the beginning of the 
  3978.  disks. Using DosRead and DosWrite, 10 megabytes of data is transferred from 
  3979.  disk #1 to disk #2. Finally, DosClosed is issued to close the disk handles. 
  3980.  
  3981.  It is assumed that the size of each of the two disks is at least 10 megabytes. 
  3982.  
  3983.   #define INCL_DOSFILEMGR          /* Include File Manager APIs */
  3984.   #define INCL_DOSMEMMGR           /* Includes Memory Management APIs */
  3985.   #define INCL_DOSERRORS           /* DOS Error values */
  3986.   #include  os2.h>
  3987.   #include  stdio.h>
  3988.   #include  string.h>
  3989.   #define SIXTY_FOUR_K 0x10000
  3990.   #define ONE_MEG     0x100000
  3991.   #define TEN_MEG     10*ONE_MEG
  3992.  
  3993.   #define UNC_DISK1  "\\\\.\\Physical_Disk1"
  3994.   #define UNC_DISK2  "\\\\.\\Physical_Disk2"
  3995.  
  3996.   int main(void) {
  3997.      HFILE  hfDisk1        = 0;      /* Handle for disk #1 */
  3998.      HFILE  hfDisk2        = 0;      /* Handle for disk #2 */
  3999.      ULONG  ulAction       = 0;      /* Action taken by DosOpen */
  4000.      ULONG  cbRead         = 0;      /* Bytes to read */
  4001.      ULONG  cbActualRead   = 0;      /* Bytes read by DosRead */
  4002.      ULONG  cbWrite        = 0;      /* Bytes to write */
  4003.      ULONG  ulLocation     = 0;
  4004.      ULONG  cbActualWrote  = 0;      /* Bytes written by DosWrite */
  4005.      UCHAR  uchFileName1[20]  = UNC_DISK1, /* UNC Name of disk 1 */
  4006.             uchFileName2[20]  = UNC_DISK2; /* UNC Name of disk 2 */
  4007.      PBYTE  pBuffer        = 0;
  4008.      ULONG  cbTotal        = 0;
  4009.  
  4010.      APIRET rc             = NO_ERROR;            /* Return code */
  4011.  
  4012.      /* Open a raw file system disk #1 for reading */
  4013.      rc = DosOpen(uchFileName1,               /* File name */
  4014.                    hfDisk1,                   /* File handle */
  4015.                    ulAction,                  /* Action taken by DosOpen */
  4016.                   0L,                         /* no file size */
  4017.                   FILE_NORMAL,                /* File attribute */
  4018.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  4019.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  4020.                   OPEN_ACCESS_READONLY,
  4021.                   0L);                        /* No extented attributes */
  4022.      if (rc != NO_ERROR) {
  4023.         printf("DosOpen error rc = %u\n", rc);
  4024.         return(1);
  4025.      } /* endif */
  4026.  
  4027.      /* Set the pointer to the begining of the disk */
  4028.      rc = DosSetFilePtr(hfDisk1,      /* Handle for disk 1 */
  4029.                         0L,           /* Offset must be multiple of 512 */
  4030.                         FILE_BEGIN,   /* Begin of the disk */
  4031.                          ulLocation); /* New pointer location */
  4032.      if (rc != NO_ERROR) {
  4033.         printf("DosSetFilePtr error rc = %u\n", rc);
  4034.         return(1);
  4035.      } /* endif */
  4036.  
  4037.      /* Open a raw file system disk #2 for writing */
  4038.      rc = DosOpen(uchFileName2,               /* File name */
  4039.                    hfDisk2,                   /* File handle */
  4040.                    ulAction,                  /* Action taken by DosOpen */
  4041.                   0L,                         /* no file size */
  4042.                   FILE_NORMAL,                /* File attribute */
  4043.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  4044.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  4045.                   OPEN_ACCESS_READWRITE,
  4046.                   0L);                        /* No extented attributes */
  4047.      if (rc != NO_ERROR) {
  4048.         printf("DosOpen error rc = %u\n", rc);
  4049.         return(1);
  4050.      } /* endif */
  4051.  
  4052.      /* Set the pointer to the begining of the disk */
  4053.      rc = DosSetFilePtr(hfDisk2,      /* Handle for disk 1 */
  4054.                         0L,           /* Offset must be multiple of 512 */
  4055.                         FILE_BEGIN,   /* Begin of the disk */
  4056.                          ulLocation); /* New pointer location */
  4057.      if (rc != NO_ERROR) {
  4058.         printf("DosSetFilePtr error rc = %u\n", rc);
  4059.         return(1);
  4060.      } /* endif */
  4061.  
  4062.  
  4063.      /* Allocate 64K of memory for transfer operations */
  4064.      rc = DosAllocMem((PPVOID) pBuffer, /* Pointer to buffer */
  4065.                        SIXTY_FOUR_K,      /* Buffer size */
  4066.                        PAG_COMMIT |     /* Allocation flags */
  4067.                        PAG_READ |
  4068.                        PAG_WRITE);
  4069.      if (rc != NO_ERROR) {
  4070.         printf("DosAllocMem error rc = %u\n", rc);
  4071.         return(1);
  4072.      } /* endif */
  4073.  
  4074.      cbRead = SIXTY_FOUR_K;
  4075.      while (rc == NO_ERROR    cbTotal   TEN_MEG) {
  4076.  
  4077.         /* Read from #1 */
  4078.         rc = DosRead(hfDisk1,         /* Handle for disk 1 */
  4079.                      pBuffer,         /* Pointer to buffer */
  4080.                      cbRead,          /* Size must be multiple of 512 */
  4081.                       cbActualRead);  /* Actual read by DosOpen */
  4082.         if (rc) {
  4083.            printf("DosRead error  return code = %u\n", rc);
  4084.            return 1;
  4085.         }
  4086.  
  4087.         /* Write to disk #2 */
  4088.         cbWrite = cbActualRead;
  4089.         rc = DosWrite(hfDisk2,         /* Handle for disk 2 */
  4090.                       pBuffer,         /* Pointer to buffer */
  4091.                       cbWrite,         /* Size must be multiple of 512 */
  4092.                        cbActualWrote); /* Actual written by DosOpen */
  4093.         if (rc) {
  4094.            printf("DosWrite error  return code = %u\n", rc);
  4095.            return 1;
  4096.         }
  4097.         if (cbActualRead != cbActualWrote) {
  4098.            printf("Bytes read (%u) does not equal bytes written (%u)\n",
  4099.                   cbActualRead, cbActualWrote);
  4100.            return 1;
  4101.         }
  4102.         cbTotal += cbActualRead; /* Update total transferred */
  4103.      }
  4104.  
  4105.      printf("Transfer successfully %d bytes from disk #1 to disk #2.\n",
  4106.             cbTotal);
  4107.  
  4108.      /* Free allocated memmory */
  4109.      rc = DosFreeMem(pBuffer);
  4110.      if (rc != NO_ERROR) {
  4111.         printf("DosFreeMem error  return code = %u\n", rc);
  4112.         return 1;
  4113.      }
  4114.  
  4115.      rc = DosClose(hfDisk1);
  4116.      if (rc != NO_ERROR) {
  4117.         printf("DosClose error  return code = %u\n", rc);
  4118.         return 1;
  4119.      }
  4120.  
  4121.      rc = DosClose(hfDisk2);
  4122.      if (rc != NO_ERROR) {
  4123.         printf("DosClose error  return code = %u\n", rc);
  4124.         return 1;
  4125.   return NO_ERROR;
  4126.   }
  4127.  
  4128.  
  4129. ΓòÉΓòÉΓòÉ 5.14. DosOpenL ΓòÉΓòÉΓòÉ
  4130.  
  4131. Purpose 
  4132.  
  4133. DosOpenL opens a new file, an existing file, or a replacement for an existing 
  4134. file. An open file can have extended attributes. 
  4135.  
  4136. Syntax 
  4137.  
  4138. #define INCL DOSFILEMGR
  4139. #include  os2.h
  4140.  
  4141.  APIRET DosOpenL (PSZ pszFileName, PHFILE pHf, PULONG pulAction, LONGLONG 
  4142.            cbFile, ULONG ulAttribute, ULONG fsOpenFlags, ULONG fsOpenMode, 
  4143.            PEAOP2 peaop2) 
  4144.  
  4145.  Parameters 
  4146.  
  4147.  pszFileName  PSZ)  input 
  4148.            Address of the ASCIIZ path name of the file or device to be opened. 
  4149.  
  4150.  pHf  PHFILE)  output 
  4151.            Address of the handle for the file. 
  4152.  
  4153.  pulAction  PULONG)  output 
  4154.            Address of the variable that receives the value that specifies the 
  4155.            action taken by the DosOpenL function. 
  4156.  
  4157.            If DosOpenL fails, this value has no meaning. Otherwise, it is one 
  4158.            of the following values 
  4159.  
  4160.            1        FILE_EXISTED 
  4161.  
  4162.                     File already existed. 
  4163.  
  4164.            2        FILE_CREATED 
  4165.  
  4166.                     File was created. 
  4167.  
  4168.            3        FILE_TRUNCATED 
  4169.  
  4170.                     File existed and was changed to a given size (file was 
  4171.                     replaced). 
  4172.  
  4173.  cbFile  LONGLONG)  input 
  4174.            New logical size of the file (end of data, EOD), in bytes. 
  4175.  
  4176.            This parameter is significant only when creating a new file or 
  4177.            replacing an existing one. Otherwise, it is ignored. It is an error 
  4178.            to create or replace a file with a nonzero length if the fsOpenMode 
  4179.            Access-Mode flag is set to read-only. 
  4180.  
  4181.  ulAttribute  ULONG)  input 
  4182.            File attribute information. 
  4183.  
  4184.            Possible values are 
  4185.  
  4186.            Bits           Description 
  4187.  
  4188.            31 6           Reserved, must be 0. 
  4189.  
  4190.            5              FILE_ARCHIVED (0x00000020) 
  4191.  
  4192.                           File has been archived. 
  4193.  
  4194.            4              FILE_DIRECTORY (0x00000010) 
  4195.  
  4196.                           File is a subdirectory. 
  4197.  
  4198.            3              Reserved, must be 0. 
  4199.  
  4200.            2              FILE_SYSTEM (0x00000004) 
  4201.  
  4202.                           File is a system file. 
  4203.  
  4204.            1              FILE_HIDDEN (0x00000002) 
  4205.  
  4206.                           File is hidden and does not appear in a directory 
  4207.                           listing. 
  4208.  
  4209.            0              FILE_READONLY (0x00000001) 
  4210.  
  4211.                           File can be read from, but not written to. 
  4212.  
  4213.            0              FILE_NORMAL (0x00000000) 
  4214.  
  4215.                           File can be read from or written to. 
  4216.  
  4217.            File attributes apply only if the file is created. 
  4218.  
  4219.            These bits may be set individually or in combination. For example, 
  4220.            an attribute value of 0x00000021 (bits 5 and 0 set to 1) indicates a 
  4221.            read-only file that has been archived. 
  4222.  
  4223.  fsOpenFlags  ULONG)  input 
  4224.            The action to be taken depending on whether the file exists or does 
  4225.            not exist. 
  4226.  
  4227.            Possible values are 
  4228.  
  4229.            Bits           Description 
  4230.  
  4231.            31 8           Reserved, must be 0. 
  4232.  
  4233.            7 4            The following flags apply if the file does not exist 
  4234.  
  4235.                           0000       OPEN_ACTION_FAIL_IF_NEW 
  4236.  
  4237.                                      Open an existing file; fail if the file 
  4238.                                      does not exist. 
  4239.  
  4240.                           0001       OPEN_ACTION_CREATE_IF_NEW 
  4241.  
  4242.                                      Create the file if the file does not 
  4243.                                      exist. 
  4244.  
  4245.            3 0            The following flags apply if the file already exists 
  4246.  
  4247.                           0000       OPEN_ACTION_FAIL_IF_EXISTS 
  4248.  
  4249.                                      Open the file; fail if the file already 
  4250.                                      exists. 
  4251.  
  4252.                           0001       OPEN_ACTION_OPEN_IF_EXISTS 
  4253.  
  4254.                                      Open the file if it already exists. 
  4255.  
  4256.                           0010       OPEN_ACTION_REPLACE_IF_EXISTS 
  4257.  
  4258.                                      Replace the file if it already exists. 
  4259.  
  4260.  fsOpenMode  ULONG)  input 
  4261.            The mode of the open function. Possible values are 
  4262.  
  4263.            Bits           Description 
  4264.  
  4265.            31 16          Reserved, must be zero. 
  4266.  
  4267.            15             OPEN_FLAGS_DASD (0x00008000) 
  4268.  
  4269.                           Direct Open flag 
  4270.  
  4271.                           0        pszFileName represents a file to be opened 
  4272.                                    normally. 
  4273.  
  4274.                           1        pszFileName is  drive  (such as c  or a ), 
  4275.                                    and represents a mounted disk or diskette 
  4276.                                    volume to be opened for direct access. 
  4277.  
  4278.            14             OPEN_FLAGS_WRITE_THROUGH (0x00004000) 
  4279.  
  4280.                           Write-Through flag 
  4281.  
  4282.                           0        Writes to the file may go through the 
  4283.                                    file-system driver s cache. The file-system 
  4284.                                    driver writes the sectors when the cache is 
  4285.                                    full or the file is closed. 
  4286.  
  4287.                           1        Writes to the file may go through the 
  4288.                                    file-system driver s cache, but the sectors 
  4289.                                    are written (the actual file I/O operation 
  4290.                                    is completed) before a synchronous write 
  4291.                                    call returns. This state of the file defines 
  4292.                                    it as a synchronous file. For synchronous 
  4293.                                    files, this bit must be set, because the 
  4294.                                    data must be written to the medium for 
  4295.                                    synchronous write operations. 
  4296.  
  4297.                           This bit flag is not inherited by child processes. 
  4298.  
  4299.            13             OPEN_FLAGS_FAIL_ON_ERROR (0x00002000) 
  4300.  
  4301.                           Fail-Errors flag. Media I/O errors are handled as 
  4302.                           follows 
  4303.  
  4304.                           0        Reported through the system critical-error 
  4305.                                    handler. 
  4306.  
  4307.                           1        Reported directly to the caller by way of a 
  4308.                                    return code. 
  4309.  
  4310.                           Media I/O errors generated through Category 08h 
  4311.                           Logical Disk Control IOCtl Commands always get 
  4312.                           reported directly to the caller by way of return 
  4313.                           code. The Fail-Errors function applies only to 
  4314.                           non-IOCtl handle-based file I/O calls. 
  4315.  
  4316.                           This flag bit is not inherited by child processes. 
  4317.  
  4318.            12             OPEN_FLAGS_NO_CACHE (0x00001000) 
  4319.  
  4320.                           No-Cache Cache flag 
  4321.  
  4322.                           0        The file-system driver should place data 
  4323.                                    from I/O operations into its cache. 
  4324.  
  4325.                           1        I/O operations to the file need not be done 
  4326.                                    through the file-system driver s cache. 
  4327.  
  4328.                           The setting of this bit determines whether 
  4329.                           file-system drivers should place data into the cache. 
  4330.                           Like the write-through bit, this is a per-handle bit, 
  4331.                           and is not inherited by child processes. 
  4332.  
  4333.            11             Reserved; must be 0. 
  4334.  
  4335.            10 8           The locality of reference flags contain information 
  4336.                           about how the application is to get access to the 
  4337.                           file. The values are as follows 
  4338.  
  4339.                           000       OPEN_FLAGS_NO_LOCALITY (0x00000000) 
  4340.  
  4341.                                     No locality known. 
  4342.  
  4343.                           001       OPEN_FLAGS_SEQUENTIAL (0x00000100) 
  4344.  
  4345.                                     Mainly sequential access. 
  4346.  
  4347.                           010       OPEN_FLAGS_RANDOM (0x00000200) 
  4348.  
  4349.                                     Mainly random access. 
  4350.  
  4351.                           011       OPEN_FLAGS_RANDOMSEQUENTIAL (0x00000300) 
  4352.  
  4353.                                     Random with some locality. 
  4354.  
  4355.            7              OPEN_FLAGS_NOINHERIT (0x00000080) 
  4356.  
  4357.                           Inheritance flag 
  4358.  
  4359.                           0        File handle is inherited by a process 
  4360.                                    created from a call to DosExecPgm. 
  4361.  
  4362.                           1        File handle is private to the current 
  4363.                                    process. 
  4364.  
  4365.                           This bit is not inherited by child processes. 
  4366.  
  4367.            6 4            Sharing Mode flags. This field defines any 
  4368.                           restrictions to file access placed by the caller on 
  4369.                           other processes. The values are as follows 
  4370.  
  4371.                           001       OPEN_SHARE_DENYREADWRITE (0x00000010) 
  4372.  
  4373.                                     Deny read write access. 
  4374.  
  4375.                           010       OPEN_SHARE_DENYWRITE (0x00000020) 
  4376.  
  4377.                                     Deny write access. 
  4378.  
  4379.                           011       OPEN_SHARE_DENYREAD (0x00000030) 
  4380.  
  4381.                                     Deny read access. 
  4382.  
  4383.                           100       OPEN_SHARE_DENYNONE (0x00000040) 
  4384.  
  4385.                                     Deny neither read nor write access (deny 
  4386.                                     none). 
  4387.  
  4388.                           Any other value is invalid. 
  4389.  
  4390.            29             OPEN_SHARE_DENYLEGACY (0x10000000) 
  4391.  
  4392.                           Deny read/write access by the DosOpen command. 
  4393.  
  4394.                           0        Allow read/write access by the DosOpen 
  4395.                                    command. 
  4396.  
  4397.                           1        Deny read/write access by the DosOpen 
  4398.                                    command. 
  4399.  
  4400.                                    A file opened by DosOpenL will not be 
  4401.                                    allowed to grow larger  than 2GB while that 
  4402.                                    same file is open with a legacy DosOpen 
  4403.                                    call.  Setting this bit to 1 will prevent 
  4404.                                    access by the obsolete DosOpen      API and 
  4405.                                    ensure that no error will occur when growing 
  4406.                                    the file. 
  4407.  
  4408.                           Any other value is invalid. 
  4409.  
  4410.            3              Reserved; must be 0. 
  4411.  
  4412.            2 0            Access-Mode flags. This field defines the file access 
  4413.                           required by the caller. The values are as follows 
  4414.  
  4415.                           000       OPEN_ACCESS_READONLY (0x00000000) 
  4416.  
  4417.                                     Read-only access 
  4418.  
  4419.                           001       OPEN_ACCESS_WRITEONLY (0x00000001) 
  4420.  
  4421.                                     Write-only access 
  4422.  
  4423.                           010       OPEN_ACCESS_READWRITE (0x00000002) 
  4424.  
  4425.                                     Read/write access. 
  4426.  
  4427.                           Any other value is invalid, as are any other 
  4428.                           combinations. 
  4429.  
  4430.            File sharing requires the cooperation of sharing processes. This 
  4431.            cooperation is communicated through sharing and access modes. Any 
  4432.            sharing restrictions placed on a file opened by a process are 
  4433.            removed when the process closes the file with a DosClose request. 
  4434.  
  4435.            Sharing Mode 
  4436.                     Specifies the type of file access that other processes may 
  4437.                     have. For example, if other processes can continue to read 
  4438.                     the file while your process is operating on it, specify 
  4439.                     Deny Write. The sharing mode prevents other processes from 
  4440.                     writing to the file but still allows them to read it. 
  4441.  
  4442.            Access Mode 
  4443.                     Specifies the type of file access (access mode) needed by 
  4444.                     your process. For example, if your process requires 
  4445.                     read/write access, and another process has already opened 
  4446.                     the file with a sharing mode of Deny None, your DosOpenL 
  4447.                     request succeeds. However, if the file is open with a 
  4448.                     sharing mode of Deny Write, the process is denied access. 
  4449.  
  4450.                     If the file is inherited by a child process, all sharing 
  4451.                     and access restrictions also are inherited. 
  4452.  
  4453.                     If an open file handle is duplicated by a call to 
  4454.                     DosDupHandle, all sharing and access restrictions also are 
  4455.                     duplicated. 
  4456.  
  4457.  peaop2  PEAOP2)  in/out 
  4458.            Extended attributes. 
  4459.  
  4460.            This parameter is used only to specify extended attributes (EAs) 
  4461.            when creating a new file, replacing an existing file, or truncating 
  4462.            an existing file. When opening existing files, it should be set to 
  4463.            null. 
  4464.  
  4465.            Input        The address of the extended-attribute buffer, which 
  4466.                         contains an EAOP2 structure. fpFEA2List points to a 
  4467.                         data area where the relevant FEA2 list is to be found. 
  4468.                         fpGEA2List and oError are ignored. 
  4469.  
  4470.            Output       fpGEA2List and fpFEA2List are unchanged. The area that 
  4471.                         fpFEA2List points to is unchanged. If an error occurred 
  4472.                         during the set, oError is the offset of the FEA2 entry 
  4473.                         where the error occurred. The return code from DosOpenL 
  4474.                         is the error code for that error condition. If no error 
  4475.                         occurred, oError is undefined. 
  4476.  
  4477.                         If peaop2 is zero, then no extended attributes are 
  4478.                         defined for the file. 
  4479.  
  4480.                         If extended attributes are not to be defined or 
  4481.                         modified, the pointer peaop2 must be set to zero. 
  4482.  
  4483.  Returns 
  4484.  
  4485.  ulrc  APIRET)  returns 
  4486.            Return Code. 
  4487.  
  4488.            DosOpenL returns one of the following values 
  4489.  
  4490.            0              NO_ERROR 
  4491.  
  4492.            2              ERROR_FILE_NOT_FOUND 
  4493.  
  4494.            3              ERROR_PATH_NOT_FOUND 
  4495.  
  4496.            4              ERROR_TOO_MANY_OPEN_FILES 
  4497.  
  4498.            5              ERROR_ACCESS_DENIED 
  4499.  
  4500.            12             ERROR_INVALID_ACCESS 
  4501.  
  4502.            26             ERROR_NOT_DOS_DISK 
  4503.  
  4504.            32             ERROR_SHARING_VIOLATION 
  4505.  
  4506.            36             ERROR_SHARING_BUFFER_EXCEEDED 
  4507.  
  4508.            82             ERROR_CANNOT_MAKE 
  4509.  
  4510.            87             ERROR_INVALID_PARAMETER 
  4511.  
  4512.            99             ERROR_DEVICE_IN_USE 
  4513.  
  4514.            108            ERROR_DRIVE_LOCKED 
  4515.  
  4516.            110            ERROR_OPEN_FAILED 
  4517.  
  4518.            112            ERROR_DISK_FULL 
  4519.  
  4520.            206            ERROR_FILENAME_EXCED_RANGE 
  4521.  
  4522.            231            ERROR_PIPE_BUSY 
  4523.  
  4524.  Remarks 
  4525.  
  4526.  A successful DosOpenL request returns a handle for accessing the file. The 
  4527.  read/write pointer is set at the first byte of the file. The position of the 
  4528.  pointer can be changed with DosSetFilePtrL or by read and write operations on 
  4529.  the file. 
  4530.  
  4531.  The file s date and time can be queried with DosQueryFileInfo. They are set 
  4532.  with DosSetFileInfo. 
  4533.  
  4534.  The read-only attribute of a file can be set with the ATTRIB command. 
  4535.  
  4536.  ulAttribute cannot be set to Volume Label. To set volume label information, 
  4537.  issue DosSetFSInfo with a logical drive number. Volume labels cannot be 
  4538.  opened. 
  4539.  
  4540.  cbFile affects the size of the file only when the file is new or is a 
  4541.  replacement. If an existing file is opened, cbFile is ignored. To change the 
  4542.  size of the existing file, issue DosSetFileSizeL. 
  4543.  
  4544.  The value in cbFile is a recommended size. If the full size cannot be 
  4545.  allocated, the open request may still succeed. The file system makes a 
  4546.  reasonable attempt to allocate the new size in an area that is as nearly 
  4547.  contiguous as possible on the medium. When the file size is extended, the 
  4548.  values of the new bytes are undefined. 
  4549.  
  4550.  The Direct Open bit provides direct access to an entire disk or diskette 
  4551.  volume, independent of the file system. This mode of opening the volume that 
  4552.  is currently on the drive returns a handle to the calling function; the handle 
  4553.  represents the logical volume as a single file.  The calling function 
  4554.  specifies this handle with a DosDevIOCtl Category 8, DSK_LOCKDRIVE request to 
  4555.  prevent other processes from accessing the logical volume. When you are 
  4556.  finished using the logical volume, issue a DosDevIOCtl Category 8, 
  4557.  DSK_UNLOCKDRIVE request to allow other processes to access the logical volume. 
  4558.  
  4559.  The file-handle state bits can be set by DosOpenL and DosSetFHState. An 
  4560.  application can query the file-handle state bits, as well as the rest of the 
  4561.  Open Mode field, by issuing DosQueryFHState. 
  4562.  
  4563.  You can use an EAOP2 structure to set extended attributes in peaop2 when 
  4564.  creating a file, replacing an existing file, or truncating an existing file. 
  4565.  No extended attributes are set when an existing file is just opened. 
  4566.  
  4567.  A replacement operation is logically equivalent to atomically deleting and 
  4568.  re-creating the file. This means that any extended attributes associated with 
  4569.  the file also are deleted before the file is re-created. 
  4570.  
  4571.  Related Functions 
  4572.  
  4573.      DosClose 
  4574.  
  4575.      DosDevIOCtl 
  4576.  
  4577.      DosDupHandle 
  4578.  
  4579.      DosQueryHType 
  4580.  
  4581.      DosSetFileInfo 
  4582.  
  4583.      DosSetFilePtrL 
  4584.  
  4585.      DosSetFileSizeL 
  4586.  
  4587.      DosSetMaxFH 
  4588.  
  4589.      DosSetRelMaxFH 
  4590.  
  4591.  Example Code 
  4592.  
  4593.  This example opens or creates and opens a normal file named  DOSTEST.DAT , 
  4594.  writes to it, reads from it, and finally closes it. 
  4595.  
  4596.   #define INCL_DOSFILEMGR          /* File Manager values */
  4597.   #define INCL_DOSERRORS           /* DOS Error values    */
  4598.   #include  os2.h
  4599.   #include  stdio.h
  4600.   #include  string.h
  4601.  
  4602.   int main(void)
  4603.   HFILE  hfFileHandle   = 0L;     /* Handle for file being manipulated */
  4604.   ULONG  ulAction       = 0;      /* Action taken by DosOpenL */
  4605.   ULONG  ulBytesRead    = 0;      /* Number of bytes read by DosRead */
  4606.   ULONG  ulWrote        = 0;      /* Number of bytes written by DosWrite */
  4607.   LONGLONG  ullLocal    = 0;      /* File pointer position after DosSetFilePtrL */
  4608.   UCHAR  uchFileName 20   = "dostest.dat",     /* Name of file */
  4609.   uchFileData 100  = " ";               /* Data to write to file */
  4610.   APIRET rc             = NO_ERROR;            /* Return code */
  4611.  
  4612.   /* Open the file test.dat.  Use an existing file or create a new */
  4613.   /* one if it doesn't exist.                                      */
  4614.   rc = DosOpenL(uchFileName,                    /* File path name */
  4615.    hfFileHandle,                  /* File handle */
  4616.    ulAction,                      /* Action taken */
  4617.   (LONGLONG)100,                    /* File primary allocation */
  4618.   FILE_ARCHIVED | FILE_NORMAL,    /* File attribute */
  4619.   OPEN_ACTION_CREATE_IF_NEW |
  4620.   OPEN_ACTION_OPEN_IF_EXISTS,     /* Open function type */
  4621.   OPEN_FLAGS_NOINHERIT |
  4622.   OPEN_SHARE_DENYNONE  |
  4623.   OPEN_ACCESS_READWRITE,          /* Open mode of the file */
  4624.   0L);                            /* No extended attribute */
  4625.  
  4626.   if (rc != NO_ERROR)
  4627.   printf("DosOpenL error  return code = %u\n", rc);
  4628.   return 1;
  4629.     else
  4630.   printf ("DosOpenL  Action taken = %ld\n", ulAction);
  4631.     /* endif *//* Write a string to the file */
  4632.   strcpy (uchFileData, "testing...\n1...\n2...\n3\n");
  4633.  
  4634.   rc = DosWrite (hfFileHandle,                /* File handle */
  4635.   (PVOID) uchFileData,         /* String to be written */
  4636.   sizeof (uchFileData),        /* Size of string to be written */
  4637.    ulWrote);                   /* Bytes actually written */
  4638.  
  4639.   if (rc != NO_ERROR)
  4640.   printf("DosWrite error  return code = %u\n", rc);
  4641.   return 1;
  4642.     else
  4643.   printf ("DosWrite  Bytes written = %u\n", ulWrote);
  4644.     /* endif */
  4645.  
  4646.   /* Move the file pointer back to the beginning of the file */
  4647.   rc = DosSetFilePtrL (hfFileHandle,           /* File Handle */
  4648.   (LONGLONG)0,            /* Offset */
  4649.   FILE_BEGIN,             /* Move from BOF */
  4650.    ullLocal);             /* New location address */
  4651.   if (rc != NO_ERROR)
  4652.   printf("DosSetFilePtrL error  return code = %u\n", rc);
  4653.   return 1;
  4654.  
  4655.  
  4656.   /* Read the first 100 bytes of the file */
  4657.   rc = DosRead (hfFileHandle,                /* File Handle */
  4658.   uchFileData,                 /* String to be read */
  4659.   100L,                        /* Length of string to be read */
  4660.    ulBytesRead);               /* Bytes actually read */
  4661.  
  4662.   if (rc != NO_ERROR)
  4663.   printf("DosRead error  return code = %u\n", rc);
  4664.   return 1;
  4665.     else
  4666.   printf ("DosRead  Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
  4667.     /* endif */
  4668.  
  4669.   rc = DosClose(hfFileHandle);                /* Close the file */
  4670.  
  4671.   if (rc != NO_ERROR)
  4672.   printf("DosClose error  return code = %u\n", rc);
  4673.   return 1;
  4674.  
  4675.   return NO_ERROR;
  4676.  
  4677.  
  4678. ΓòÉΓòÉΓòÉ 5.15. DosPerfSysCall ΓòÉΓòÉΓòÉ
  4679.  
  4680. Purpose 
  4681.  
  4682. DosPerfSysCall retrieves system performance information and performs software 
  4683. tracing. 
  4684.  
  4685. Syntax 
  4686.  
  4687. #define INCL_BASE
  4688. #include  os2.h>
  4689.  
  4690.  APIRET DosPerfSysCall (ULONG ulCommand, ULONG ulParm1, ULONG ulParm1,ULONG 
  4691.            ulParm2, ULONG ulParm3) 
  4692.  
  4693.  Parameters 
  4694.  
  4695.  ulCommand (ULONG)  input 
  4696.            Accepts following commands 
  4697.  
  4698.            CMD_KI_RDCNT 0x63 Reads CPU utilization information in both 
  4699.                           uniprocessor and symmetric multi-processor (SMP) 
  4700.                           environments by taking a snapshot of the time stamp 
  4701.                           counters. To determine CPU utilization, the 
  4702.                           application must compute the difference between  two 
  4703.                           time stamp snapshots using 64 bit aritimetic. See the 
  4704.                           example code for details. 
  4705.  
  4706.            CMD_SOFTTRACE_LOG0x14 Records software trace information. 
  4707.  
  4708.  ulParm1 (ULONG)  input/output 
  4709.  
  4710.            CMD_KI_RDCNT   Pointer to CPUUTIL structure 
  4711.  
  4712.                           ulParm1 would be set to the address of the CPUUTIL 
  4713.                           structure. 
  4714.  
  4715.                           ulParm2and ulParm3are not used and should be set to 
  4716.                           zero. 
  4717.  
  4718.            CMD_SOFTTRACE_LOG Major code for the trace entry in the range of 0 
  4719.                           to 255. Major codes 184 (0x00b8) and 185 (0x00b9) 
  4720.                           have been reserved for customer use. Major code 1 is 
  4721.                           reserved for exclusive use by IBM(R). 
  4722.  
  4723.  ulParm2 (ULONG)  input/output 
  4724.  
  4725.            CMD_KI_RDCNT   0 (reserved) 
  4726.  
  4727.            CMD_SOFTTRACE_LOG Minor code for the trace entry in the range of 0 
  4728.                           to 255. 
  4729.  
  4730.  ulParm3 (ULONG)  input/output 
  4731.  
  4732.            CMD_KI_RDCNT   0 (reserved) 
  4733.  
  4734.            CMD_SOFTTRACE_LOG Pointer to a HOOKDATA data structure. 
  4735.  
  4736.  Returns 
  4737.  
  4738.  ulrc (APIRET)  returns 
  4739.            Return Code. 
  4740.  
  4741.            DosPerfSysCall returns one of the following values 
  4742.  
  4743.            0              NO_ERROR 
  4744.  
  4745.            1              ERROR_INVALID_FUNCTION 
  4746.  
  4747.  Remarks 
  4748.  
  4749.  DosPerfSysCall is a general purpose performance function. This function 
  4750.  accepts four parameters. The first parameter is the command requested. The 
  4751.  other three parameters are command specific. 
  4752.  
  4753.  Some functions of DosPerfSysCall may have a dependency on Intel Pentium or 
  4754.  Pentium-Pro support. If a function cannot be provided because OS/2 is not 
  4755.  running on a processor with the required features, a return code will indicate 
  4756.  an attempt to use an unsupported function. 
  4757.  
  4758.  Example Code 
  4759.  
  4760.  This example uses DosPerfSysCall to obtain CPU utilization information. 
  4761.  
  4762.   #define INCL_BASE
  4763.   #include  os2.h>
  4764.   #include  stdio.h>
  4765.   #include  stdlib.h>
  4766.   #include  string.h>
  4767.   #include  perfutil.h>
  4768.  
  4769.   #define LL2F (high, low) (4294967296.0* (high) + (low)
  4770.  
  4771.   void main (int argc, char *argv[])
  4772.   {
  4773.  
  4774.      APIRET   rc;
  4775.      int      i, iter, sleep_sec;
  4776.      double   ts_val, idle_val_prev;
  4777.      double   idle_val, busy_val_prev;
  4778.      double   busy_val, busy_val_prev;
  4779.      dobule   intr_val intr_val_prev;
  4780.      CPUUTIL  CPUUtil;
  4781.  
  4782.      if ((argc   2) || (*aargv[1]   '1') || (*aargv[1] > '9')) {
  4783.        fprintf(stderr, "usage  %s [1-9]\n", argv[0]);
  4784.        exit(0);
  4785.      }
  4786.      sleep_sec = *argv[1] - '0';
  4787.  
  4788.      iter = 0;
  4789.      do {
  4790.        rec = DosPerfSysCall (CMD_KI_RDCNT, (ULONG)  CPUUtil,0,0);
  4791.        if (rc) {
  4792.           fprintf (stderr, "CMD_KI_RDCNT failed rc = %d\n", rc);
  4793.           exit(1);
  4794.        }
  4795.        ts_val = LL2F (CPUUtil.ulTimeHigh, CPUUtil.ulTimeLow);
  4796.        idle_val = LL2f (CPUUtil.ulIdleHigh, CPUUtil.ulIdleLow);
  4797.        busy_val = LL2F (CPUUtil.ulBusyHigh, CPUUtil.ulBusyLow);
  4798.        intr_val = LL2F (CPUUtil.ulIntrHigh, CPUUtil.ulIntrLow);
  4799.  
  4800.        if (iter > 0) {
  4801.           double ts_delta = ts_val - ts_val_prev;
  4802.           printf ("idle  %4.2%% busy  %4.2f%% intr  %4.2f%%\n";
  4803.              (idle_val - idle_val_prev/ts_delta*100.0,
  4804.              (busy_val - busy_val_prev/ts_delta*100.0,
  4805.              (intr_val - intr_val_prev/ts_delta*100.0);
  4806.        }
  4807.        ts_val_prev = ts_val;
  4808.        idle_val_prev = idle_val;
  4809.        busy_val_prev = busy_val;
  4810.        intr_val_prev = intr_val;
  4811.  
  4812.        iter++;
  4813.        DosSleep(1000*sleep_sec);
  4814.  
  4815.      } while (1);
  4816.   }
  4817.  
  4818.  This example performs software tracing from a program in ring 3. 
  4819.  
  4820.   #define INCL_BASE
  4821.   #include  os2.h>
  4822.   #include  stdio.h>
  4823.   #include  stdlib.h>
  4824.   #include  string.h>
  4825.   #include  perfutil.h>
  4826.  
  4827.   int main (int argc, char *argv[])
  4828.   {
  4829.      APIRET     rc;
  4830.      BYTE       HookBuffer [256];
  4831.      HOOKDATA   Hookdata = {0,HookBuffer};
  4832.      ULONG      ulMajor, ulMinor;
  4833.      *((PULONG)  HookBuffer[0]) = 1;
  4834.      *((PULONG)  HookBuffer[4]) = 2;
  4835.      *((PULONG)  HookBuffer[8]) = 3;
  4836.      strcpy((PSZ  HookBuffer[12], "Test of 3 ULONG values and a string.")
  4837.      HookData.ulLength = 12 + strlen((PSZ HookBuffer[12]) + 1;
  4838.  
  4839.      ulMajor = 0x00b8
  4840.      ulMinor = 0x0001
  4841.  
  4842.      rc = DosPerfSystCall(CMD_SOFTTRACE_LOG, ulMajor, ulMinor, (ULONG)  HookData);
  4843.      if (rc != NO_ERROR) {
  4844.        fprintf (stderr, "CMD_SOFTTRACE_LOG failed   rc = %u\n", rc);
  4845.        return 1;
  4846.        }
  4847.  
  4848.      return NO_ERROR;
  4849.   }
  4850.  
  4851.  
  4852. ΓòÉΓòÉΓòÉ 5.16. DosProtectOpenL ΓòÉΓòÉΓòÉ
  4853.  
  4854. Purpose 
  4855.  
  4856. DosProtectOpenL opens a new file, an existing file, or a replacement for an 
  4857. existing file and returns a protected file handle. An open file can have 
  4858. extended attributes. 
  4859.  
  4860. Syntax 
  4861.  
  4862. #define INCL DOSFILEMGR
  4863. #include  os2.h
  4864.  
  4865.  APIRET DosProtectOpenL (PSZ pszFileName, PHFILE phf, PULONG pulAction, 
  4866.            LONGLONG cbFile, ULONG ulAttribute, ULONG fsOpenFlags, ULONG 
  4867.            fsOpenMode, PEAOP2 peaop2, PFHLOCK pfhFileHandleLockID) 
  4868.  
  4869.  Parameters 
  4870.  
  4871.  pszFileName  PSZ)  input 
  4872.            Address of the ASCIIZ path name of the file or device to be opened. 
  4873.  
  4874.  phf  PHFILE)  output 
  4875.            Address of the handle for the file. 
  4876.  
  4877.  pulAction  PULONG)  output 
  4878.            A pointer to the ULONG in which the value that specifies the action 
  4879.            taken by DosProtectOpenL is returned. 
  4880.  
  4881.            If DosProtectOpenL fails, this value has no meaning.  Otherwise, it 
  4882.            is one of the following values 
  4883.  
  4884.            1        FILE_EXISTED 
  4885.  
  4886.                     File already existed. 
  4887.  
  4888.            2        FILE_CREATED 
  4889.  
  4890.                     File was created. 
  4891.  
  4892.            3        FILE_TRUNCATED 
  4893.  
  4894.                     File existed and was changed to a given size (file was 
  4895.                     replaced). 
  4896.  
  4897.  cbFile  LONGLONG)  input 
  4898.            New logical size of the file (end of data, EOD), in bytes. 
  4899.  
  4900.            This parameter is significant only when creating a new file or 
  4901.            replacing an existing one. Otherwise, it is ignored. It is an error 
  4902.            to create or replace a file with a nonzero length if the fsOpenMode 
  4903.            Access-Mode flag is set to read-only. 
  4904.  
  4905.  ulAttribute  ULONG)  input 
  4906.            File attributes. 
  4907.  
  4908.            This parameter contains the following bit fields 
  4909.  
  4910.            Bits           Description 
  4911.  
  4912.            31 6           Reserved, must be 0. 
  4913.  
  4914.            5              FILE_ARCHIVED (0x00000020) 
  4915.  
  4916.                           File has been archived. 
  4917.  
  4918.            4              FILE_DIRECTORY (0x00000010) 
  4919.  
  4920.                           File is a subdirectory. 
  4921.  
  4922.            3              Reserved, must be 0. 
  4923.  
  4924.            2              FILE_SYSTEM (0x00000004) 
  4925.  
  4926.                           File is a system file. 
  4927.  
  4928.            1              FILE_HIDDEN (0x00000002) 
  4929.  
  4930.                           File is hidden and does not appear in a directory 
  4931.                           listing. 
  4932.  
  4933.            0              FILE_READONLY (0x00000001) 
  4934.  
  4935.                           File can be read from, but not written to. 
  4936.  
  4937.            0              FILE_NORMAL (0x00000000) 
  4938.  
  4939.                           File can be read from or written to. 
  4940.  
  4941.            File attributes apply only if the file is created. 
  4942.  
  4943.            These bits may be set individually or in combination. For example, 
  4944.            an attribute value of 0x00000021 (bits 5 and 0 set to 1) indicates a 
  4945.            read-only file that has been archived. 
  4946.  
  4947.  fsOpenFlags  ULONG)  input 
  4948.            The action to be taken depending on whether the file exists or does 
  4949.            not exist. 
  4950.  
  4951.            This parameter contains the following bit fields 
  4952.  
  4953.            Bits           Description 
  4954.  
  4955.            31 8           Reserved, must be 0. 
  4956.  
  4957.            7 4            The following flags apply if the file does not exist 
  4958.  
  4959.                           0000       OPEN_ACTION_FAIL_IF_NEW 
  4960.  
  4961.                                      Open an existing file; fail if the file 
  4962.                                      does not exist. 
  4963.  
  4964.                           0001       OPEN_ACTION_CREATE_IF_NEW 
  4965.  
  4966.                                      Create the file if the file does not 
  4967.                                      exist. 
  4968.  
  4969.            3 0            The following flags apply if the file does not exist 
  4970.  
  4971.                           0000       OPEN_ACTION_FAIL_IF_EXISTS 
  4972.  
  4973.                                      Open the file; fail if the file already 
  4974.                                      exists. 
  4975.  
  4976.                           0001       OPEN_ACTION_OPEN_IF_EXISTS 
  4977.  
  4978.                                      Open the file if it already exists. 
  4979.  
  4980.                           0010       OPEN_ACTION_REPLACE_IF_EXISTS 
  4981.  
  4982.                                      Replace the file if it already exists. 
  4983.  
  4984.  fsOpenMode  ULONG)  input 
  4985.            The mode of the open function. 
  4986.  
  4987.            This parameter contains the following bit fields 
  4988.  
  4989.            Bits           Description 
  4990.  
  4991.            29 16          Reserved, must be zero. 
  4992.  
  4993.            30             OPEN_FLAGS_PROTECTED_HANDLE (0x40000000) 
  4994.  
  4995.                           Protected file handle flag. 
  4996.  
  4997.                           0        Unprotected Handle 
  4998.  
  4999.                           1        Protected Handle 
  5000.  
  5001.                           Protected handle requires the pfhFileHandleLockID to 
  5002.                           be specified on subsequent DosProtectxxxx calls. 
  5003.  
  5004.                           Unprotected handle requires the pfhFileHandleLockID 
  5005.                           value to be specified as zero on subsequent 
  5006.                           DosProtectxxxx calls. An unprotected handle may be 
  5007.                           used with the unprotected calls such as DosRead and 
  5008.                           DosWrite. 
  5009.  
  5010.            31             Reserved, must be zero. 
  5011.  
  5012.            15             OPEN_FLAGS_DASD (x00008000) 
  5013.  
  5014.                           Direct Open flag 
  5015.  
  5016.                           0        pszFileName represents a file to be opened 
  5017.                                    normally. 
  5018.  
  5019.                           1        pszFileName is  drive  (such as C  or A ), 
  5020.                                    and represents a mounted disk or diskette 
  5021.                                    volume to be opened for direct access. 
  5022.  
  5023.            14             OPEN_FLAGS_WRITE_THROUGH (0x00004000) 
  5024.  
  5025.                           Write-Through flag 
  5026.  
  5027.                           0        Writes to the file may go through the 
  5028.                                    file-system driver s cache. The file-system 
  5029.                                    driver writes the sectors when the cache is 
  5030.                                    full or the file is closed. 
  5031.  
  5032.                           1        Writes to the file may go through the 
  5033.                                    file-system driver s cache, but the sectors 
  5034.                                    are written  the actual file I O operation 
  5035.                                    is completed) before a synchronous write 
  5036.                                    call returns. This state of the file defines 
  5037.                                    it as a synchronous file. For synchronous 
  5038.                                    files, this bit must be set, because the 
  5039.                                    data must be written to the medium for 
  5040.                                    synchronous write operations. 
  5041.  
  5042.                           This bit flag is not inherited by child processes. 
  5043.  
  5044.            13             OPEN_FLAGS_FAIL_ON_ERROR (0x00002000) 
  5045.  
  5046.                           Fail-Errors flag. Media I O errors are handled as 
  5047.                           follows 
  5048.  
  5049.                           0        Reported through the system critical-error 
  5050.                                    handler. 
  5051.  
  5052.                           1        Reported directly to the caller by way of a 
  5053.                                    return code. 
  5054.  
  5055.                           Media I/O errors generated through Category 08h 
  5056.                           Logical Disk Control IOCtl Commands always get 
  5057.                           reported directly to the caller by way of return 
  5058.                           code. The Fail-Errors function applies only to 
  5059.                           non-IOCtl handle-based file I/O calls. 
  5060.  
  5061.                           This flag bit is not inherited by child processes. 
  5062.  
  5063.            12             OPEN_FLAGS_NO_CACHE (0x00001000) 
  5064.  
  5065.                           No-Cache/Cache flag 
  5066.  
  5067.                           0        The file-system driver should place data 
  5068.                                    from I O operations into its cache. 
  5069.  
  5070.                           1        I/O operations to the file need not be done 
  5071.                                    through the file-system driver s cache. 
  5072.  
  5073.                           The setting of this bit determines whether 
  5074.                           file-system drivers should place data into the cache. 
  5075.                           Like the write-through bit, this is a per-handle bit, 
  5076.                           and is not inherited by child processes. 
  5077.  
  5078.            11             Reserved; must be 0. 
  5079.  
  5080.            10 8           The locality of reference flags contain information 
  5081.                           about how the application is to get access to the 
  5082.                           file. The values are as follows 
  5083.  
  5084.                           000        OPEN_FLAGS_NO_LOCALITY (0x00000000) 
  5085.  
  5086.                                      No locality known. 
  5087.  
  5088.                           001        OPEN_FLAGS_SEQUENTIAL (0x00000100) 
  5089.  
  5090.                                      Mainly sequential access. 
  5091.  
  5092.                           010        OPEN_FLAGS_RANDOM (0x00000200) 
  5093.  
  5094.                                      Mainly random access. 
  5095.  
  5096.                           011        OPEN_FLAGS_RANDOMSEQUENTIAL (0x00000300) 
  5097.  
  5098.                                      Random with some locality. 
  5099.  
  5100.            7              OPEN_FLAGS_NOINHERIT (0x00000080) 
  5101.  
  5102.                           Inheritance flag 
  5103.  
  5104.                           0        File handle is inherited by a process 
  5105.                                    created from a call to DosExecPgm. 
  5106.  
  5107.                           1        File handle is private to the current 
  5108.                                    process. 
  5109.  
  5110.                           This bit is not inherited by child processes. 
  5111.  
  5112.            6 4            Sharing Mode flags. This field defines any 
  5113.                           restrictions to file access placed by the caller on 
  5114.                           other processes. The values are as follows 
  5115.  
  5116.                           001        OPEN_SHARE_DENYREADWRITE (0x00000010) 
  5117.  
  5118.                                      Deny read write access. 
  5119.  
  5120.                           010        OPEN_SHARE_DENYWRITE (0x00000020) 
  5121.  
  5122.                                      Deny write access. 
  5123.  
  5124.                           011        OPEN_SHARE_DENYREAD (0x00000030) 
  5125.  
  5126.                                      Deny read access. 
  5127.  
  5128.                           100        OPEN_SHARE_DENYNONE (0x00000040) 
  5129.  
  5130.                                      Deny neither read nor write access (deny 
  5131.                                      none). 
  5132.  
  5133.            29             OPEN_SHARE_DENYLEGACY (0x10000000) 
  5134.  
  5135.                           Deny read/write access by the DosOpen command 
  5136.  
  5137.                           0        Allow read/write access by the DosOpen 
  5138.                                    command. 
  5139.  
  5140.                           1        Deny read/write access by the DosOpen 
  5141.                                    command. 
  5142.  
  5143.                                    A file opened by DosOpenL will not be 
  5144.                                    allowed to grow larger  than 2GB while that 
  5145.                                    same file is open via a legacy DosOpen call. 
  5146.                                    Setting this bit to 1 will prevent access by 
  5147.                                    the obsolete DosOpen      API and ensure 
  5148.                                    that no error will occur when growing the 
  5149.                                    file. 
  5150.  
  5151.                           Any other value is invalid. 
  5152.  
  5153.            3              Reserved; must be 0. 
  5154.  
  5155.            2 0            Access-Mode flags. This field defines the file access 
  5156.                           required by the caller. The values are as follows 
  5157.  
  5158.                           000        OPEN_ACCESS_READONLY (0x00000000) 
  5159.  
  5160.                                      Read-only access 
  5161.  
  5162.                           001        OPEN_ACCESS_WRITEONLY (0x00000001) 
  5163.  
  5164.                                      Write-only access 
  5165.  
  5166.                           010        OPEN_ACCESS_READWRITE (0x00000002) 
  5167.  
  5168.                                      Read/write access. 
  5169.  
  5170.                           Any other value is invalid, as are any other 
  5171.                           combinations. 
  5172.  
  5173.            File sharing requires the cooperation of sharing processes. This 
  5174.            cooperation is communicated through sharing and access modes. Any 
  5175.            sharing restrictions placed on a file opened by a process are 
  5176.            removed when the process closes the file with a DosClose request. 
  5177.  
  5178.            Sharing Mode 
  5179.                     Specifies the type of file access that other processes may 
  5180.                     have. For example, if other processes can continue to read 
  5181.                     the file while your process is operating on it, specify 
  5182.                     Deny Write. The sharing mode prevents other processes from 
  5183.                     writing to the file but still allows them to read it. 
  5184.  
  5185.            Access Mode 
  5186.                     Specifies the type of file access (access mode) needed by 
  5187.                     your process. For example, if your process requires 
  5188.                     read/write access, and another process has already opened 
  5189.                     the file with a sharing mode of Deny None, your 
  5190.                     DosProtectOpenL request succeeds. However, if the file is 
  5191.                     open with a sharing mode of Deny Write, the process is 
  5192.                     denied access. 
  5193.  
  5194.                     If the file is inherited by a child process, all sharing 
  5195.                     and access restrictions also are inherited. 
  5196.  
  5197.                     If an open file handle is duplicated by a call to 
  5198.                     DosDupHandle, all sharing and access restrictions also are 
  5199.                     duplicated. 
  5200.  
  5201.  peaop2  PEAOP2)  in/out 
  5202.            A pointer to an extended attribute buffer. 
  5203.  
  5204.            Input        The address of the extended-attribute buffer, which 
  5205.                         contains an EAOP2 structure. The fpFEA2List field in 
  5206.                         the EAOP2 structure points to a data area where the 
  5207.                         relevant FEA2 list is to be found. The fpGEA2List and 
  5208.                         oError fields are ignored. 
  5209.  
  5210.            Output       fpGEA2List and fpFEA2List are unchanged. The area that 
  5211.                         fpFEA2List points to is unchanged. If an error occurred 
  5212.                         during the set, oError is the offset of the FEA2 entry 
  5213.                         where the error occurred. The return code from 
  5214.                         DosProtectOpenL is the error code for that error 
  5215.                         condition. If no error occurred, oError is undefined. 
  5216.  
  5217.            If peaop2 is zero, then no extended attributes are defined for the 
  5218.            file. If extended attributes are not to be defined or modified, the 
  5219.            pointer peaop2 must be set to zero. 
  5220.  
  5221.  pfhFileHandleLockID  PFHLOCK)  output 
  5222.            The address of the 32-bit lockid for the file handle. 
  5223.  
  5224.  Returns 
  5225.  
  5226.  ulrc  APIRET)  returns 
  5227.            Return Code. 
  5228.  
  5229.            DosProtectOpenL returns one of the following values 
  5230.  
  5231.            0              NO_ERROR 
  5232.  
  5233.            2              ERROR_FILE_NOT_FOUND 
  5234.  
  5235.            3              ERROR_PATH_NOT_FOUND 
  5236.  
  5237.            4              ERROR_TOO_MANY_OPEN_FILES 
  5238.  
  5239.            5              ERROR_ACCESS_DENIED 
  5240.  
  5241.            12             ERROR_INVALID_ACCESS 
  5242.  
  5243.            26             ERROR_NOT_DOS_DISK 
  5244.  
  5245.            32             ERROR_SHARING_VIOLATION 
  5246.  
  5247.            36             ERROR_SHARING_BUFFER_EXCEEDED 
  5248.  
  5249.            82             ERROR_CANNOT_MAKE 
  5250.  
  5251.            87             ERROR_INVALID_PARAMETER 
  5252.  
  5253.            99             ERROR_DEVICE_IN_USE 
  5254.  
  5255.            108            ERROR_DRIVE_LOCKED 
  5256.  
  5257.            110            ERROR_OPEN_FAILED 
  5258.  
  5259.            112            ERROR_DISK_FULL 
  5260.  
  5261.            206            ERROR_FILENAME_EXCED_RANGE 
  5262.  
  5263.            231            ERROR_PIPE_BUSY 
  5264.  
  5265.  Remarks 
  5266.  
  5267.  A successful DosProtectOpenL request returns a handle and a 32-bit lockid for 
  5268.  accessing the file. The read/write pointer is set at the first byte of the 
  5269.  file. The position of the pointer can be changed with DosProtectSetFilePtrL or 
  5270.  by read and write operations on the file. 
  5271.  
  5272.  The file s date and time can be queried with DosProtectQueryFileInfo. They are 
  5273.  set with DosProtectSetFileInfo. 
  5274.  
  5275.  The read-only attribute of a file can be set with the ATTRIB command. 
  5276.  
  5277.  ulAttribute cannot be set to Volume Label. To set volume-label information, 
  5278.  issue DosProtectSetFileInfo with a logical drive number.  Volume labels cannot 
  5279.  be opened. 
  5280.  
  5281.  cbFile affects the size of the file only when the file is new or is a 
  5282.  replacement. If an existing file is opened, cbFile is ignored. To change the 
  5283.  size of the existing file, issue DosProtectSetFileSizeL. 
  5284.  
  5285.  The value in cbFile is a recommended size. If the full size cannot be 
  5286.  allocated, the open request may still succeed.  The file system makes a 
  5287.  reasonable attempt to allocate the new size in an area that is as nearly 
  5288.  contiguous as possible on the medium. When the file size is extended, the 
  5289.  values of the new bytes are undefined. 
  5290.  
  5291.  The Direct Open bit provides direct access to an entire disk or diskette 
  5292.  volume, independent of the file system. This mode of opening the volume that 
  5293.  is currently on the drive returns a handle to the calling function; the handle 
  5294.  represents the logical volume as a single file. The calling function specifies 
  5295.  this handle with a DosDevIOCtl Category 8, DSK_LOCKDRIVE request to prevent 
  5296.  other processes from accessing the logical volume. When you are finished using 
  5297.  the logical volume, issue a DosDevIOCtl Category 8, DSK_UNLOCKDRIVE request to 
  5298.  allow other processes to access the logical volume. 
  5299.  
  5300.  The file-handle state bits can be set by DosProtectOpenL and 
  5301.  DosProtectSetFHState. An application can query the file-handle state bits, as 
  5302.  well as the rest of the Open Mode field, by issuing DosProtectQueryFHState. 
  5303.  
  5304.  You can use an EAOP2 structure to set extended attributes in peaop2 when 
  5305.  creating a file, replacing an existing file, or truncating an existing file. 
  5306.  No extended attributes are set when an existing file is just opened. 
  5307.  
  5308.  A replacement operation is logically equivalent to atomically deleting and 
  5309.  re-creating the file. This means that any extended attributes associated with 
  5310.  the file also are deleted before the file is re-created. 
  5311.  
  5312.  The pfhFileHandleLockID returned is required on each of the DosProtectxxx 
  5313.  functions. An incorrect pfhFileHandleLockID on subsequent DosProtectxxx calls 
  5314.  results in an ERROR_ACCESS_DENIED return code. 
  5315.  
  5316.  The DosProtectxxx functions can be used with a NULL filehandle lockid, if the 
  5317.  subject filehandle was obtained from DosOpen. 
  5318.  
  5319.  Related Functions 
  5320.  
  5321.      DosDevIOCtl 
  5322.  
  5323.      DosDupHandle 
  5324.  
  5325.      DosProtectClose 
  5326.  
  5327.      DosProtectSetFileInfo 
  5328.  
  5329.      DosProtectSetFilePtrL 
  5330.  
  5331.      DosProtectSetFileSizeL 
  5332.  
  5333.      DosQueryHType 
  5334.  
  5335.      DosSetMaxFH 
  5336.  
  5337.      DosSetRelMaxFH 
  5338.  
  5339.  Example Code 
  5340.  
  5341.  This example opens or creates and opens a file named  DOSPROT.DAT , writes to 
  5342.  it, reads from it, and finally closes it using DosProtect functions. 
  5343.  
  5344.   #define INCL_DOSFILEMGR          /* File Manager values */
  5345.   #define INCL_DOSERRORS           /* DOS Error values    */
  5346.   #include  os2.h
  5347.   #include  stdio.h
  5348.   #include  string.h
  5349.  
  5350.   int main(VOID)
  5351.   HFILE  hfFileHandle   = 0L;
  5352.   ULONG  ulAction       = 0;
  5353.   ULONG  ulBytesRead    = 0;
  5354.   ULONG  ulWrote        = 0;
  5355.   LONGLONG  ullLocal    = 0;
  5356.   UCHAR  uchFileName 20   = "dosprot.dat",
  5357.   uchFileData 100  = " ";
  5358.   FHLOCK FileHandleLock = 0;        /* File handle lock   */
  5359.   APIRET rc             = NO_ERROR; /* Return code */
  5360.  
  5361.   /* Open the file dosprot.dat.  Make it read/write, open it */
  5362.   /* if it already exists and create it if it is new.     */
  5363.   rc = DosProtectOpenL(uchFileName,             /* File path name          */
  5364.    hfFileHandle,                  /* File handle             */
  5365.    ulAction,                      /* Action taken            */
  5366.   (LONGLONG)100,                      /* File primary allocation */
  5367.   FILE_ARCHIVED | FILE_NORMAL,    /* File attribute          */
  5368.   OPEN_ACTION_CREATE_IF_NEW |
  5369.   OPEN_ACTION_OPEN_IF_EXISTS,     /* Open function type      */
  5370.   OPEN_FLAGS_NOINHERIT |
  5371.   OPEN_SHARE_DENYNONE  |
  5372.   OPEN_ACCESS_READWRITE,          /* Open mode of the file   */
  5373.   0L,                             /* No extended attribute   */
  5374.    FileHandleLock);               /* File handle lock id     */
  5375.   if (rc != NO_ERROR)
  5376.   printf("DosProtectOpenL error  return code = %u\n", rc);
  5377.   return 1;
  5378.     else
  5379.   printf ("DosProtectOpenL  Action taken = %u\n", ulAction);
  5380.     /* endif */
  5381.  
  5382.   /* Write a string to the file */
  5383.   strcpy (uchFileData, "testing...\n3...\n2...\n1\n");
  5384.  
  5385.   rc = DosProtectWrite (hfFileHandle,       /* File handle                  */
  5386.   (PVOID) uchFileData,       /* String to be written         */
  5387.   sizeof (uchFileData),      /* Size of string to be written */
  5388.    ulWrote,                  /* Bytes actually written       */
  5389.   FileHandleLock);           /* File handle lock id          */if (rc != NO_ERROR)
  5390.   printf("DosProtectWrite error  return code = %u\n", rc);
  5391.   return 1;
  5392.     else
  5393.   printf ("DosProtectWrite  Bytes written = %u\n", ulWrote);
  5394.     /* endif */
  5395.  
  5396.   /* Move the file pointer back to the beginning of the file */
  5397.   rc = DosProtectSetFilePtrL (hfFileHandle,    /* File Handle          */
  5398.   (LONGLONG)0,            /* Offset               */
  5399.   FILE_BEGIN,             /* Move from BOF        */
  5400.    ullLocal,               /* New location address */
  5401.   FileHandleLock);        /* File handle lock id  */
  5402.   if (rc != NO_ERROR)
  5403.   printf("DosSetFilePtrL error  return code = %u\n", rc);
  5404.   return 1;
  5405.  
  5406.  
  5407.   /* Read the first 100 bytes of the file */
  5408.   rc = DosProtectRead (hfFileHandle,         /* File Handle                 */
  5409.   uchFileData,                 /* String to be read           */
  5410.   100L,                        /* Length of string to be read */
  5411.    ulBytesRead,                /* Bytes actually read         */
  5412.   FileHandleLock);             /* File handle lock id         */
  5413.   if (rc != NO_ERROR)
  5414.   printf("DosProtectRead error  return code = %u\n", rc);
  5415.   return 1;
  5416.     else
  5417.   printf("DosProtectRead  Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
  5418.     /* endif */
  5419.  
  5420.   rc = DosProtectClose(hfFileHandle, FileHandleLock);   /* Close the file */
  5421.   if (rc != NO_ERROR)
  5422.   printf("DosProtectClose error  return code = %u\n", rc);
  5423.   return 1;
  5424.  
  5425.   return NO_ERROR;
  5426.  
  5427.  
  5428. ΓòÉΓòÉΓòÉ 5.17. DosProtectQueryFileInfo ΓòÉΓòÉΓòÉ
  5429.  
  5430. Purpose 
  5431.  
  5432. DosProtectQueryFileInfo gets file information. 
  5433.  
  5434. Syntax 
  5435.  
  5436. #define INCL DOSFILEMGR
  5437. #include  os2.h
  5438.  
  5439.  APIRET DosProtectQueryFileInfo (HFILE hf, ULONG ulInfoLevel, PVOID pInfo, 
  5440.            ULONG cbInfoBuf, FHLOCK fhFileHandleLockID) 
  5441.  
  5442.  Parameters 
  5443.  
  5444.  hf  HFILE)  input 
  5445.            File handle. 
  5446.  
  5447.  ulInfoLevel  ULONG)  input 
  5448.            Level of file information required. 
  5449.  
  5450.            Specify a value 
  5451.  
  5452.            1        FIL_STANDARD 
  5453.  
  5454.                     Level 1 file information 
  5455.  
  5456.            11       FIL_STANDARDL 
  5457.  
  5458.                     Level 11 file information 
  5459.  
  5460.            2        FIL_QUERYEASIZE 
  5461.  
  5462.                     Level 2 file information 
  5463.  
  5464.            12       FIL_QUERYEASIZEL 
  5465.  
  5466.                     Level 12 file information 
  5467.  
  5468.            3        FIL_QUERYEASFROMLIST 
  5469.  
  5470.                     Level 3 file information 
  5471.  
  5472.            The structures described in pInfo indicate the information returned 
  5473.            for each of these levels. 
  5474.  
  5475.  pInfo  PVOID)  output 
  5476.            Address of the storage area where the system returns the requested 
  5477.            level of file information. 
  5478.  
  5479.            File information, where applicable, is at least as accurate as the 
  5480.            most recent DosProtectClose, DosResetBuffer, DosProtectSetFileInfo, 
  5481.            or DosSetPathInfo. 
  5482.  
  5483.            Level 1 File Information (ulInfoLevel == FIL_STANDARD) 
  5484.                     pInfo contains the FILESTATUS3 data structure, to which 
  5485.                     file information is returned. 
  5486.  
  5487.            Level 11 File Information (ulInfoLevel == FIL_STANDARDL) 
  5488.                     pInfo contains the FILESTATUS3L data structure, to which 
  5489.                     file information is returned. 
  5490.  
  5491.            Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) 
  5492.                     pInfo contains the FILESTATUS4 data structure. This is 
  5493.                     similar to the Level 1 structure, with the addition of the 
  5494.                     cbList field after the attrFile field. 
  5495.  
  5496.                     The cbList field is an ULONG. On output, this field 
  5497.                     contains the size, in bytes, of the file s entire extended 
  5498.                     attribute (EA) set on disk. You can use this value to 
  5499.                     calculate the size of the buffer required to hold the EA 
  5500.                     information returned when a value of 3 is specified for 
  5501.                     ulInfoLevel. The buffer size is less than or equal to twice 
  5502.                     the size of the file s entire EA set on disk. 
  5503.  
  5504.            Level 12 File Information (ulInfoLevel == FIL_QUERYEASIZEL) 
  5505.                     pInfo contains the FILESTATUS4L data structure. This is 
  5506.                     similar to the Level 11 structure, with the addition of the 
  5507.                     cbList field after the attrFile field. 
  5508.  
  5509.                     The cbList field is an ULONG. On output, this field 
  5510.                     contains the size, in bytes, of the file s entire extended 
  5511.                     attribute (EA) set on disk. You can use this value to 
  5512.                     calculate the size of the buffer required to hold the EA 
  5513.                     information returned when a value of 3 is specified for 
  5514.                     ulInfoLevel. The buffer size is less than or equal to twice 
  5515.                     the size of the file s entire EA set on disk. 
  5516.  
  5517.            Level 3 File Information (ulInfoLevel == FIL_QUERYEASFROMLIST) 
  5518.  
  5519.                     Input        pInfo contains an EAOP2 data structure. 
  5520.                                  fpGEA2List points to a GEA2 list defining the 
  5521.                                  attribute names whose values are returned. The 
  5522.                                  GEA2 data structures must be aligned on a 
  5523.                                  doubleword boundary. Each oNextEntryOffset 
  5524.                                  field must contain the number of bytes from 
  5525.                                  the beginning of the current entry to the 
  5526.                                  beginning of the next entry in the GEA2 list. 
  5527.                                  The oNextEntryOffset field in the last entry 
  5528.                                  of the GEA2 list must be zero. fpFEA2List 
  5529.                                  points to a data area where the relevant FEA2 
  5530.                                  list is returned. The length field of this 
  5531.                                  FEA2 list is valid, giving the size of the 
  5532.                                  FEA2 list buffer. oError is ignored. 
  5533.  
  5534.                     Output       pInfo is unchanged. The buffer pointed to by 
  5535.                                  fpFEA2List is filled in with the returned 
  5536.                                  information. If the buffer that fpFEA2List 
  5537.                                  points to is not large enough to hold the 
  5538.                                  returned information (the return code is 
  5539.                                  ERROR_BUFFER_OVERFLOW), cbList is still valid, 
  5540.                                  assuming there is at least enough space for 
  5541.                                  it. Its value is the size of the entire EA set 
  5542.                                  on disk for the file, even though only a 
  5543.                                  subset of attributes was requested. 
  5544.  
  5545.  cbInfoBuf  ULONG)  input 
  5546.            The length, in bytes, of pInfo. 
  5547.  
  5548.  fhFileHandleLockID  FHLOCK)  input 
  5549.            The filehandle lockid returned by a previous DosProtectOpenL. 
  5550.  
  5551.  Returns 
  5552.  
  5553.  ulrc (APIRET)  returns 
  5554.            Return Code. 
  5555.  
  5556.            DosProtectQueryFile returns one of the following values 
  5557.  
  5558.            0              NO_ERROR 
  5559.  
  5560.            5              ERROR_ACCESS_DENIED 
  5561.  
  5562.            6              ERROR_INVALID_HANDLE 
  5563.  
  5564.            111            ERROR_BUFFER_OVERFLOW 
  5565.  
  5566.            124            ERROR_INVALID_LEVEL 
  5567.  
  5568.            130            ERROR_DIRECT_ACCESS_HANDLE 
  5569.  
  5570.            254            ERROR_INVALID_EA_NAME 
  5571.  
  5572.            255            ERROR_EA_LIST_INCONSISTENT 
  5573.  
  5574.  Remarks 
  5575.  
  5576.  In the FAT file system, only date and time information contained in level-1 
  5577.  file information can be modified. Zero is returned for the creation and access 
  5578.  dates and times. 
  5579.  
  5580.  To return information contained in any of the file information levels, 
  5581.  DosProtectQueryFileInfo must be able to read the open file. 
  5582.  DosProtectQueryFileInfo works only when the file is opened for read access, 
  5583.  with a deny-write sharing mode specified for access by other processes. If 
  5584.  another process that has specified conflicting sharing and access modes has 
  5585.  already opened the file, any call to DosProtectOpen will fail. 
  5586.  
  5587.  DosProtectEnumAttribute returns the lengths of extended attributes. This 
  5588.  information can be used to calculate what size pInfo needs to be to hold 
  5589.  full-extended-attribute (FEA) information returned by DosProtectQueryFileInfo 
  5590.  when Level 3 is specified. The size of the buffer is calculated as follows 
  5591.  
  5592.       Four bytes (for oNextEntryOffset) + 
  5593.       One byte (for fEA) + 
  5594.       One byte (for cbName) + 
  5595.       Two bytes (for cbValue) + 
  5596.       Value of cbName (for the name of the EA) + 
  5597.       One byte (for terminating NULL in cbName) + 
  5598.       Value of cbValue (for the value of the EA) 
  5599.  
  5600.  Related Functions 
  5601.  
  5602.      DosProtectClose 
  5603.  
  5604.      DosProtectOpenL 
  5605.  
  5606.      DosProtectEnumAttribute 
  5607.  
  5608.      DosProtectSetFileInfo 
  5609.  
  5610.      DosQueryPathInfo 
  5611.  
  5612.      DosResetBuffer 
  5613.  
  5614.      DosProtectSetFileSizeL 
  5615.  
  5616.      DosSetPathInfo 
  5617.  
  5618.  Example Code 
  5619.  
  5620.  This example creates a read-only file named  DOSFDEL.DAT , then changes the 
  5621.  file attributes to normal, and uses DosForceDelete to delete the file so that 
  5622.  it can not be restored using UNDELETE. 
  5623.  
  5624.   #define INCL_DOSFILEMGR   /* File Manager values */
  5625.   #define INCL_DOSERRORS    /* DOS error values    */
  5626.   #include  os2.h
  5627.   #include  stdio.h
  5628.  
  5629.   int main(VOID)
  5630.  
  5631.   UCHAR       uchFileName     = "DOSFDEL.DAT";   /* File to delete    */
  5632.   HFILE       fhDelFile       = 0;               /* File handle from DosOpenL  */
  5633.   FILESTATUS3L fsts3FileInfo   =   0  ;  /* Information associated with file   */
  5634.   ULONG       ulBufferSize    = sizeof(FILESTATUS3L); /* File info buffer size */
  5635.   ULONG       ulOpenAction    = 0;                 /* Action taken by DosOpenL */
  5636.   APIRET      rc              = NO_ERROR;          /* Return code             */
  5637.   FHLOCK      FHLock          = 0;                 /* File handle lock        */
  5638.  
  5639.   /* Create a read-only file */
  5640.  
  5641.   rc = DosProtectOpenL(uchFileName,  fhDelFile,
  5642.    ulOpenAction, (longlong)10, FILE_READONLY,
  5643.   OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
  5644.   OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE, 0L,  FHLock);
  5645.   if (rc != NO_ERROR)
  5646.   printf("DosProtectOpenL error  return code = %u\n", rc);
  5647.   return 1;
  5648.  
  5649.  
  5650.   rc = DosProtectQueryFileInfo(fhDelFile, FIL_STANDARDL,
  5651.    fsts3FileInfo, ulBufferSize, FHLock);   /* Get standard info */
  5652.   if (rc != NO_ERROR)
  5653.   printf("DosProtectQueryFileInfo error  return code = %u\n", rc);
  5654.   return 1;
  5655.     else   printf("File %s created read-only.\n",uchFileName);
  5656.  
  5657.   /*   Change the file attributes to be "normal"  */
  5658.  
  5659.   fsts3FileInfo.attrFile  = FILE_NORMAL;
  5660.   rc = DosProtectSetFileInfo(fhDelFile, FIL_STANDARDL,
  5661.    fsts3FileInfo, ulBufferSize, FHLock);
  5662.   if (rc != NO_ERROR)
  5663.   printf("DosProtectSetFileInfo error  return code = %u\n", rc);
  5664.   return 1;
  5665.  
  5666.   rc = DosProtectClose(fhDelFile, FHLock);
  5667.   /* Should verify that (rc != NO_ERROR) here... *//* Delete the file */
  5668.  
  5669.   rc = DosForceDelete(uchFileName);
  5670.   if (rc != NO_ERROR)
  5671.   printf("DosForceDelete error  return code = %u\n", rc);
  5672.   return 1;
  5673.     else
  5674.   printf("File %s has been deleted.\n",uchFileName);
  5675.      /* endif */
  5676.  
  5677.   return NO_ERROR;
  5678.  
  5679.  
  5680. ΓòÉΓòÉΓòÉ 5.18. DosProtectSetFileInfo ΓòÉΓòÉΓòÉ
  5681.  
  5682. Purpose 
  5683.  
  5684. DosProtectSetFileInfo sets file information. 
  5685.  
  5686. Syntax 
  5687.  
  5688. #define INCL DOSFILEMGR
  5689. #include   os2.h
  5690.  
  5691.  APIRET DosProtectSetFileInfo (HFILE hf, ULONG ulInfoLevel, PVOID pInfoBuf, 
  5692.            ULONG cbInfoBuf, FHLOCK fhFileHandleLockID) 
  5693.  
  5694.  Parameters 
  5695.  
  5696.  hf  HFILE)  input 
  5697.            File handle. 
  5698.  
  5699.  ulInfoLevel  ULONG)  input 
  5700.            Level of file information being set. 
  5701.  
  5702.            Specify a value 
  5703.  
  5704.            1        FIL_STANDARD 
  5705.  
  5706.                     Level 1 file information 
  5707.  
  5708.            11       FIL_STANDARDL 
  5709.  
  5710.                     Level 11 file information 
  5711.  
  5712.            2        FIL_QUERYEASIZE 
  5713.  
  5714.                     Level 2 file information 
  5715.  
  5716.            The structures described in pInfoBuf indicate the information being 
  5717.            set for each of these levels. 
  5718.  
  5719.  pInfoBuf  PVOID)  input 
  5720.            Address of the storage area containing the structures for file 
  5721.            information levels. 
  5722.  
  5723.            Level 1 File Information (ulInfoLevel == FIL_STANDARD) 
  5724.                    pInfoBuf contains the FILESTATUS3 data structure. 
  5725.  
  5726.            Level 11 File Information (ulInfoLevel == FIL_STANDARDL) 
  5727.                    pInfo contains the FILESTATUS3L data structure, to which 
  5728.                    file information is returned. 
  5729.  
  5730.            Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) 
  5731.                    pInfoBuf contains an EAOP2 data structure. 
  5732.  
  5733.                    Level 2 sets a series of EA name/value pairs. On input, 
  5734.                    pInfoBuf is an EAOP2 data structure. fpGEA2List is ignored. 
  5735.                    fpFEA2List points to a data area where the relevant is an 
  5736.                    FEA2 list is to be found. oError is ignored. 
  5737.  
  5738.                    On output, fpGEA2List and fpFEA2List are unchanged. The area 
  5739.                    pointed to by fpFEA2List is unchanged. If an error occurred 
  5740.                    during the set, oError is the offset of the FEA2 where the 
  5741.                    error occurred. The return code is the error code 
  5742.                    corresponding to the condition generating the error. If no 
  5743.                    error occurred, oError is undefined. 
  5744.  
  5745.  cbInfoBuf  ULONG)  input 
  5746.            The length, in bytes, of pInfoBuf. 
  5747.  
  5748.  fhFileHandleLockID  FHLOCK)  input 
  5749.            The filehandle lockid obtained from DosProtectOpen. 
  5750.  
  5751.  Returns 
  5752.  
  5753.  ulrc  APIRET)  returns 
  5754.            Return Code. 
  5755.  
  5756.            DosProtectSetFileInfo returns one of the following values 
  5757.  
  5758.            0              NO_ERROR 
  5759.  
  5760.            1              ERROR_INVALID_FUNCTION 
  5761.  
  5762.            5              ERROR_ACCESS_DENIED 
  5763.  
  5764.            6              ERROR_INVALID_HANDLE 
  5765.  
  5766.            87             ERROR_INVALID_PARAMETER 
  5767.  
  5768.            122            ERROR_INSUFFICIENT_BUFFER 
  5769.  
  5770.            124            ERROR_INVALID_LEVEL 
  5771.  
  5772.            130            ERROR_DIRECT_ACCESS_HANDLE 
  5773.  
  5774.            254            ERROR_INVALID_EA_NAME 
  5775.  
  5776.            255            ERROR_EA_LIST_INCONSISTENT 
  5777.  
  5778.  Remarks 
  5779.  
  5780.  DosProtectSetFileInfo is successful only when the file is opened for write 
  5781.  access, and access by other processes is prevented by a deny-both sharing 
  5782.  mode. If the file is already opened with conflicting sharing rights, any call 
  5783.  to DosProtectOpen will fail. 
  5784.  
  5785.  A value of 0 in the date and time components of a field does not change the 
  5786.  field. For example, if both  last write date  and  last write time  are 
  5787.  specified as 0 in the Level 1 information structure, then both attributes of 
  5788.  the file are left unchanged. If either  last write date  or  last write time 
  5789.  are other than 0, both attributes of the file are set to the new values. 
  5790.  
  5791.  In the FAT file system, only the dates and times of the last write can be 
  5792.  modified. Creation and last-access dates and times are not affected. 
  5793.  
  5794.  The last-modification date and time will be changed if the extended attributes 
  5795.  are modified. 
  5796.  
  5797.  Related Functions 
  5798.  
  5799.      DosProtectClose 
  5800.  
  5801.      DosProtectEnumAttribute 
  5802.  
  5803.      DosProtectOpen 
  5804.  
  5805.      DosProtectQueryFileInfo 
  5806.  
  5807.      DosQueryPathInfo 
  5808.  
  5809.      DosResetBuffer 
  5810.  
  5811.      DosSetFileSize 
  5812.  
  5813.      DosSetPathInfo 
  5814.  
  5815.  Example Code 
  5816.  
  5817.  This example creates a read-only file named  DOSFDEL.DAT , then changes its 
  5818.  attributes to normal file, and finally uses DosForceDelete to delete the file 
  5819.  so that it cannot be restored using UNDELETE. 
  5820.  
  5821.   #define INCL_DOSFILEMGR   /* File Manager values */
  5822.   #define INCL_DOSERRORS    /* DOS error values    */
  5823.   #include  os2.h
  5824.   #include  stdio.h
  5825.  
  5826.   int main(VOID)
  5827.  
  5828.   UCHAR       uchFileName     = "DOSFDEL.DAT";   /* File to delete    */
  5829.   HFILE       fhDelFile       = 0;               /* File handle from DosOpenL  */
  5830.   FILESTATUS3L fsts3FileInfo   =   0  ;  /* Information associated with file   */
  5831.   ULONG       ulBufferSize    = sizeof(FILESTATUS3L); /* File info buffer size */
  5832.   ULONG       ulOpenAction    = 0;                 /* Action taken by DosOpenL */
  5833.   APIRET      rc              = NO_ERROR;          /* Return code             */
  5834.   FHLOCK      FHLock          = 0;                 /* File handle lock        */
  5835.  
  5836.   /* Create a read-only file */
  5837.  
  5838.   rc = DosProtectOpenL(uchFileName,  fhDelFile,
  5839.    ulOpenAction, (LONGLONG)10, FILE_READONLY,
  5840.   OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
  5841.   OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE, 0L,  FHLock);
  5842.   if (rc != NO_ERROR)
  5843.   printf("DosProtectOpenL error  return code = %u\n", rc);
  5844.   return 1;
  5845.  
  5846.  
  5847.   rc = DosProtectQueryFileInfo(fhDelFile, FIL_STANDARDL,
  5848.    fsts3FileInfo, ulBufferSize, FHLock);   /* Get standard info */
  5849.   if (rc != NO_ERROR)
  5850.   printf("DosProtectQueryFileInfo error  return code = %u\n", rc);
  5851.   return 1;
  5852.     else   printf("File %s created read-only.\n",uchFileName);
  5853.  
  5854.   /*   Change the file attributes to be "normal"  */
  5855.  
  5856.   fsts3FileInfo.attrFile  = FILE_NORMAL;
  5857.   rc = DosProtectSetFileInfo(fhDelFile, FIL_STANDARDL,
  5858.    fsts3FileInfo, ulBufferSize, FHLock);
  5859.   if (rc != NO_ERROR)
  5860.   printf("DosProtectSetFileInfo error  return code = %u\n", rc);
  5861.   return 1;
  5862.  
  5863.  
  5864.   rc = DosProtectClose(fhDelFile, FHLock);
  5865.   /* Should verify that (rc != NO_ERROR) here... *//* Delete the file */
  5866.  
  5867.   rc = DosForceDelete(uchFileName);
  5868.   if (rc != NO_ERROR)
  5869.   printf("DosForceDelete error  return code = %u\n", rc);
  5870.   return 1;
  5871.     else
  5872.   printf("File %s has been deleted.\n",uchFileName);
  5873.      /* endif */
  5874.  
  5875.   return NO_ERROR;
  5876.  
  5877.  
  5878. ΓòÉΓòÉΓòÉ 5.19. DosProtectSetFileLocksL ΓòÉΓòÉΓòÉ
  5879.  
  5880. Purpose 
  5881.  
  5882. DosProtectSetFileLocksL locks and unlocks a range of an open file. 
  5883.  
  5884. Syntax 
  5885.  
  5886. #define INCL DOSFILEMGR
  5887. #include  os2.h
  5888.  
  5889.  APIRET DosProtectSetFileLocksL (HFILE hFile, PFILELOCKL pflUnlock, PFILELOCKL 
  5890.            pflLock, ULONG timeout, ULONG flags, FHLOCK fhFileHandleLockID) 
  5891.  
  5892.  Parameters 
  5893.  
  5894.  hFile  HFILE)  input 
  5895.            File handle. 
  5896.  
  5897.  pflUnlock  PFILELOCKL)  input 
  5898.            Address of the structure containing the offset and length of a range 
  5899.            to be unlocked. 
  5900.  
  5901.            The structure is shown in the following figure 
  5902.  
  5903.                       typedef struct  FILELOCKL
  5904.                         LONGLONG       lOffset
  5905.                         LONGLONG       lRange
  5906.                         FILELOCKL
  5907.  
  5908.  pflLock  PFILELOCKL)  input 
  5909.            Address of the structure containing the offset and length of a range 
  5910.            to be locked 
  5911.  
  5912.  timeout  ULONG)  input 
  5913.            The maximum time that the process is to wait for the requested 
  5914.            locks. 
  5915.  
  5916.            The time is represented in milliseconds. 
  5917.  
  5918.  flags  ULONG)  input 
  5919.            Flags that describe the action to be taken. 
  5920.  
  5921.            Possible actions are 
  5922.  
  5923.            Bits           Description 
  5924.  
  5925.            31 2           Reserved flags 
  5926.  
  5927.            1              Atomic 
  5928.  
  5929.                           This bit defines a request for atomic locking. If 
  5930.                           this bit is set to 1 and the lock range is equal to 
  5931.                           the unlock range, an atomic lock occurs. If this bit 
  5932.                           is set to 1 and the lock range is not equal to the 
  5933.                           unlock range, an error is returned. 
  5934.  
  5935.                           If this bit is set to 0, then the lock may or may not 
  5936.                           occur atomically with the unlock. 
  5937.  
  5938.            0              Share 
  5939.  
  5940.                           This bit defines the type of access that other 
  5941.                           processes may have to the file range that is being 
  5942.                           locked. 
  5943.  
  5944.                           If this bit is set to 0 (the default), other 
  5945.                           processes have no access to the locked file range. 
  5946.                           The current process has exclusive access to the 
  5947.                           locked file range, which must not overlap any other 
  5948.                           locked file range. 
  5949.  
  5950.                           If this bit is set to 1, the current process and 
  5951.                           other processes have shared read only access to the 
  5952.                           locked file range. A file range with shared access 
  5953.                           may overlap any other file range with shared access, 
  5954.                           but must not overlap any other file range with 
  5955.                           exclusive access. 
  5956.  
  5957.  fhFileHandleLockID  FHLOCK)  input 
  5958.            The filehandle lockid returned by a previous DosProtectOpenL. 
  5959.  
  5960.  Returns 
  5961.  
  5962.  ulrc  APIRET)  returns 
  5963.            Return Code. 
  5964.  
  5965.            DosProtectSetFileLocksL returns one of the following values 
  5966.  
  5967.            0              NO_ERROR 
  5968.  
  5969.            6              ERROR_INVALID_HANDLE 
  5970.  
  5971.            33             ERROR_LOCK_VIOLATION 
  5972.  
  5973.            36             ERROR_SHARING_BUFFER_EXCEEDED 
  5974.  
  5975.            87             ERROR_INVALID_PARAMETER 
  5976.  
  5977.            95             ERROR_INTERRUPT 
  5978.  
  5979.            174            ERROR_ATOMIC_LOCK_NOT_SUPPORTED 
  5980.  
  5981.            175            ERROR_READ_LOCKS_NOT_SUPPORTED 
  5982.  
  5983.  Remarks 
  5984.  
  5985.  DosProtectSetFileLocksL allows a process to lock and unlock a range in a file. 
  5986.  The time during which a file range is locked should be short. 
  5987.  
  5988.  If the lock and unlock ranges are both zero, ERROR_LOCK_VIOLATION is returned 
  5989.  to the caller. 
  5990.  
  5991.  If you only want to lock a file range, set the unlock file offset and the 
  5992.  unlock range length to zero. 
  5993.  
  5994.  If you only want to unlock a file range, set the lock file offset and the lock 
  5995.  range length to zero. 
  5996.  
  5997.  When the Atomic bit of flags is set to 0, and DosProtectSetFileLocksL 
  5998.  specifies a lock operation and an unlock operation, the unlock operation 
  5999.  occurs first, and then the lock operation is performed. If an error occurs 
  6000.  during the unlock operation, an error code is returned and the lock operation 
  6001.  is not performed. If an error occurs during the lock operation, an error code 
  6002.  is returned and the unlock remains in effect if it was successful. 
  6003.  
  6004.  The lock operation is atomic when all of these conditions are met 
  6005.  
  6006.      The Atomic bit is set to 1 in flags 
  6007.  
  6008.      The unlock range is the same as the lock range 
  6009.  
  6010.      The process has shared access to the file range, and has requested 
  6011.       exclusive access to it; or the process has exclusive access to the file 
  6012.       range, and has requested shared access to it. 
  6013.  
  6014.  Some file system drivers (FSDs) may not support atomic lock operations. 
  6015.  Versions of the operating system prior to OS/2 Version 2.00 do not support 
  6016.  atomic lock operations. If the application receives the error code 
  6017.  ERROR_ATOMIC_LOCK_NOT_SUPPORTED, the application should unlock the file range 
  6018.  and then lock it using a non-atomic operation (with the atomic bit set to 0 in 
  6019.  flags). The application should also refresh its internal buffers before making 
  6020.  any changes to the file. 
  6021.  
  6022.  If you issue DosProtectClose to close a file with locks still in effect, the 
  6023.  locks are released in no defined sequence. 
  6024.  
  6025.  If you end a process with a file open, and you have locks in effect in that 
  6026.  file, the file is closed and the locks are released in no defined sequence. 
  6027.  
  6028.  The locked range can be anywhere in the logical file. Locking beyond the end 
  6029.  of the file is not an error. A file range to be locked exclusively must first 
  6030.  be cleared of any locked file sub-ranges or overlapping locked file ranges. 
  6031.  
  6032.  If you repeat DosProtectSetFileLocksL for the same file handle and file range, 
  6033.  then you duplicate access to the file range. Access to locked file ranges is 
  6034.  not duplicated across DosExecPgm. The proper method of using locks is to 
  6035.  attempt to lock the file range, and to examine the return value. 
  6036.  
  6037.  The following table shows the level of access granted when the accessed file 
  6038.  range is locked with an exclusive lock or a shared lock.  Owner  refers to a 
  6039.  process that owns the lock.  Non-owner  refers to a process that does not own 
  6040.  the lock. 
  6041.  
  6042.  
  6043.    Action       Exclusive Lock             Shared Lock
  6044.  
  6045.    Owner read   Success                    Success
  6046.  
  6047.    Non-owner    Wait for unlock. Return    Success
  6048.    read         error code after time-out.
  6049.  
  6050.    Owner write  Success                    Wait for unlock. Return
  6051.                                            error code after time-out.
  6052.  
  6053.    Non-owner    Wait for unlock. Return    Wait for unlock. Return
  6054.    write        error code after time-out. error code after time-out.
  6055.  
  6056.  If only locking is specified, DosProtectSetFileLocksL locks the specified file 
  6057.  range using pflLock If the lock operation cannot be accomplished, an error is 
  6058.  returned, and the file range is not locked. 
  6059.  
  6060.  After the lock request is processed, a file range can be unlocked using the 
  6061.  pflUnlock parameter of another DosProtectSetFileLocksL request. If unlocking 
  6062.  cannot be accomplished, an error is returned. 
  6063.  
  6064.  Instead of denying read/write access to an entire file by specifying access 
  6065.  and sharing modes with DosProtectOpenL requests, a process attempts to lock 
  6066.  only the range needed for read/write access and examines the error code 
  6067.  returned. 
  6068.  
  6069.  Once a specified file range is locked exclusively, read and write access by 
  6070.  another process is denied until the file range is unlocked. If both unlocking 
  6071.  and locking are specified by DosProtectSetFileLocksL, the unlocking operation 
  6072.  is performed first, then locking is done. 
  6073.  
  6074.  Related Functions 
  6075.  
  6076.      DosCancelLockRequestL 
  6077.  
  6078.      DosDupHandle 
  6079.  
  6080.      DosExecPgm 
  6081.  
  6082.      DosProtectOpenL 
  6083.  
  6084.  Example Code 
  6085.  
  6086.  This example opens or creates and opens a file named  FLOCK.DAT  in protected 
  6087.  mode, and updates it using file locks. 
  6088.  
  6089.   #define INCL_DOSFILEMGR       /* File Manager values */
  6090.   #define INCL_DOSERRORS        /* DOS Error values    */
  6091.   #include  os2.h
  6092.   #include  stdio.h
  6093.   #include  string.h
  6094.  
  6095.   int main(VOID)
  6096.  
  6097.   HFILE     FileHandle   = NULLHANDLE;  /* File handle */
  6098.   ULONG     Action       = 0,           /* Action taken by DosOpenL */
  6099.   Wrote        = 0,           /* Number of bytes written by DosWrite */
  6100.   i            = 0;           /* Loop index */
  6101.   CHAR      FileData 40  = "Forty bytes of demonstration text data\r\n";
  6102.   APIRET    rc           = NO_ERROR;    /* Return code */
  6103.   FHLOCK    FHLock       = 0;           /* File handle lock   */
  6104.   FILELOCKL  LockArea     =  0 ,         /* Area of file to lock */
  6105.   UnlockArea   =  0 ;         /* Area of file to unlock */
  6106.  
  6107.   rc = DosProtectOpenL("flock.dat",                   /* File to open */
  6108.    FileHandle,                   /* File handle */
  6109.    Action,                       /* Action taken */
  6110.   (LONGLONG)4000,                /* File primary allocation */
  6111.   FILE_ARCHIVED,                 /* File attributes */
  6112.   FILE_OPEN | FILE_CREATE,       /* Open function type */
  6113.   OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE,
  6114.   0L,                            /* No extended attributes */
  6115.    FHLock);                      /* File handle lock */
  6116.   if (rc != NO_ERROR)                         /* If open failed */
  6117.   printf("DosProtectOpenL error  return code = %u\n", rc);
  6118.   return 1;
  6119.  
  6120.  
  6121.   LockArea.lOffset = 0;              /* Start locking at beginning of file */
  6122.   LockArea.lRange =  40;             /* Use a lock range of 40 bytes       */
  6123.   UnLockArea.lOffset = 0;              /* Start unlocking at beginning of file */
  6124.   UnLockArea.lRange =  0;              /* Use a unlock range of 0 bytes       */
  6125.  
  6126.   /* Write 8000 bytes to the file, 40 bytes at a time */
  6127.  
  6128.   for (i=0; i 200; ++i)
  6129.  
  6130.   rc = DosProtectSetFileLocksL(FileHandle,        /* File handle   */
  6131.    UnlockArea,       /* Unlock previous record (if any) */
  6132.    LockArea,         /* Lock current record */
  6133.   2000L,             /* Lock time-out value of 2 seconds */
  6134.   0L,                /* Exclusive lock, not atomic */
  6135.   FHLock);           /* File handle lock */
  6136.   if (rc != NO_ERROR)
  6137.   printf("DosProtectSetFileLocksL error  return code = %u\n", rc);
  6138.   return 1;
  6139.  
  6140.   rc = DosProtectWrite(FileHandle, FileData, sizeof(FileData),  Wrote, FHLock);
  6141.   if (rc != NO_ERROR)
  6142.   printf("DosProtectWrite error  return code = %u\n", rc);
  6143.   return 1;
  6144.  
  6145.   UnlockArea = LockArea;      /* Will unlock this record on next iteration */
  6146.   LockArea.lOffset += 40;     /* Prepare to lock next record               */
  6147.  
  6148.     /* endfor - 8000 bytes written */
  6149.  
  6150.   rc = DosProtectClose(FileHandle,FHLock);    /* Close file, release any locks */
  6151.   /* Should check if (rc != NO_ERROR) here .... */
  6152.  
  6153.   return NO_ERROR;
  6154.  
  6155.  
  6156. ΓòÉΓòÉΓòÉ 5.20. DosProtectSetFilePtrL ΓòÉΓòÉΓòÉ
  6157.  
  6158. Purpose 
  6159.  
  6160. DosProtectSetFilePtrL moves the read or write pointer according to the type of 
  6161. move specified. 
  6162.  
  6163. Syntax 
  6164.  
  6165. #define INCL DOSFILEMGR
  6166. #include  os2.h
  6167.  
  6168.  APIRET DosProtectSetFilePtrL (HFILE hFile, LONGLONG ib, ULONG method, 
  6169.            PLONGLONG ibActual, FHLOCK fhFileHandleLockID) 
  6170.  
  6171.  Parameters 
  6172.  
  6173.  hFile  HFILE)  input 
  6174.            The handle returned by a previous DosOpenL function. 
  6175.  
  6176.  ib  LONGLONG)  input 
  6177.            The signed distance (offset) to move, in bytes. 
  6178.  
  6179.  method  LONG)  input 
  6180.            The method of moving. 
  6181.  
  6182.            This field specifies the location in the file at which the 
  6183.            read/write pointer starts before adding the ib offset. The values 
  6184.            and their meanings are as shown in the following list 
  6185.  
  6186.            0        FILE_BEGIN 
  6187.  
  6188.                     Move the pointer from the beginning of the file. 
  6189.  
  6190.            1        FILE_CURRENT 
  6191.  
  6192.                     Move the pointer from the current location of the 
  6193.                     read/write pointer. 
  6194.  
  6195.            2        FILE_END 
  6196.  
  6197.                     Move the pointer from the end of the file. Use this method 
  6198.                     to determine a file s size. 
  6199.  
  6200.  ibActual  PLONGLONG)  output 
  6201.            Address of the new pointer location. 
  6202.  
  6203.  fhFileHandleLockID  FHLOCK)  input 
  6204.            The filehandle lockid returned by a previous DosProtectOpenL. 
  6205.  
  6206.  Returns 
  6207.  
  6208.  ulrc  APIRET)  returns 
  6209.            Return Code. 
  6210.  
  6211.            DosProtectSetFilePtrL returns one of the following values 
  6212.  
  6213.            0              NO_ERROR 
  6214.  
  6215.            1              ERROR_INVALID_FUNCTION 
  6216.  
  6217.            6              ERROR_INVALID_HANDLE 
  6218.  
  6219.            132            ERROR_SEEK_ON_DEVICE 
  6220.  
  6221.            131            ERROR_NEGATIVE_SEEK 
  6222.  
  6223.            130            ERROR_DIRECT_ACCESS_HANDLE 
  6224.  
  6225.  Remarks 
  6226.  
  6227.  The read/write pointer in a file is a signed 64-bit number. A negative value 
  6228.  for ib moves the pointer backward in the file; a positive value moves it 
  6229.  forward. DosProtectSetFilePtrL cannot be used to move to a negative position 
  6230.  in the file. 
  6231.  
  6232.  DosProtectSetFilePtrL cannot be used for a character device or pipe. 
  6233.  
  6234.  Related Functions 
  6235.  
  6236.      DosProtectOpenL 
  6237.  
  6238.      DosProtectRead 
  6239.  
  6240.      DosProtectSetFileSizeL 
  6241.  
  6242.      DosProtectWrite 
  6243.  
  6244.  Example Code 
  6245.  
  6246.  This example opens or creates and opens a file named  DOSPROT.DAT , writes a 
  6247.  string to it, returns the file pointer to the beginning of the file, reads it, 
  6248.  and finally closes it using DosProtect functions. 
  6249.  
  6250.   #define INCL_DOSFILEMGR          /* File Manager values */
  6251.   #define INCL_DOSERRORS           /* DOS Error values    */
  6252.   #include  os2.h
  6253.   #include  stdio.h
  6254.   #include  string.h
  6255.  
  6256.   int main(VOID)
  6257.   HFILE  hfFileHandle   = 0L;
  6258.   ULONG  ulAction       = 0;
  6259.   ULONG  ulBytesRead    = 0;
  6260.   ULONG  ulWrote        = 0;
  6261.   LONGLONG  ullLocal    = 0;
  6262.   UCHAR  uchFileName 20   = "dosprot.dat",
  6263.   uchFileData 100  = " ";
  6264.   FHLOCK FileHandleLock = 0;        /* File handle lock   */
  6265.   APIRET rc             = NO_ERROR; /* Return code */
  6266.  
  6267.   /* Open the file test.dat.  Make it read/write, open it */
  6268.   /* if it already exists and create it if it is new.     */
  6269.   rc = DosProtectOpenL(uchFileName,             /* File path name          */
  6270.    hfFileHandle,                  /* File handle             */
  6271.    ulAction,                      /* Action taken            */
  6272.   (LONGLONG)100,                           /* File primary allocation */
  6273.   FILE_ARCHIVED | FILE_NORMAL,    /* File attribute          */
  6274.   OPEN_ACTION_CREATE_IF_NEW |
  6275.   OPEN_ACTION_OPEN_IF_EXISTS,     /* Open function type      */
  6276.   OPEN_FLAGS_NOINHERIT |
  6277.   OPEN_SHARE_DENYNONE  |
  6278.   OPEN_ACCESS_READWRITE,          /* Open mode of the file   */
  6279.   0L,                             /* No extended attribute   */
  6280.    FileHandleLock);               /* File handle lock id     */
  6281.   if (rc != NO_ERROR)
  6282.   printf("DosProtectOpenL error  return code = %u\n", rc);
  6283.   return 1;
  6284.     else
  6285.   printf ("DosProtectOpenL  Action taken = %u\n", ulAction);
  6286.     /* endif */
  6287.  
  6288.   /* Write a string to the file */
  6289.   strcpy (uchFileData, "testing...\n3...\n2...\n1\n");
  6290.  
  6291.   rc = DosProtectWrite (hfFileHandle,       /* File handle                  */
  6292.   (PVOID) uchFileData,       /* String to be written         */
  6293.   sizeof (uchFileData),      /* Size of string to be written */
  6294.    ulWrote,                  /* Bytes actually written       */
  6295.   FileHandleLock);           /* File handle lock id          */if (rc != NO_ERROR)
  6296.   printf("DosProtectWrite error  return code = %u\n", rc);
  6297.   return 1;
  6298.     else
  6299.   printf ("DosProtectWrite  Bytes written = %u\n", ulWrote);
  6300.     /* endif */
  6301.  
  6302.   /* Move the file pointer back to the beginning of the file */
  6303.   rc = DosProtectSetFilePtrL (hfFileHandle,   /* File Handle          */
  6304.   (LONGLONG)0,            /* Offset               */
  6305.   FILE_BEGIN,             /* Move from BOF        */
  6306.    ullLocal,              /* New location address */
  6307.   FileHandleLock);        /* File handle lock id  */
  6308.   if (rc != NO_ERROR)
  6309.   printf("DosSetFilePtr error  return code = %u\n", rc);
  6310.   return 1;
  6311.  
  6312.  
  6313.   /* Read the first 100 bytes of the file */
  6314.   rc = DosProtectRead (hfFileHandle,         /* File Handle                 */
  6315.   uchFileData,                 /* String to be read           */
  6316.   100L,                        /* Length of string to be read */
  6317.    ulBytesRead,                /* Bytes actually read         */
  6318.   FileHandleLock);             /* File handle lock id         */
  6319.   if (rc != NO_ERROR)
  6320.   printf("DosProtectRead error  return code = %u\n", rc);
  6321.   return 1;
  6322.     else
  6323.   printf("DosProtectRead  Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
  6324.     /* endif */
  6325.  
  6326.   rc = DosProtectClose(hfFileHandle, FileHandleLock);   /* Close the file */
  6327.   if (rc != NO_ERROR)
  6328.   printf("DosProtectClose error  return code = %u\n", rc);
  6329.   return 1;
  6330.  
  6331.   return NO_ERROR;
  6332.  
  6333.  
  6334. ΓòÉΓòÉΓòÉ 5.21. DosProtectSetFileSizeL ΓòÉΓòÉΓòÉ
  6335.  
  6336. Purpose 
  6337.  
  6338. DosProtectSetFileSizeL changes the size of a file. 
  6339.  
  6340. Syntax 
  6341.  
  6342. #define INCL DOSFILEMGR
  6343. #include  os2.h
  6344.  
  6345.  APIRET DosProtectSetFileSizeL (HFILE hFile, LONGLONG cbSize, FHLOCK 
  6346.            fhFileHandleLockID) 
  6347.  
  6348.  Parameters 
  6349.  
  6350.  hFile  HFILE)  input 
  6351.            Handle of the file whose size to be changed. 
  6352.  
  6353.  cbSize  LONGLONG)  input 
  6354.            New size, in bytes, of the file. 
  6355.  
  6356.  fhFileHandleLockID  FHLOCK)  input 
  6357.            The filehandle lockid obtained from DosProtectOpenL. 
  6358.  
  6359.  Returns 
  6360.  
  6361.  ulrc  APIRET)  returns 
  6362.            Return Code. 
  6363.  
  6364.            DosProtectSetFileSizeL returns one of the following values 
  6365.  
  6366.            0              NO_ERROR 
  6367.  
  6368.            5              ERROR_ACCESS_DENIED 
  6369.  
  6370.            6              ERROR_INVALID_HANDLE 
  6371.  
  6372.            26             ERROR_NOT_DOS_DISK 
  6373.  
  6374.            33             ERROR_LOCK_VIOLATION 
  6375.  
  6376.            87             ERROR_INVALID_PARAMETER 
  6377.  
  6378.            112            ERROR_DISK_FULL 
  6379.  
  6380.  Remarks 
  6381.  
  6382.  When DosProtectSetFileSizeL is issued, the file must be open in a mode that 
  6383.  allows write access. 
  6384.  
  6385.  The size of the open file can be truncated or extended. If the file size is 
  6386.  being extended, the file system tries to allocate additional bytes in a 
  6387.  contiguous (or nearly contiguous) space on the medium. The values of the new 
  6388.  bytes are undefined. 
  6389.  
  6390.  Related Functions 
  6391.  
  6392.      DosProtectOpenL 
  6393.  
  6394.      DosProtectQueryFileInfo 
  6395.  
  6396.      DosQueryPathInfo 
  6397.  
  6398.  Example Code 
  6399.  
  6400.  This example writes to a file named  DOSPMAN.DAT , resets the buffer, and 
  6401.  changes the size of the file using DosProtect functions. 
  6402.  
  6403.   #define INCL_DOSFILEMGR          /* File Manager values */
  6404.   #define INCL_DOSERRORS           /* DOS Error values    */
  6405.   #include  os2.h
  6406.   #include  stdio.h
  6407.   #include  string.h
  6408.  
  6409.   int main(VOID)
  6410.   HFILE  hfFileHandle   = 0L;     /* Handle for file being manipulated */
  6411.   ULONG  ulAction       = 0;      /* Action taken by DosOpenL */
  6412.   FHLOCK FileHandleLock = 0;      /* File handle lock   */
  6413.  
  6414.   ULONG  ulWrote        = 0;      /* Number of bytes written by DosWrite */
  6415.   UCHAR  uchFileName 20   = "dospman.dat",     /* Name of file */
  6416.   uchFileData 4    = "DATA";            /* Data to write to file */
  6417.   APIRET rc             = NO_ERROR;            /* Return code */
  6418.  
  6419.   /* Open the file dosman.dat.  Use an existing file or create a new */
  6420.   /* one if it doesn't exist.                                      */
  6421.   rc = DosProtectOpenL(uchFileName,  hfFileHandle,  ulAction, (LONGLONG)4,
  6422.   FILE_ARCHIVED | FILE_NORMAL,
  6423.   OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
  6424.   OPEN_FLAGS_NOINHERIT | OPEN_SHARE_DENYNONE  |
  6425.   OPEN_ACCESS_READWRITE, 0L,  FileHandleLock);
  6426.   if (rc != NO_ERROR)
  6427.   printf("DosProtectOpenL error  return code = %u\n", rc);
  6428.   return 1;
  6429.  
  6430.  
  6431.   rc = DosProtectWrite (hfFileHandle, (PVOID) uchFileData,
  6432.   sizeof (uchFileData),  ulWrote, FileHandleLock);
  6433.   if (rc != NO_ERROR)
  6434.   printf("DosProtectWrite error  return code = %u\n", rc);
  6435.   return 1;
  6436.  
  6437.  
  6438.   rc = DosResetBuffer (hfFileHandle);
  6439.   if (rc != NO_ERROR)
  6440.   printf("DosResetBuffer error  return code = %u\n", rc);
  6441.   return 1;
  6442.     /* endif */
  6443.  
  6444.   rc = DosProtectSetFileSizeL (hfFileHandle, (LONGLONG)8, FileHandleLock);
  6445.   if (rc != NO_ERROR)
  6446.   printf("DosProtectSetFileSizeL error  return code = %u\n", rc);
  6447.   return 1;
  6448.  
  6449.  
  6450.   return NO_ERROR;
  6451.  
  6452.  
  6453. ΓòÉΓòÉΓòÉ 5.22. DosQueryABIOSSupport ΓòÉΓòÉΓòÉ
  6454.  
  6455. Purpose 
  6456.  
  6457. DosQueryABIOSSupport returns flags that indicate various basic hardware 
  6458. configurations. 
  6459.  
  6460. Syntax 
  6461.  
  6462. #define INCL_DOSMODULEMGR
  6463. #include  os2.h>
  6464.  
  6465.  APIRET APRENTRY DosQueryABIOSSupport (ULONG Reserved) 
  6466.  
  6467.  Parameters 
  6468.  
  6469.  reserved (ULONG)  input 
  6470.            Must be set to 0L. No other value is defined. 
  6471.  
  6472.            The following flags are returned 
  6473.  
  6474.            HW_CFG_MCA     0x01 
  6475.  
  6476.            HW_CFG_EISA    0x02 
  6477.  
  6478.            HW_CFG_ABIOS_SUPPORTED 0x04 
  6479.  
  6480.            HW_CFG_ABIOS_PRESENT 0x08 
  6481.  
  6482.            HW_CFG_PCI     0x10 
  6483.  
  6484.            HW_CFG_OEM_ABIOS 0x20 
  6485.  
  6486.            HW_CFG_IBM_ABIOS 0000 
  6487.  
  6488.            HW_CFG_PENTIUM_CPU 0x40 
  6489.  
  6490.  Example Code 
  6491.  
  6492.   int main(int argc, char *argv[], char *envp[])
  6493.   {
  6494.      APIRET flags;
  6495.  
  6496.      flags = DosQueryABIOSSupport(0L);
  6497.  
  6498.      printf("H/W config  %08x\n",flags);
  6499.  
  6500.      if (flags   HW_CFG_MCA)             printf("            0x01 => MCA Bus\n");
  6501.      if (flags   HW_CFG_EISA)            printf("            0x02 => EISA Bus\n");
  6502.      if (flags   HW_CFG_ABIOS_SUPPORTED) printf("            0x04 => ABIOS Supported\n");
  6503.      if (flags   HW_CFG_ABIOS_PRESENT)   printf("            0x08 => ABIOS Present\n");
  6504.      if (flags   HW_CFG_PCI)             printf("            0x10 => PCI Bus\n");
  6505.      if (flags   HW_CFG_OEM_ABIOS)       printf("            0x20 => OEM ABIOS\n");
  6506.      if (flags   HW_CFG_PENTIUM_CPU)     printf("            0x40 => Pentium or Higher CPU\n");
  6507.  
  6508.      return 0;
  6509.   }
  6510.  
  6511.  
  6512. ΓòÉΓòÉΓòÉ 5.23. DosQueryFileInfo ΓòÉΓòÉΓòÉ
  6513.  
  6514. Purpose 
  6515.  
  6516. DosQueryFileInfo gets file information. 
  6517.  
  6518. Syntax 
  6519.  
  6520. #define INCL DOSFILEMGR
  6521. #include  os2.h
  6522.  
  6523.  APIRET DosQueryFileInfo (HFILE hf, ULONG ulInfoLevel, PVOID pInfo, ULONG 
  6524.            cbInfoBuf) 
  6525.  
  6526.  Parameters 
  6527.  
  6528.  hf  HFILE)  input 
  6529.            The file handle. 
  6530.  
  6531.  ulInfoLevel  ULONG)  input 
  6532.            Level of file information required. 
  6533.  
  6534.            Specify a value 
  6535.  
  6536.            1        FIL_STANDARD 
  6537.  
  6538.                     Level 1 file information 
  6539.  
  6540.            11       FIL_STANDARDL 
  6541.  
  6542.                     Level 11 file information 
  6543.  
  6544.            2        FIL_QUERYEASIZE 
  6545.  
  6546.                     Level 2 file information 
  6547.  
  6548.            12       FIL_QUERYEASIZEL 
  6549.  
  6550.                     Level 12 file information 
  6551.  
  6552.            3        FIL_QUERYEASFROMLIST 
  6553.  
  6554.                     Level 3 file information 
  6555.  
  6556.            Level 4 is reserved. 
  6557.  
  6558.            The structures described in pInfo indicate the information returned 
  6559.            for each of these levels. 
  6560.  
  6561.  pInfo  PVOID)  output 
  6562.            Address of the storage area where the system returns the requested 
  6563.            level of file information. 
  6564.  
  6565.            File information, where applicable, is at least as accurate as the 
  6566.            most recent DosClose, DosResetBuffer, DosSetFileInfo, or 
  6567.            DosSetPathInfo. 
  6568.  
  6569.            Level 1 File Information (ulInfoLevel == FIL_STANDARD) 
  6570.                     pInfo contains the FILESTATUS3 data structure, in which 
  6571.                     file information is returned. 
  6572.  
  6573.            Level 11 File Information (ulInfoLevel == FIL_STANDARDL) 
  6574.                     pInfo contains the FILESTATUS3L data structure, in which 
  6575.                     file information is returned. 
  6576.  
  6577.            Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) 
  6578.                     pInfo contains the FILESTATUS4 data structure. This is 
  6579.                     similar to the Level 1 structure, with the addition of the 
  6580.                     cbList field after the attrFile field. 
  6581.  
  6582.                     The cbList field is an unsigned ULONG. On output, this 
  6583.                     field contains the size, in bytes, of the file s entire 
  6584.                     extended attribute (EA) set on disk. You can use this value 
  6585.                     to calculate the size of the buffer required to hold the EA 
  6586.                     information returned when a value of 3 is specified for 
  6587.                     ulInfoLevel. The buffer size is less than or equal to twice 
  6588.                     the size of the file s entire EA set on disk. 
  6589.  
  6590.            Level 12 File Information (ulInfoLevel == FIL_QUERYEASIZEL) 
  6591.                     pInfo contains the FILESTATUS4L data structure. This is 
  6592.                     similar to the Level 1 structure, with the addition of the 
  6593.                     cbList field after the attrFile field. 
  6594.  
  6595.                     The cbList field is an unsigned ULONG. On output, this 
  6596.                     field contains the size, in bytes, of the file s entire 
  6597.                     extended attribute (EA) set on disk. You can use this value 
  6598.                     to calculate the size of the buffer required to hold the EA 
  6599.                     information returned when a value of 3 is specified for 
  6600.                     ulInfoLevel. The buffer size is less than or equal to twice 
  6601.                     the size of the file s entire EA set on disk. 
  6602.  
  6603.            Level 3 File Information (ulInfoLevel == FIL_QUERYEASFROMLIST) 
  6604.  
  6605.                     Input        pInfo contains an EAOP2 data structure. 
  6606.                                  fpGEA2List points to a GEA2 list defining the 
  6607.                                  attribute names whose values are returned. The 
  6608.                                  GEA2 data structures must be aligned on a 
  6609.                                  doubleword boundary. Each oNextEntryOffset 
  6610.                                  field must contain the number of bytes from 
  6611.                                  the beginning of the current entry to the 
  6612.                                  beginning of the next entry in the GEA2 list. 
  6613.                                  The oNextEntryOffset field in the last entry 
  6614.                                  of the GEA2 list must be 0. fpFEA2List points 
  6615.                                  to a data area where the relevant FEA2 list is 
  6616.                                  returned. The length field of this FEA2 list 
  6617.                                  is valid, giving the size of the FEA2 list 
  6618.                                  buffer. oError is ignored. 
  6619.  
  6620.                     Output       pInfo is unchanged. The buffer pointed to by 
  6621.                                  fpFEA2List is filled with the returned 
  6622.                                  information. If the buffer that fpFEA2List 
  6623.                                  points to is not large enough to hold the 
  6624.                                  returned information (the return code is 
  6625.                                  ERROR_BUFFER_OVERFLOW), cbList is still valid, 
  6626.                                  assuming there is at least enough space for 
  6627.                                  it. Its value is the size of the entire EA set 
  6628.                                  on disk for the file, even though only a 
  6629.                                  subset of attributes was requested. 
  6630.  
  6631.  cbInfoBuf  ULONG)  input 
  6632.            The length, in bytes, of pInfo. 
  6633.  
  6634.  Returns 
  6635.  
  6636.  ulrc  APIRET)  returns 
  6637.            Return Code. 
  6638.  
  6639.            DosQueryFileInfo returns one of the following values 
  6640.  
  6641.            0              NO_ERROR 
  6642.  
  6643.            5              ERROR_ACCESS_DENIED 
  6644.  
  6645.            6              ERROR_INVALID_HANDLE 
  6646.  
  6647.            111            ERROR_BUFFER_OVERFLOW 
  6648.  
  6649.            124            ERROR_INVALID_LEVEL 
  6650.  
  6651.            130            ERROR_DIRECT_ACCESS_HANDLE 
  6652.  
  6653.            254            ERROR_INVALID_EA_NAME 
  6654.  
  6655.            255            ERROR_EA_LIST_INCONSISTENT 
  6656.  
  6657.  Remarks 
  6658.  
  6659.  Information levels designated  L  should be used in order to get complete size 
  6660.  information for files larger than 2GB. If information levels designated  L 
  6661.  are not used, a size of one byte will be returned for files which are >2GB in 
  6662.  size. 
  6663.  
  6664.  In the FAT file system, only date and time information contained in Level 1 
  6665.  file information can be modified. Zero is returned for the creation and access 
  6666.  dates and times. 
  6667.  
  6668.  To return information contained in any of the file information levels, 
  6669.  DosQueryFileInfo must be able to read the open file. DosQueryFileInfo works 
  6670.  only when the file is opened for read access, with a deny-write sharing mode 
  6671.  specified for access by other processes. If another process that has specified 
  6672.  conflicting sharing and access modes has already opened the file, any call to 
  6673.  DosOpenL will fail. 
  6674.  
  6675.  DosEnumAttribute returns the lengths of EAs. This information can be used to 
  6676.  calculate what size pInfo needs to be to hold full-extended-attribute (FEA) 
  6677.  information returned by DosQueryFileInfo when Level 3 is specified. The size 
  6678.  of the buffer is calculated as follows 
  6679.  
  6680.       Four bytes (for oNextEntryOffset) + 
  6681.       One byte (for fEA + 
  6682.       One byte (for cbName) + 
  6683.       Two bytes (for cbValue) + 
  6684.       Value of cbName (for the name of the EA) + 
  6685.       One byte (for terminating NULL in cbName) + 
  6686.       Value of cbValue (for the value of the EA) 
  6687.  
  6688.  Related Functions 
  6689.  
  6690.      DosClose 
  6691.  
  6692.      DosEnumAttribute 
  6693.  
  6694.      DosOpen 
  6695.  
  6696.      DosOpenL 
  6697.  
  6698.      DosQueryPathInfo 
  6699.  
  6700.      DosResetBuffer 
  6701.  
  6702.      DosSetFileInfo 
  6703.  
  6704.      DosSetFileSize 
  6705.  
  6706.      DosSetFileSizeL 
  6707.  
  6708.      DosSetPathInfo 
  6709.  
  6710.  Example Code 
  6711.  
  6712.  This example obtains the information of the  CONFIG.SYS  file. 
  6713.  
  6714.   #define INCL_DOSFILEMGR   /* File Manager values */
  6715.   #define INCL_DOSERRORS    /* DOS error values    */
  6716.   #include  os2.h
  6717.   #include  stdio.h
  6718.  
  6719.   int main(VOID)
  6720.   UCHAR        uchFileName 80  = "C \\CONFIG.SYS";  /* File to manipulate    */
  6721.   FILESTATUS3L  fsts3ConfigInfo =   0  ;       /* Buffer for file information */
  6722.   ULONG        ulBufSize     = sizeof(FILESTATUS3L);  /* Size of above buffer */
  6723.   HFILE        hfConfig      = 0;             /* Handle for Config file      */
  6724.   ULONG        ulOpenAction  = 0;             /* Action taken by DosOpenL     */
  6725.   APIRET       rc            = NO_ERROR;      /* Return code                 */
  6726.  
  6727.   rc = DosOpenL(uchFileName,                 /* File to open (path and name) */
  6728.    hfConfig,                /* File handle returned         */
  6729.    ulOpenAction,               /* Action taken by DosOpenL      */
  6730.   (LONGLONG)0,0L,        /* Primary allocation and attributes (ignored) */
  6731.   OPEN_ACTION_FAIL_IF_NEW |
  6732.   OPEN_ACTION_OPEN_IF_EXISTS,  /* Open an existing file only   */
  6733.   OPEN_FLAGS_NOINHERIT | OPEN_ACCESS_READONLY |
  6734.   OPEN_SHARE_DENYNONE,         /* Read access only             */
  6735.   0L);                         /* Extended attributes (ignored)*/
  6736.  
  6737.   if (rc != NO_ERROR)
  6738.   printf("DosOpenL error  return code = %u\n", rc);
  6739.   return 1;
  6740.  
  6741.  
  6742.   rc = DosQueryFileInfo(hfConfig,   /* Handle of file                  */
  6743.   FIL_STANDARDL,  /* Request standard (Level 11) info */
  6744.    fsts3ConfigInfo, /* Buffer for file information  */
  6745.   ulBufSize);    /* Size of buffer                  */
  6746.   if (rc != NO_ERROR)
  6747.   printf("DosQueryFileInfo error  return code = %u\n", rc);
  6748.   return 1;
  6749.  
  6750.  
  6751.   rc = DosClose(hfConfig);      /* Close the file  (check RC in real life) */
  6752.   printf("%s ---  File size  %lld bytes\n",uchFileName, fsts3ConfigInfo.cbFile);
  6753.   printf("Last updated  %d/%d/%d; %d %2.2d\n",
  6754.   fsts3ConfigInfo.fdateLastWrite.month,        /* Month            */
  6755.   fsts3ConfigInfo.fdateLastWrite.day,          /* Day              */
  6756.   (fsts3ConfigInfo.fdateLastWrite.year+1980L), /* Years since 1980 */
  6757.   fsts3ConfigInfo.ftimeLastWrite.hours,        /* Hours            */
  6758.   fsts3ConfigInfo.ftimeLastWrite.minutes);     /* Minutes          */
  6759.  
  6760.   return NO_ERROR;
  6761.  
  6762.  
  6763. ΓòÉΓòÉΓòÉ 5.24. DosQueryMemState ΓòÉΓòÉΓòÉ
  6764.  
  6765. Purpose 
  6766.  
  6767. DosQueryMemState gets the status of a range of pages in memory. Its input 
  6768. parameters are an address and size. The address is rounded down to page 
  6769. boundary and size is rounded up to a whole number of pages. The status of the 
  6770. pages in the range is returned in the state parameter, and the size of the 
  6771. range queried is returned in the size parameter. If the pages in the range have 
  6772. conflicting states, then the state of the first page is returned. 
  6773.  
  6774. Syntax 
  6775.  
  6776. #define INCL_PROFILE
  6777. #include  os2.h>
  6778.  
  6779.  APIRET APIENTRY DosQueryMemState (PVOID pMem, PULONG size, PULONG state) 
  6780.  
  6781.  Parameters 
  6782.  
  6783.  pMem (PVOID)  input 
  6784.  
  6785.  size (PULONG)  input/output 
  6786.  
  6787.  state (PLONG)  output 
  6788.            Flags indicate the following page states 
  6789.  
  6790.            PAG_NPOUT 0x00000000 Page is not present, not in core. 
  6791.  
  6792.            PAG_PRESENT 0x00000001 Page is present. 
  6793.  
  6794.            PAG_NPIN 0x00000002 Page is not present, in core. 
  6795.  
  6796.            PAG_PRESMASK 0x00000003 Present state mask. 
  6797.  
  6798.            PAG_INVALID 0x00000000 Page is invalid. 
  6799.  
  6800.            PAG_RESIDENT 0x00000010 Page is resident. 
  6801.  
  6802.            PAG_SWAPPABLE 0x00000020 Page is swappable. 
  6803.  
  6804.            PAG_DISCARDABLE 0x00000030 Page is discardable. 
  6805.  
  6806.            PAG_TYPEMASK 0x00000030 Typemask. 
  6807.  
  6808.  Returns 
  6809.  
  6810.  ulrc (APIRET)  returns 
  6811.            Return Code. 
  6812.  
  6813.            DosQueryMemState returns one of the following values 
  6814.  
  6815.            0              NO_ERROR 
  6816.  
  6817.            87             ERROR_INVALID_PARAMETER 
  6818.  
  6819.            487            ERROR_INVALID_ADDRESS 
  6820.  
  6821.  Related Functions 
  6822.  
  6823.      DosQueryMem 
  6824.  
  6825.  Example Code 
  6826.  
  6827.   int main(int argc, char *argv[], char *envp[])
  6828.   {
  6829.      APIRET rc=0;
  6830.      PVOID pMem;
  6831.      ULONG status;
  6832.      ULONG size;
  6833.      ULONG pages;
  6834.      ULONG onepage = 0x1000;
  6835.  
  6836.      if (argc   3) {
  6837.  
  6838.         printf("Syntax  MEMSTATE  address>  size>\n");
  6839.         return 0;
  6840.  
  6841.      } else {
  6842.  
  6843.         pMem = (PVOID) strtoul(argv[1], NULL, 0);
  6844.         size = strtoul(argv[2], NULL, 0);
  6845.         pages = (size+0x0fff) >> 12;
  6846.  
  6847.         printf("address     state\n");
  6848.         while (pages--) {
  6849.  
  6850.            rc = DosQueryMemState(pMem,  onepage,  status);
  6851.  
  6852.            if (rc) printf("0x%08x DosQueryMemState returned %u\n",pMem, rc);
  6853.            else {
  6854.               printf("0x%08x 0x%08x ", pMem, status);
  6855.               if ((status   PAG_PRESMASK) == PAG_NPOUT) printf("not present, not in-core, ");
  6856.               else if (status   PAG_PRESENT) printf("present, in-core, ");
  6857.               else if (status   PAG_NPIN) printf("not present, in-core, ");
  6858.  
  6859.               if ((status   PAG_TYPEMASK) == PAG_INVALID) printf("invalid\n");
  6860.               if ((status   PAG_TYPEMASK) == PAG_RESIDENT) printf("resident\n");
  6861.               if ((status   PAG_TYPEMASK) == PAG_SWAPPABLE) printf("swappable\n");
  6862.               if ((status   PAG_TYPEMASK) == PAG_DISCARDABLE) printf("discardable\n");
  6863.            }
  6864.            pMem = (PVOID)((ULONG)pMem + 0x1000);
  6865.  
  6866.         } /* endwhile */
  6867.  
  6868.      } /* end if*/
  6869.  
  6870.      return rc;
  6871.   }
  6872.  
  6873.  
  6874. ΓòÉΓòÉΓòÉ 5.25. Dos16QueryModFromCS ΓòÉΓòÉΓòÉ
  6875.  
  6876. Purpose 
  6877.  
  6878. Dos16QueryModFromCS queries the name, segment, and handle that corresponds to a 
  6879. 16 bit selector. It takes a selector as a parameter and returns information 
  6880. about the module (a protect mode application currently executing) owning that 
  6881. selector. 
  6882.  
  6883. Syntax 
  6884.  
  6885. #define INCL_DOSMODULEMGR
  6886. #include  os2.h>
  6887.  
  6888.  APIRET16 APIENTRY16 Dos16QueryModFromCS (SEL sel, PQMRESULT qmresult) 
  6889.  
  6890.  Parameters 
  6891.  
  6892.  sel (SEL)  input 
  6893.            Selector to be queried. 
  6894.  
  6895.  qmresult (QMRESULT)  output 
  6896.            Structure containing the queried information 
  6897.  
  6898.                       typedef struct_QMRESULT{
  6899.                       USHORT seg;
  6900.                       USHORT htme;
  6901.                       char name[256];
  6902.                       } QMRESULT;
  6903.  
  6904.                       typedef QMRESULT*PQMRESULT;
  6905.  
  6906.  Returns 
  6907.  
  6908.  ulrc (APIRET)  returns 
  6909.            Return Code. 
  6910.  
  6911.            Dos16QueryModFromCS returns one of the following values 
  6912.  
  6913.            0              NO_ERROR 
  6914.  
  6915.            87             ERROR_INVALID_PARAMETER 
  6916.  
  6917.  Related Functions 
  6918.  
  6919.      DosQueryModFromEIP 
  6920.  
  6921.      DosSetExceptionHandler 
  6922.  
  6923.  Example Code 
  6924.  
  6925.   int main(int argc, char *argv[], char *envp[])
  6926.   {
  6927.      SEL sel=0;
  6928.      QMRESULT qmresult;
  6929.      APIRET16 rc;
  6930.  
  6931.      if (argc!=2) {
  6932.         printf("QMODCS sel\n");
  6933.         return;
  6934.      } /* endif */
  6935.  
  6936.      sel=(SEL)strtoul(argv[1],NULL,16);
  6937.  
  6938.      rc=Dos16QueryModFromCS(sel,  qmresult);
  6939.  
  6940.      if (rc != 0) {
  6941.         printf("DosQueryModFromCS returned rc=%u\n",rc);
  6942.         return rc;
  6943.      } /* endif */
  6944.  
  6945.      printf("Sel=0x%04x Handle=0x%04x Segment=0x%04x %s\n",
  6946.              sel,qmresult.hmte,qmresult.seg,qmresult.name);
  6947.  
  6948.      return 0;
  6949.   }
  6950.  
  6951.  
  6952. ΓòÉΓòÉΓòÉ 5.26. DosQueryModFromEIP ΓòÉΓòÉΓòÉ
  6953.  
  6954. Purpose 
  6955.  
  6956. DosQueryModFromEIP queries a module handle and name from a given flat address. 
  6957. It takes a flat 32 bit address as a parameter and returns information about the 
  6958. module (a protect mode application currently executing) owning the storage. 
  6959.  
  6960. Syntax 
  6961.  
  6962. #define INCL_DOSMODULEMGR
  6963. #include  os2.h>
  6964.  
  6965.  APIRET APIENTRY DosQueryModFromEIP (HMODULE *phMod, ULONG *pObjNum, ULONG 
  6966.            BuffLen, PCHAR pBuff, ULONG *pOffset, ULONG Address) 
  6967.  
  6968.  Parameters 
  6969.  
  6970.  phMod (PHMODULE)  output 
  6971.            Address of a location in which the module handle is returned. 
  6972.  
  6973.  pObjNum (PULONG)  output 
  6974.            Address of a ULONG where the module object number corresponding to 
  6975.            the Address is returned. The object is zero based. 
  6976.  
  6977.  BuffLen (ULONG)  input 
  6978.            Length of the user supplied buffer pointed to by pBuff. 
  6979.  
  6980.  pBuff (PCHAR)  output 
  6981.            Address of a user supplied buffer in which the module name is 
  6982.            returned. 
  6983.  
  6984.  pOffset (PULONG)  output 
  6985.            Address of a where the offset to the object corresponding to the 
  6986.            Address is returned. The offset is zero based. 
  6987.  
  6988.  Address (ULONG)  input 
  6989.            Input address to be queried. 
  6990.  
  6991.  Returns 
  6992.  
  6993.  ulrc (APIRET)  returns 
  6994.            Return Code. 
  6995.  
  6996.            DosQueryModFromEIP returns one of the following values 
  6997.  
  6998.            0              NO_ERROR 
  6999.  
  7000.            87             ERROR_INVALID_PARAMETER 
  7001.  
  7002.            487            ERROR_INVALID_ADDRESS 
  7003.  
  7004.  Related Functions 
  7005.  
  7006.      DosQueryModFromEIP 
  7007.  
  7008.      DosSetExceptionHandler 
  7009.  
  7010.  Example Code 
  7011.  
  7012.   int main(int argc, char *argv[], char *envp[])
  7013.   {
  7014.      HMODULE hMod;
  7015.      ULONG ObjNum;
  7016.      ULONG Offset;
  7017.      ULONG eip;
  7018.      APIRET rc;
  7019.      char Buff[256];
  7020.  
  7021.  
  7022.      if (argc !=2) {
  7023.         printf("QEIP \n");
  7024.         return 0;
  7025.      } /* endif */
  7026.  
  7027.      eip = strtoul(argv[1],NULL,0);
  7028.  
  7029.      rc=DosQueryModFromEIP(  hMod,
  7030.                              ObjNum,
  7031.                             sizeof(Buff),
  7032.                             Buff,
  7033.                              Offset,
  7034.                             eip);
  7035.      if (rc!=0) {
  7036.         printf("DosQueryModFromEIP returned rc=%u\n",rc);
  7037.         return rc;
  7038.      } /* endif */
  7039.  
  7040.      printf("\nLinear Address  0x%08x\n",eip);
  7041.      printf("%s\n",Buff);
  7042.      printf("handle  0x%04x\n",hMod);
  7043.      printf("Object  0x%08x\n",ObjNum);
  7044.      printf("Offset  0x%08x\n",Offset);
  7045.  
  7046.      return 0;
  7047.   }
  7048.  
  7049.  
  7050. ΓòÉΓòÉΓòÉ 5.27. DosQueryPathInfo ΓòÉΓòÉΓòÉ
  7051.  
  7052. Purpose 
  7053.  
  7054. DosQueryPathInfo gets file information for a file or subdirectory. 
  7055.  
  7056. Syntax 
  7057.  
  7058. #define INCL DOSFILEMGR
  7059. #include  os2.h
  7060.  
  7061.  APIRET DosQueryPathInfo (PSZ pszPathName, ULONG ulInfoLevel, PVOID pInfoBuf, 
  7062.            ULONG cbInfoBuf) 
  7063.  
  7064.  Parameters 
  7065.  
  7066.  pszPathName  PSZ)  input 
  7067.            Address of the ASCIIZ file specification of the file or 
  7068.            subdirectory. 
  7069.  
  7070.            Global file-name characters can be used in the name only for level 5 
  7071.            file information. 
  7072.  
  7073.            DosQuerySysInfo is called by an application during initialization to 
  7074.            determine the maximum path length allowed by the operating system. 
  7075.  
  7076.  ulInfoLevel  ULONG)  input 
  7077.            The level of path information required. 
  7078.  
  7079.            Specify a value 
  7080.  
  7081.            1        FIL_STANDARD 
  7082.  
  7083.                     Level 1 file information 
  7084.  
  7085.            11       FIL_STANDARDL 
  7086.  
  7087.                     Level 11 file information 
  7088.  
  7089.            2        FIL_QUERYEASIZE 
  7090.  
  7091.                     Level 2 file information 
  7092.  
  7093.            12       FIL_QUERYEASIZEL 
  7094.  
  7095.                     Level 12 file information 
  7096.  
  7097.            3        FIL_QUERYEASFROMLIST 
  7098.  
  7099.                     Level 3 file information 
  7100.  
  7101.            5        FIL_QUERYFULLNAME 
  7102.  
  7103.                     Level 5 file information 
  7104.  
  7105.            Level 4 is reserved. 
  7106.  
  7107.            The structures described in pInfoBuf indicate the information 
  7108.            returned for each of these levels. 
  7109.  
  7110.  pInfoBuf  PVOID)  output 
  7111.            Address of the storage area containing the requested level of path 
  7112.            information. 
  7113.  
  7114.            Path information, where applicable, is based on the most recent 
  7115.            DosClose, DosResetBuffer, DosSetFileInfo, or DosSetPathInfo. 
  7116.  
  7117.            Level 1 File Information (ulInfoLevel == FIL_STANDARD) 
  7118.                    pInfoBuf contains the FILESTATUS3 data structure, in which 
  7119.                    path information is returned. 
  7120.  
  7121.            Level 11 File Information (ulInfoLevel == FIL_STANDARDL) 
  7122.                    pInfoBuf contains the FILESTATUS3L data structure, in which 
  7123.                    path information is returned. 
  7124.  
  7125.            Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) 
  7126.                    pInfoBuf contains the FILESTATUS4 data structure. This is 
  7127.                    similar to the Level 1 structure, with the addition of the 
  7128.                    cbList field after the attrFile field. 
  7129.  
  7130.                    The cbList field is an unsigned LONG On output, this field 
  7131.                    contains the size, in bytes, of the file s entire extended 
  7132.                    attribute (EA) set on disk. You can use this value to 
  7133.                    calculate the size of the buffer required to hold the EA 
  7134.                    information returned when a value of 3 is specified for 
  7135.                    ulInfoLevel. The buffer size is less than or equal to twice 
  7136.                    the size of the file s entire EA set on disk. 
  7137.  
  7138.            Level 12 File Information (ulInfoLevel == FIL_QUERYEASIZEL) 
  7139.                    pInfoBuf contains the FILESTATUS4L data structure. This is 
  7140.                    similar to the Level 1 structure, with the addition of the 
  7141.                    cbList field after the attrFile field. 
  7142.  
  7143.                    The cbList field is an unsigned ULONG On output, this field 
  7144.                    contains the size, in bytes, of the file s entire extended 
  7145.                    attribute (EA) set on disk. You can use this value to 
  7146.                    calculate the size of the buffer required to hold the EA 
  7147.                    information returned when a value of 3 is specified for 
  7148.                    ulInfoLevel. The buffer size is less than or equal to twice 
  7149.                    the size of the file s entire EA set on disk. 
  7150.  
  7151.            Level 3 File Information (ulInfoLevel == FIL_QUERYEASFROMLIST) 
  7152.                    This is a subset of the EA information of the file. 
  7153.  
  7154.                    Input        ulInfoLevel contains an EAOP2 data structure. 
  7155.                                 fpGEA2List points to a GEA2 that defines the 
  7156.                                 attribute names whose values are returned. The 
  7157.                                 GEA2 data structures must be aligned on a 
  7158.                                 doubleword boundary. Each oNextEntryOffset 
  7159.                                 field must contain the number of bytes from the 
  7160.                                 beginning of the current entry to the beginning 
  7161.                                 of the next entry in the GEA2 list. The 
  7162.                                 oNextEntryOffset field in the last entry of the 
  7163.                                 GEA2 list must be zero. fpFEA2List points to a 
  7164.                                 data area where the relevant FEA2  list is 
  7165.                                 returned. The length field of this FEA2 list is 
  7166.                                 valid, giving the size of the FEA2 list buffer. 
  7167.                                 oError is ignored. 
  7168.  
  7169.                    Output       pInfoBuf is unchanged. If an error occurs, 
  7170.                                 oError points to the GEA2 entry that caused the 
  7171.                                 error. The buffer pointed to by fpFEA2List is 
  7172.                                 filled in with the returned information. If the 
  7173.                                 buffer that fpFEA2List points to is not large 
  7174.                                 enough to hold the returned information (the 
  7175.                                 return code is ERROR_BUFFER_OVERFLOW), cbList 
  7176.                                 is still valid, assuming there is at least 
  7177.                                 enough space for it. Its value is the size, in 
  7178.                                 bytes, of the file s entire EA set on disk, 
  7179.                                 even though only a subset of attributes was 
  7180.                                 requested. The size of the buffer required to 
  7181.                                 hold the EA information is less than or equal 
  7182.                                 to twice the size of the file s entire EA set 
  7183.                                 on disk. 
  7184.  
  7185.            Level 5 File Information (ulInfoLevel == FIL_QUERYFULLNAME) 
  7186.                    Level 5 returns the fully-qualified ASCIIZ name of 
  7187.                    pszPathName in pInfoBuf. pszPathName may contain global 
  7188.                    file-name characters. 
  7189.  
  7190.  cbInfoBuf  ULONG)  input 
  7191.            The length, in bytes, of pInfoBuf. 
  7192.  
  7193.  Returns 
  7194.  
  7195.  ulrc  APIRET)  returns 
  7196.            Return Code. 
  7197.  
  7198.            DosQueryPathInfo returns one of the following values 
  7199.  
  7200.            0              NO_ERROR 
  7201.  
  7202.            3              ERROR_PATH_NOT_FOUND 
  7203.  
  7204.            32             ERROR_SHARING_VIOLATION 
  7205.  
  7206.            111            ERROR_BUFFER_OVERFLOW 
  7207.  
  7208.            124            ERROR_INVALID_LEVEL 
  7209.  
  7210.            206            ERROR_FILENAME_EXCED_RANGE 
  7211.  
  7212.            254            ERROR_INVALID_EA_NAME 
  7213.  
  7214.            255            ERROR_EA_LIST_INCONSISTENT 
  7215.  
  7216.  Remarks 
  7217.  
  7218.  In the FAT file system, only date and time information contained in Level 1 
  7219.  file information can be modified. Zero is returned for the creation and access 
  7220.  dates and times. 
  7221.  
  7222.  For DosQueryPathInfo to return information contained in any of the file 
  7223.  information levels, the file object must be opened for read access, with a 
  7224.  deny-write sharing mode specified for access by other processes. Thus, if the 
  7225.  file object is already accessed by another process that holds conflicting 
  7226.  sharing and access rights, a call to DosQueryPathInfo fails. 
  7227.  
  7228.  Related Functions 
  7229.  
  7230.      DosClose 
  7231.  
  7232.      DosCreateDir 
  7233.  
  7234.      DosEnumAttribute 
  7235.  
  7236.      DosOpen 
  7237.  
  7238.      DosOpenL 
  7239.  
  7240.      DosQueryFileInfo 
  7241.  
  7242.      DosResetBuffer 
  7243.  
  7244.      DosSetFileInfo 
  7245.  
  7246.      DosSetPathInfo 
  7247.  
  7248.  Example Code 
  7249.  
  7250.  The first example obtains information about the file  STARTUP.CMD.  The second 
  7251.  example obtains information about the directory  SYSTEM. 
  7252.  
  7253.   #define INCL_DOSFILEMGR   /* File Manager values */
  7254.   #define INCL_DOSERRORS    /* DOS error values    */
  7255.   #include  os2.h
  7256.   #include  stdio.h
  7257.  
  7258.   int main(VOID)
  7259.   UCHAR        uchFileName 80  = "C \\STARTUP.CMD";  /* File to manipulate    */
  7260.   FILESTATUS3L  fsts3ConfigInfo =   0  ;       /* Buffer for file information */
  7261.   ULONG        ulBufSize     = sizeof(FILESTATUS3L);  /* Size of above buffer */
  7262.   APIRET       rc            = NO_ERROR;      /* Return code                 */
  7263.  
  7264.   rc = DosQueryPathInfo(uchFileName,   /* Path and name of file           */
  7265.   FIL_STANDARDL,  /* Request standard (Level 11) info */
  7266.    fsts3ConfigInfo, /* Buffer for file information  */
  7267.   ulBufSize);    /* Size of buffer                  */
  7268.   if (rc != NO_ERROR)
  7269.   printf("DosQueryPathInfo error  return code = %u\n", rc);
  7270.   return 1;
  7271.  
  7272.  
  7273.   printf("%s ---  File size  %lld bytes\n",uchFileName, fsts3ConfigInfo.cbFile);
  7274.   printf("Last updated  %d/%d/%d; %d %2.2d\n",
  7275.   fsts3ConfigInfo.fdateLastWrite.month,        /* Month            */
  7276.   fsts3ConfigInfo.fdateLastWrite.day,          /* Day              */
  7277.   (fsts3ConfigInfo.fdateLastWrite.year+1980L), /* Years since 1980 */
  7278.   fsts3ConfigInfo.ftimeLastWrite.hours,        /* Hours            */
  7279.   fsts3ConfigInfo.ftimeLastWrite.minutes);     /* Minutes          */
  7280.  
  7281.   return NO_ERROR;
  7282.  
  7283.   #define INCL_DOSFILEMGR   /* File Manager values */
  7284.   #define INCL_DOSERRORS    /* DOS error values    */
  7285.   #include  os2.h
  7286.   #include  stdio.h
  7287.  
  7288.   int main(VOID)
  7289.   UCHAR        uchPathName 255  = "C \\OS2\\SYSTEM"; /* Path of interest     */
  7290.   FILESTATUS3L  fsts3ConfigInfo =   0  ;       /* Buffer for path information */
  7291.   ULONG        ulBufSize     = sizeof(FILESTATUS3L);  /* Size of above buffer */
  7292.   APIRET       rc            = NO_ERROR;      /* Return code                 */
  7293.  
  7294.   rc = DosQueryPathInfo(uchPathName,   /* Name of path                    */
  7295.   FIL_STANDARDL,  /* Request standard (Level 11) info */
  7296.    fsts3ConfigInfo, /* Buffer for information       */
  7297.   ulBufSize);       /* Size of buffer               */
  7298.   if (rc != NO_ERROR)
  7299.   printf("DosQueryPathInfo error  return code = %u\n", rc);
  7300.   return 1;
  7301.  
  7302.  
  7303.   printf("Information for subdirectory  %s \n",uchPathName);
  7304.   printf("Last updated  %d/%d/%d; %d %2.2d\n",
  7305.   fsts3ConfigInfo.fdateLastWrite.month,        /* Month            */
  7306.   fsts3ConfigInfo.fdateLastWrite.day,          /* Day              */
  7307.   (fsts3ConfigInfo.fdateLastWrite.year+1980L), /* Years since 1980 */
  7308.   fsts3ConfigInfo.ftimeLastWrite.hours,        /* Hours            */
  7309.   fsts3ConfigInfo.ftimeLastWrite.minutes);     /* Minutes          */
  7310.  
  7311.   return NO_ERROR;
  7312.  
  7313.  
  7314. ΓòÉΓòÉΓòÉ 5.28. DosQuerySysInfo ΓòÉΓòÉΓòÉ
  7315.  
  7316. Purpose 
  7317.  
  7318. DosQuerySysInfo returns values of static system variables. 
  7319.  
  7320. Syntax 
  7321.  
  7322. #define INCL DOSMISC
  7323. #include   os2.h
  7324.  
  7325.  APIRET DosQuerySysInfo (ULONG iStart, ULONG iLast, PVOID pBuf, ULONG cbBuf) 
  7326.  
  7327.  Parameters 
  7328.  
  7329.  iStart  ULONG)  input 
  7330.            Ordinal of the first system variable to return. 
  7331.  
  7332.  iLast  ULONG)  input 
  7333.            Ordinal of the last system variable to return. 
  7334.  
  7335.  pBuf  PVOID)  output 
  7336.            Address of the data buffer where the system returns the variable 
  7337.            values. 
  7338.  
  7339.  cbBuf  ULONG)  input 
  7340.            Length, in bytes, of the data buffer. 
  7341.  
  7342.  Returns 
  7343.  
  7344.  ulrc  APIRET)  returns 
  7345.            Return Code. 
  7346.  
  7347.            DosQuerySysInfo returns one of the following values 
  7348.  
  7349.            0              NO_ERROR 
  7350.  
  7351.            87             ERROR_INVALID_PARAMETER 
  7352.  
  7353.            111            ERROR_BUFFER_OVERFLOW 
  7354.  
  7355.  Remarks 
  7356.  
  7357.  DosQuerySysInfo returns a single system variable or a range of system 
  7358.  variables to a user-allocated buffer. To request a single system variable, set 
  7359.  iStart equal to iLast. To request a range of system variables, set iStart less 
  7360.  than iLast. 
  7361.  
  7362.  Each system variable is a ULONG value. The following list gives the ordinal 
  7363.  index, name, and description of the system variables. 
  7364.  
  7365.  1   QSV_MAX_PATH_LENGTH 
  7366.  
  7367.      Maximum length, in bytes, of a path name. 
  7368.  
  7369.  2   QSV_MAX_TEXT_SESSIONS 
  7370.  
  7371.      Maximum number of text sessions. 
  7372.  
  7373.  3   QSV_MAX_PM_SESSIONS 
  7374.  
  7375.      Maximum number of PM sessions. 
  7376.  
  7377.  4   QSV_MAX_VDM_SESSIONS 
  7378.  
  7379.      Maximum number of DOS sessions. 
  7380.  
  7381.  5   QSV_BOOT_DRIVE 
  7382.  
  7383.      Drive from which the system was started (1 means drive A, 2 means drive B, 
  7384.      and so on). 
  7385.  
  7386.  6   QSV_DYN_PRI_VARIATION 
  7387.  
  7388.      Dynamic priority variation flag (0 means absolute priority, 1 means 
  7389.      dynamic priority). 
  7390.  
  7391.  7   QSV_MAX_WAIT 
  7392.  
  7393.      Maximum wait in seconds. 
  7394.  
  7395.  8   QSV_MIN_SLICE 
  7396.  
  7397.      Minimum time slice in milliseconds. 
  7398.  
  7399.  9   QSV_MAX_SLICE 
  7400.  
  7401.      Maximum time slice in milliseconds. 
  7402.  
  7403.  10  QSV_PAGE_SIZE 
  7404.  
  7405.      Memory page size in bytes. This value is 4096 for the 80386 processor. 
  7406.  
  7407.  11  QSV_VERSION_MAJOR 
  7408.  
  7409.      Major version number (see note below). 
  7410.  
  7411.  12  QSV_VERSION_MINOR 
  7412.  
  7413.      Minor version number (see note below). 
  7414.  
  7415.  13  QSV_VERSION_REVISION 
  7416.  
  7417.      Revision number (see note below). 
  7418.  
  7419.  14  QSV_MS_COUNT 
  7420.  
  7421.      Value of a 32-bit, free-running millisecond counter. This value is zero 
  7422.      when the system is started. 
  7423.  
  7424.  15  QSV_TIME_LOW 
  7425.  
  7426.      Low-order 32 bits of the time in seconds since January 1, 1970 at 0 00 00. 
  7427.  
  7428.  16  QSV_TIME_HIGH 
  7429.  
  7430.      High-order 32 bits of the time in seconds since January 1, 1970 at 0 00 
  7431.      00. 
  7432.  
  7433.  17  QSV_TOTPHYSMEM 
  7434.  
  7435.      Total number of bytes of physical memory in the system. 
  7436.  
  7437.  18  QSV_TOTRESMEM 
  7438.  
  7439.      Total number of bytes of resident memory in the system. 
  7440.  
  7441.  19  QSV_TOTAVAILMEM 
  7442.  
  7443.      Maximum number of bytes of memory that can be allocated by all processes 
  7444.      in the system. This number is advisory and is not guaranteed, since system 
  7445.      conditions change constantly. 
  7446.  
  7447.  20  QSV_MAXPRMEM 
  7448.  
  7449.      Maximum number of bytes of memory that this process can allocate in its 
  7450.      private arena. This number is advisory and is not guaranteed, since system 
  7451.      conditions change constantly. 
  7452.  
  7453.  21  QSV_MAXSHMEM 
  7454.  
  7455.      Maximum number of bytes of memory that a process can allocate in the 
  7456.      shared arena. This number is advisory and is not guaranteed, since system 
  7457.      conditions change constantly. 
  7458.  
  7459.  22  QSV_TIMER_INTERVAL 
  7460.  
  7461.      Timer interval in tenths of a millisecond. 
  7462.  
  7463.  23  QSV_MAX_COMP_LENGTH 
  7464.  
  7465.      Maximum length, in bytes, of one component in a path name. 
  7466.  
  7467.  24  QSV_FOREGROUND_FS_SESSION 
  7468.  
  7469.      Session ID of the current foreground full-screen session. Note that this 
  7470.      only applies to full-screen sessions. The Presentation Manager session 
  7471.      (which displays Vio-windowed, PM, and windowed DOS Sessions) is 
  7472.      full-screen session ID 1. 
  7473.  
  7474.  25  QSV_FOREGROUND_PROCESS 
  7475.  
  7476.      Process ID of the current foreground process. 
  7477.  
  7478.  26  QSV_NUMPROCESSORS 
  7479.  
  7480.      Number of processors in the machine 
  7481.  
  7482.  27  QSV_MAXHPRMEM 
  7483.  
  7484.      Maximum amount of free space in process's high private arena. Because 
  7485.      system conditions change constantly, this number is advisory and is not 
  7486.      guaranteed.  In addition, this number does not indicate the largest single 
  7487.      memory object you can allocate because the arena may be fragmented. 
  7488.  
  7489.  28  QSV_MAXHSHMEM 
  7490.  
  7491.      Maximum amount of free space in process's high shared arena. Because 
  7492.      system conditions change constantly, this number is advisory and is not 
  7493.      guaranteed. In addition, this number does not indicate the largest single 
  7494.      memory object you can allocate because the arena may be fragmented. 
  7495.  
  7496.  29  QSV_MAXPROCESSES 
  7497.  
  7498.      Maximum number of concurrent processes supported. 
  7499.  
  7500.  30  QSV_VIRTUALADDRESSLIMIT 
  7501.  
  7502.      Size of the user's address space in megabytes (that is, the value of the 
  7503.      rounded VIRTUALADDRESSLIMIT) 
  7504.  
  7505.  30  QSV_MAX 
  7506.  
  7507.  Note:  Major, minor and revision numbers for versions of OS/2 operating system 
  7508.         are described below 
  7509.  
  7510.                   Major           Minor           Revision
  7511.   OS/2 2.0        20              00              0
  7512.   OS/2 2.1        20              10              0
  7513.   OS/2 2.11       20              11              0
  7514.   OS/2 3.0        20              30              0
  7515.   OS/2 4.0        20              40              0
  7516.  
  7517.  An application can specify file objects managed by an installable file system 
  7518.  that supports long file names.  Because some installable file systems support 
  7519.  longer names than others, the application should issue DosQuerySysInfo upon 
  7520.  initialization. 
  7521.  
  7522.  DosQuerySysInfo returns the maximum path length (QSV_MAX_PATH_LENGTH) 
  7523.  supported by the installed file system. The path length includes the drive 
  7524.  specifier (d ), the leading backslash (  ), and the trailing null character. 
  7525.  The value returned by DosQuerySysInfo can be used to allocate buffers for path 
  7526.  names returned by other functions, for example, DosFindFirst and DosFindNext. 
  7527.  
  7528.  Related Functions 
  7529.  
  7530.      DosCreateDir 
  7531.  
  7532.      DosFindFirst 
  7533.  
  7534.      DosFindNext 
  7535.  
  7536.      DosOpen 
  7537.  
  7538.      DosQueryCurrentDir 
  7539.  
  7540.      DosQueryFSInfo 
  7541.  
  7542.      DosQueryPathInfo 
  7543.  
  7544.      DosSearchPath 
  7545.  
  7546.      DosSetCurrentDir 
  7547.  
  7548.      DosSetPathInfo 
  7549.  
  7550.      DosSetFSInfo 
  7551.  
  7552.  Example Code 
  7553.  
  7554.  This example queries and displays the maximum length for a path name and the 
  7555.  total amount of physical memory in bytes. 
  7556.  
  7557.   #define INCL_DOSMISC       /* DOS Miscellaneous values */
  7558.   #define INCL_DOSERRORS     /* DOS Error values         */
  7559.   #include  os2.h
  7560.   #include  stdio.h
  7561.  
  7562.   int main(VOID)
  7563.  
  7564.   ULONG   aulSysInfo QSV_MAX  =  0 ;       /* System Information Data Buffer */
  7565.   APIRET  rc                  = NO_ERROR;  /* Return code                    */
  7566.  
  7567.   rc = DosQuerySysInfo(1L,                 /* Request all available system   */
  7568.   QSV_MAX,            /* information                    */
  7569.   (PVOID)aulSysInfo,
  7570.   sizeof(ULONG)*QSV_MAX);
  7571.  
  7572.   if (rc != NO_ERROR)
  7573.   printf("DosQuerySysInfo error  return code = %u\n", rc);
  7574.   return 1;
  7575.     else
  7576.   printf("Maximum length for a path name is %u characters.\n",
  7577.   aulSysInfo QSV_MAX_PATH_LENGTH-1 );  /* Max length of path name */
  7578.  
  7579.   printf("Total physical memory is %u bytes.\n",
  7580.   aulSysInfo QSV_TOTPHYSMEM-1 );       /* Total physical memory   */
  7581.     /* endif */
  7582.  
  7583.   return NO_ERROR;
  7584.  
  7585.  
  7586. ΓòÉΓòÉΓòÉ 5.29. DosQuerySysState ΓòÉΓòÉΓòÉ
  7587.  
  7588. Purpose 
  7589.  
  7590. DosQuerySysState returns information about various resources in use by the 
  7591. system. The EntityList parameter determines which information is returned 
  7592. according to the bits set in this parameter. 
  7593.  
  7594. Syntax 
  7595.  
  7596. #define INCL_DOSPROFILE
  7597. #define INCL_DOSERRORS
  7598. #include  os2.h>
  7599.  
  7600.  APIRET APIENTRY DosQuerySysState (ULONG EntityList, ULONG EntityLevel, PID 
  7601.            pid, TID tid, PVOID pDataBuf, ULONG cbBuf) 
  7602.  
  7603.  Parameters 
  7604.  
  7605.  EntityList (ULONG)  input 
  7606.            Determines what information is returned. May be a combination of the 
  7607.            following 
  7608.  
  7609.            QS_PROCESS     0x0001 Requests process information 
  7610.  
  7611.            QS_SEMAPHORE   0x0002 Requests semaphore information 
  7612.  
  7613.            QS_MTE         0x0004 Requests module information 
  7614.  
  7615.            QS_FILESYS     0x0008 Requests file system information 
  7616.  
  7617.            QS_SHMEMORY    0x0010 Requests shared memory information 
  7618.  
  7619.            QS_MODVER      0x0200 Requests module version information 
  7620.  
  7621.  EntityLevel (ULONG)  input 
  7622.            Determines the extent of information returned for a given entity. 
  7623.            This applies to QS_MTE entities only. If EntityLevel is also set to 
  7624.            SQ_MTE, then module object information is returned. 
  7625.  
  7626.  pid (PID)  input 
  7627.            Restricts information to a particular process ID. If 0 is specified, 
  7628.            then entities for all processes are returned. 
  7629.  
  7630.  tid (TID)  input 
  7631.            Restricts information to a particular thread ID. A value of zero 
  7632.            only is supported, requesting all threads of a process. 
  7633.  
  7634.  pDataBuf (PVOID)  output 
  7635.            Pointer to the buffer allocated by the user into which entity 
  7636.            structures are returned. If the buffer is of insufficient size, then 
  7637.            an ERROR_BUFFER_OVERFLOW is returned. 
  7638.  
  7639.  cbBuf (ULONG)  input 
  7640.            Size of the buffer pointed to by pDataBuf in bytes. 
  7641.  
  7642.  Returns 
  7643.  
  7644.  ulrc (APIRET)  returns 
  7645.            Return Code. 
  7646.  
  7647.            DosQuerySysState returns one of the following values 
  7648.  
  7649.            0              NO_ERROR 
  7650.  
  7651.            87             ERROR_INVALID_PARAMETER 
  7652.  
  7653.            111            ERROR_BUFFER_OVERFLOW 
  7654.  
  7655.            115            ERROR_PROTECTION_VIOLATION 
  7656.  
  7657.            124            ERROR_INVALID_LEVEL 
  7658.  
  7659.  Remarks 
  7660.  
  7661.  The information returned by DosQuerySysState begins with a pointer to the 
  7662.  global record structure, qsGrec_s. Following this will be a series of other 
  7663.  records which depend on what information was requested. Some of these 
  7664.  subsequent record structures contain an identifier as their first member, 
  7665.  which enables the returned information to be interpreted without any order 
  7666.  being imposed. 
  7667.  
  7668.   Entities that may be requested are 
  7669.  
  7670.  Process information QS_PROCESS 
  7671.  
  7672.  Semaphore information QS_SEMAPHORE 
  7673.  
  7674.  Module information QS_MTE 
  7675.  
  7676.  File system information QS_FILESYS 
  7677.  
  7678.  Shared memory information QS_SHMEMORY 
  7679.  
  7680.  Module Version information QS_MODVER 
  7681.  Not all entities have been supported in earlier versions of OS/2.
  7682.  
  7683.  The structures returned will be a combination of the following 
  7684.  
  7685.  qsGrec_t  Global Record structure 
  7686.  
  7687.  qsTrec_t  Thread Record structure 
  7688.  
  7689.  qsPrec_t  Process Record structure 
  7690.  
  7691.  qsS16rec_t 16 bit system semaphore structure 
  7692.  
  7693.  qsS16Headrec_t 16 bit system semaphore structure 
  7694.  
  7695.  qsMrec_t  Shared Memory Record structure 
  7696.  
  7697.  QSOPENQ   32 bit Open Semaphore structure 
  7698.  
  7699.  QSEVENT   32 bit Event Semaphore structure 
  7700.  
  7701.  QSMUTEX   32 bit Mutex semaphore structure 
  7702.  
  7703.  QSMUX     32 bit Mux semaphore structure 
  7704.  
  7705.  QSHUN     32 bit semaphore header structure 
  7706.  
  7707.  qsS32rec_t 32 bit semaphore header structure 
  7708.  
  7709.  qsLObjrec_t Object level MTE information 
  7710.  
  7711.  qsLrec_t  System wide MTE information 
  7712.  
  7713.  qsExLrec_t Module version information 
  7714.  
  7715.  qsSft_t   System wide FILE information one per open instance 
  7716.  
  7717.  qsFrec_t  System wide FILE information one per file name 
  7718.  
  7719.  qsPtrRec_t System wide FILE information 
  7720.  
  7721.  Related Functions 
  7722.  
  7723.      DosQueryMemState 
  7724.  
  7725.      DosQuerySysInfo 
  7726.  
  7727.  Example Code 
  7728.  
  7729.   #define BUFSIZE 64*1024
  7730.   int main(int argc, char *argv[], char *envp[])
  7731.   {
  7732.      APIRET rc;
  7733.      qsGrec_t ** pBuf;
  7734.      qsGrec_t * pGrec;
  7735.      qsLrec_t * pLrec;
  7736.  
  7737.  
  7738.      pBuf=malloc(BUFSIZE); /* allocate a 64K buffer */
  7739.      if (pBuf == NULL) {
  7740.         printf("Not enough memoryan");
  7741.         return ERROR_NOT_ENOUGH_MEMORY;
  7742.      } /* endif */
  7743.  
  7744.      /* query module information */
  7745.  
  7746.      rc=DosQuerySysState(QS_MTE, 0L, 0L, 0L, pBuf, BUFSIZE);
  7747.      if (rc!=0) {
  7748.         printf("DosQuerySysState returned rc=%u\n",rc);
  7749.         return rc;
  7750.      } /* endif */
  7751.  
  7752.      pGrec = *  pBuf;
  7753.  
  7754.      printf("Threads=%u 32-bit Sems=%u File Names=%u\n\n",
  7755.                   pGrec->cThrds,
  7756.                   pGrec->c32SSem,
  7757.                   pGrec->cMFTNodes);
  7758.  
  7759.      pLrec = (ULONG)pGrec + sizeof(qsGrec_t);
  7760.  
  7761.      while (pLrec) {
  7762.         if (pLrec->pName) printf("hmte=%04x %s\n", pLrec->hmte, pLrec->pName);
  7763.         pLrec = pLrec->pNextRec;
  7764.      } /* endwhile */
  7765.  
  7766.      return rc;
  7767.   }
  7768.  
  7769.  
  7770. ΓòÉΓòÉΓòÉ 5.30. DosQueryThreadAffinity ΓòÉΓòÉΓòÉ
  7771.  
  7772. Purpose 
  7773.  
  7774. DosQueryThreadAffinity allows a thread to inquire for the current thread's 
  7775. processor affinity mask and the system's capable processor affinity mask. 
  7776.  
  7777. Syntax 
  7778.  
  7779.  APIRET DosQueryThreadAffinity (ULONG scope, PMPAffinity pAffinityMask) 
  7780.  
  7781.  Parameters 
  7782.  
  7783.  scope(ULONG)  input 
  7784.  
  7785.            AFNTY_THREAD   Return the current threads processor affinity mask. 
  7786.  
  7787.            AFNTY_SYSTEM   Return the system's current capable processor 
  7788.                           affinity mask. 
  7789.  
  7790.  pAffinityMask(PMPAffinity)  input 
  7791.            Address of MPAffinity structure to receive the affinity mask. 
  7792.            Processors 0 31 are in mask [0] and processors 32 63 are in mask 
  7793.            [1]. 
  7794.  
  7795.  Returns 
  7796.  
  7797.  ulrc  APIRET)  returns 
  7798.            Return Code. 
  7799.  
  7800.            DosQueryThreadAffinity returns one of the following values 
  7801.  
  7802.            13             ERROR_INVALID_DATA 
  7803.  
  7804.            87             ERROR_INVALID_PARAMETER 
  7805.  
  7806.  Remarks 
  7807.  
  7808.  DosQueryThreadAffinity allows a thread to ask the Processor Affinity Mask for 
  7809.  
  7810.    1. The current thread's processor affinity mask, scope =AFNTY_THREAD, 
  7811.       returns qwThreadAffinity, for the calling thread. 
  7812.  
  7813.    2. The system's capable processor affinity mask, scope=AFNTY_SYSTEM, returns 
  7814.       qwCapableAffinity for the system. The caller may then use any subset of 
  7815.       the returned affinity mask to change the threads processor affinity in a 
  7816.       later call to DosSetThreadAffinity. 
  7817.  
  7818.  Related Functions 
  7819.  
  7820.      DosSetThreadAffinity 
  7821.  
  7822.  Example Code 
  7823.  
  7824.   #define INCL_DOS
  7825.   #define INCL_32
  7826.   #define INCL_DOSERRORS
  7827.   #define INCL_NOPMAPI
  7828.   #include  os2.h>
  7829.   #include  stdio.h>
  7830.  
  7831.   int main(void) {
  7832.   APIRET rc;
  7833.   MPAFFINITY affinity;
  7834.  
  7835.   rc = DosQueryThreadAffinity(AFNTY_SYSTEM,  affinity);
  7836.   printf("Query system's affinity  rc = %08.8xh\n",rc);
  7837.   printf("Query system's affinity  affinity[0] = %08.8xh, affinity[1] = %08.8xh\n",
  7838.           affinity.mask[0], affinity.mask[1]);
  7839.   return rc;
  7840.   }
  7841.  
  7842.  
  7843. ΓòÉΓòÉΓòÉ 5.31. DosRead ΓòÉΓòÉΓòÉ
  7844.  
  7845. Purpose 
  7846.  
  7847. DosRead reads the specified number of bytes from a disk to a buffered location. 
  7848.  
  7849. Syntax 
  7850.  
  7851. #define INCL_DOSFILEMGR
  7852. #include  os2.h>
  7853.  
  7854.  APIRET DosRead (HFILE hf, PVOID pBuffer,  ULONG cbRead, PULONG pcbActual) 
  7855.  
  7856.  Parameters 
  7857.  
  7858.  hFile (HFILE)  input 
  7859.            File handle obtained from DosOpen. 
  7860.  
  7861.  pBuffer (PVOID)  output 
  7862.            Address of the buffer to receive the bytes read. 
  7863.  
  7864.  cbRead (ULONG)  input 
  7865.            The number of bytes to be read into pBuffer. This must be a multiple 
  7866.            of the sector size (512) for the raw file system. 
  7867.  
  7868.  pcbActual (PULONG)  output 
  7869.            Address of the variable to receive the number of bytes actually 
  7870.            read. 
  7871.  
  7872.  Returns 
  7873.  
  7874.  ulrc (APIRET)  returns 
  7875.            Return Code. 
  7876.  
  7877.            DosRead returns one of the following values 
  7878.  
  7879.            0              NO_ERROR 
  7880.  
  7881.            5               ERROR_ACCESS_DENIED 
  7882.  
  7883.            6              ERROR_INVALID_HANDLE 
  7884.  
  7885.            26             ERROR_NOT_DOS_DISK 
  7886.  
  7887.            33             ERROR_LOCK_VIOLATION 
  7888.  
  7889.            109            ERROR_BROKEN_PIPE 
  7890.  
  7891.            234            ERROR_MORE_DATA 
  7892.  
  7893.  Remarks 
  7894.  
  7895.  DosRead begins reading from the current file pointer position. The file 
  7896.  pointer is updated by reading the data. 
  7897.  
  7898.  The requested number of bytes might not be read. If the value returned in 
  7899.  pcbActual is less than requested, the process tried to read past the end of 
  7900.  the disk. 
  7901.  
  7902.  A value of zero for cbRead is not considered an error. It is treated as a null 
  7903.  operation. 
  7904.  
  7905.  Using the raw file system on logical partitions requires you to lock and 
  7906.  unlock the volume using the DosDevIOCtl Category 8, DSK_LOCKDRIVE and 
  7907.  DSK_UNLOCKDRIVE. Reads and writes will not succeed until the logical drive is 
  7908.  locked. 
  7909.  
  7910.  The raw file system requires that the number of bytes read be a multiple of 
  7911.  the sector size (512). 
  7912.  
  7913.  Related Functions 
  7914.  
  7915.      DosOpen 
  7916.  
  7917.      DosListIO 
  7918.  
  7919.      DosSetFilePtr 
  7920.  
  7921.      DosWrite 
  7922.  
  7923.  Example Code 
  7924.  
  7925.  The following is NOT a complete usable program.  It is simply intended to 
  7926.  provide an idea of how to use Raw I/O File System APIs (e.g. DosOpen, DosRead, 
  7927.  DosWrite, DosSetFilePtr, and DosClose). 
  7928.  
  7929.  This example opens physical disk #1 for reading and physical disk #2  for 
  7930.  writing.  DosSetFilePtr is used to set the pointer to the beginning of the 
  7931.  disks. Using DosRead and DosWrite, 10 megabytes of data is transferred from 
  7932.  disk #1 to disk #2. Finally, DosClosed is issued to close the disk handles. 
  7933.  
  7934.  It is assumed that the size of each of the two disks is at least 10 megabytes. 
  7935.  
  7936.   #define INCL_DOSFILEMGR          /* Include File Manager APIs */
  7937.   #define INCL_DOSMEMMGR           /* Includes Memory Management APIs */
  7938.   #define INCL_DOSERRORS           /* DOS Error values */
  7939.   #include  os2.h>
  7940.   #include  stdio.h>
  7941.   #include  string.h>
  7942.  
  7943.   #define SIXTY_FOUR_K 0x10000
  7944.   #define ONE_MEG     0x100000
  7945.   #define TEN_MEG     10*ONE_MEG
  7946.  
  7947.   #define UNC_DISK1  "\\\\.\\Physical_Disk1"
  7948.   #define UNC_DISK2  "\\\\.\\Physical_Disk2"
  7949.  
  7950.   int main(void) {
  7951.      HFILE  hfDisk1        = 0;      /* Handle for disk #1 */
  7952.      HFILE  hfDisk2        = 0;      /* Handle for disk #2 */
  7953.      ULONG  ulAction       = 0;      /* Action taken by DosOpen */
  7954.      ULONG  cbRead         = 0;      /* Bytes to read */
  7955.      ULONG  cbActualRead   = 0;      /* Bytes read by DosRead */
  7956.      ULONG  cbWrite        = 0;      /* Bytes to write */
  7957.      ULONG  ulLocation     = 0;
  7958.      ULONG  cbActualWrote  = 0;      /* Bytes written by DosWrite */
  7959.      UCHAR  uchFileName1[20]  = UNC_DISK1, /* UNC Name of disk 1 */
  7960.             uchFileName2[20]  = UNC_DISK2; /* UNC Name of disk 2 */
  7961.      PBYTE  pBuffer        = 0;
  7962.      ULONG  cbTotal        = 0;
  7963.  
  7964.      APIRET rc             = NO_ERROR;            /* Return code */
  7965.  
  7966.      /* Open a raw file system disk #1 for reading */
  7967.      rc = DosOpen(uchFileName1,               /* File name */
  7968.                    hfDisk1,                   /* File handle */
  7969.                    ulAction,                  /* Action taken by DosOpen */
  7970.                   0L,                         /* no file size */
  7971.                   FILE_NORMAL,                /* File attribute */
  7972.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  7973.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  7974.                   OPEN_ACCESS_READONLY,
  7975.                   0L);                        /* No extented attributes */
  7976.      if (rc != NO_ERROR) {
  7977.         printf("DosOpen error rc = %u\n", rc);
  7978.         return(1);
  7979.      } /* endif */
  7980.  
  7981.      /* Set the pointer to the begining of the disk */
  7982.      rc = DosSetFilePtr(hfDisk1,      /* Handle for disk 1 */
  7983.                         0L,           /* Offset must be multiple of 512 */
  7984.                         FILE_BEGIN,   /* Begin of the disk */
  7985.                          ulLocation); /* New pointer location */
  7986.      if (rc != NO_ERROR) {
  7987.         printf("DosSetFilePtr error rc = %u\n", rc);
  7988.         return(1);
  7989.      } /* endif */
  7990.  
  7991.      /* Open a raw file system disk #2 for writing */
  7992.      rc = DosOpen(uchFileName2,               /* File name */
  7993.                    hfDisk2,                   /* File handle */
  7994.                    ulAction,                  /* Action taken by DosOpen */
  7995.                   0L,                         /* no file size */
  7996.                   FILE_NORMAL,                /* File attribute */
  7997.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  7998.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  7999.                   OPEN_ACCESS_READWRITE,
  8000.                   0L);                        /* No extented attributes */
  8001.      if (rc != NO_ERROR) {
  8002.         printf("DosOpen error rc = %u\n", rc);
  8003.         return(1);
  8004.      } /* endif */
  8005.  
  8006.      /* Set the pointer to the begining of the disk */
  8007.      rc = DosSetFilePtr(hfDisk2,      /* Handle for disk 1 */
  8008.                         0L,           /* Offset must be multiple of 512 */
  8009.                         FILE_BEGIN,   /* Begin of the disk */
  8010.                          ulLocation); /* New pointer location */
  8011.      if (rc != NO_ERROR) {
  8012.         printf("DosSetFilePtr error rc = %u\n", rc);
  8013.         return(1);
  8014.      } /* endif */
  8015.  
  8016.  
  8017.      /* Allocate 64K of memory for transfer operations */
  8018.      rc = DosAllocMem((PPVOID) pBuffer, /* Pointer to buffer */
  8019.                        SIXTY_FOUR_K,      /* Buffer size */
  8020.                        PAG_COMMIT |     /* Allocation flags */
  8021.                        PAG_READ |
  8022.                        PAG_WRITE);
  8023.      if (rc != NO_ERROR) {
  8024.         printf("DosAllocMem error rc = %u\n", rc);
  8025.         return(1);
  8026.      } /* endif */
  8027.  
  8028.      cbRead = SIXTY_FOUR_K;
  8029.      while (rc == NO_ERROR    cbTotal   TEN_MEG) {
  8030.  
  8031.         /* Read from #1 */
  8032.         rc = DosRead(hfDisk1,         /* Handle for disk 1 */
  8033.                      pBuffer,         /* Pointer to buffer */
  8034.                      cbRead,          /* Size must be multiple of 512 */
  8035.                       cbActualRead);  /* Actual read by DosOpen */
  8036.         if (rc) {
  8037.            printf("DosRead error  return code = %u\n", rc);
  8038.            return 1;
  8039.         }
  8040.  
  8041.         /* Write to disk #2 */
  8042.         cbWrite = cbActualRead;
  8043.         rc = DosWrite(hfDisk2,         /* Handle for disk 2 */
  8044.                       pBuffer,         /* Pointer to buffer */
  8045.                       cbWrite,         /* Size must be multiple of 512 */
  8046.                        cbActualWrote); /* Actual written by DosOpen */
  8047.         if (rc) {
  8048.            printf("DosWrite error  return code = %u\n", rc);
  8049.            return 1;
  8050.         }
  8051.         if (cbActualRead != cbActualWrote) {
  8052.            printf("Bytes read (%u) does not equal bytes written (%u)\n",
  8053.                   cbActualRead, cbActualWrote);
  8054.            return 1;
  8055.         }
  8056.         cbTotal += cbActualRead; /* Update total transferred */
  8057.      }
  8058.  
  8059.      printf("Transfer successfully %d bytes from disk #1 to disk #2.\n",
  8060.             cbTotal);
  8061.  
  8062.      /* Free allocated memmory */
  8063.      rc = DosFreeMem(pBuffer);
  8064.      if (rc != NO_ERROR) {
  8065.         printf("DosFreeMem error  return code = %u\n", rc);
  8066.         return 1;
  8067.      }
  8068.  
  8069.      rc = DosClose(hfDisk1);
  8070.      if (rc != NO_ERROR) {
  8071.         printf("DosClose error  return code = %u\n", rc);
  8072.         return 1;
  8073.      }
  8074.  
  8075.      rc = DosClose(hfDisk2);
  8076.      if (rc != NO_ERROR) {
  8077.         printf("DosClose error  return code = %u\n", rc);
  8078.         return 1;
  8079.      }
  8080.   return NO_ERROR;
  8081.   }
  8082.  
  8083.  
  8084. ΓòÉΓòÉΓòÉ 5.32. DosReplaceModule ΓòÉΓòÉΓòÉ
  8085.  
  8086. Purpose 
  8087.  
  8088. DosReplaceModule replaces or caches a module that is in use. 
  8089.  
  8090. Syntax 
  8091.  
  8092. #define INCL_DOSMEMMGR
  8093. #include  os2.h>
  8094.  
  8095.  APIRET APIENTRY DosReplaceModule (PSZ pszOldModule, PSZ pszNewModule, PSZ 
  8096.            pszBackupModule) 
  8097.  
  8098.  Parameters 
  8099.  
  8100.  pszOldModule (PSZ)  input 
  8101.            Points to the name of the existing module. Required. 
  8102.  
  8103.  pszNewModule (PSZ)  input 
  8104.            Points to the name of the new module. Optional. 
  8105.  
  8106.  pszBackupModule (PSZ)  input 
  8107.            Points to the name to be used for saving a copy of the old module. 
  8108.            Optional. 
  8109.  
  8110.  Returns 
  8111.  
  8112.  ulrc (APIRET)  returns 
  8113.            Return Code. 
  8114.  
  8115.            DosReplaceModule returns one of the following values 
  8116.  
  8117.            0              NO_ERROR 
  8118.  
  8119.            2              ERROR_FILE_NOT_FOUND 
  8120.  
  8121.            3              ERROR_PATH_NOT_FOUND 
  8122.  
  8123.            5              ERROR_ACCESS_DENIED 
  8124.  
  8125.            17             ERROR_NOT_THE_SAME_DEVICE 
  8126.  
  8127.            26             ERROR_NOT_DOS_DISK 
  8128.  
  8129.            32             ERROR_SHARING VIOLATION 
  8130.  
  8131.            87             ERROR_INVALID_PARAMETER 
  8132.  
  8133.            108            ERROR_DRIVE_LOCKED 
  8134.  
  8135.            112            ERROR_DISK_FULL 
  8136.  
  8137.            267            ERROR_DIRECTORY 
  8138.  
  8139.            296            ERROR_MODULE_IN_USE 
  8140.  
  8141.            731            ERROR_MODULE_CORRUPTED 
  8142.  
  8143.  Remarks 
  8144.  
  8145.  When a DLL or EXE file is in use by the system, the file is locked. It cannot, 
  8146.  therefore, be replaced on the harddisk by a newer copy. DosReplaceModule 
  8147.  allows the replacement on the disk of the module while the system continues to 
  8148.  run the old module. The contents of the old module file are cached in the swap 
  8149.  file by the system and the load module file is closed. A backup copy of the 
  8150.  file may be created for recovery purposes should the install program fail. If 
  8151.  a backup module is not specified, then no backup will be made. The new module 
  8152.  takes the place of the original module on the disk. 
  8153.  
  8154.  Note:  The system will continue to use the cached old module until all 
  8155.         references to it are released. The next reference to the module will 
  8156.         cause a reload from the new module on disk. If a new module is not 
  8157.         specified, then the old module file will be cached and the file closed. 
  8158.  
  8159.  Protect mode executable files only can be replaced by DosReplaceModule. It 
  8160.  cannot be used for DOS/Windows(R) programs or for data files. 
  8161.  
  8162.  Related Functions 
  8163.  
  8164.      DosLoadModule 
  8165.  
  8166.      DosCopy 
  8167.  
  8168.  Example Code 
  8169.  
  8170.   int main(int argc, char *argv[], char *envp[])
  8171.  
  8172.   {
  8173.      APIRET rc=0;
  8174.      PSZ pszOld;
  8175.      PSZ pszNew = NULL;
  8176.      PSZ pszBak = NULL;
  8177.  
  8178.      if (argc==1) {
  8179.         printf("REPMOD oldmod  \n");
  8180.         return rc;
  8181.      }
  8182.  
  8183.      if (argc>1) pszOld = argv[1];
  8184.      if (argc>2) pszNew = argv[2];
  8185.      if (argc>3) pszBak = argv[3];
  8186.  
  8187.      rc = DosReplaceModule(pszOld, pszNew, pszBak);
  8188.  
  8189.      if (rc) printf("DosReplaceModule returned %u\n",rc);
  8190.  
  8191.      else {
  8192.         if (argc==2) printf("%s successfully cached and closed\n", pszOld);
  8193.         else if (argc==3)
  8194.            printf("%s successfully cached and replaced with %s\n", pszOld, pszNew);
  8195.         else if (argc==4)
  8196.            printf("%s successfully copied to %s and replaced with %s\n", pszOld, pszBak, pszNew);
  8197.      }
  8198.  
  8199.      return rc;
  8200.   }
  8201.  
  8202.  
  8203. ΓòÉΓòÉΓòÉ 5.33. DosSetFileInfo ΓòÉΓòÉΓòÉ
  8204.  
  8205. Purpose 
  8206.  
  8207. DosSetFileInfo sets file information. 
  8208.  
  8209. Syntax 
  8210.  
  8211. #define INCL DOSFILEMGR
  8212. #include  os2.h
  8213.  
  8214.  APIRET DosSetFileInfo (HFILE hf, ULONG ulInfoLevel, PVOID pInfoBuf, ULONG 
  8215.            cbInfoBuf) 
  8216.  
  8217.  Parameters 
  8218.  
  8219.  hf  HFILE)  input 
  8220.            File handle. 
  8221.  
  8222.  ulInfoLevel  ULONG)  input 
  8223.            Level of file information being set. 
  8224.  
  8225.            Specify a value 
  8226.  
  8227.            1        FIL_STANDARD 
  8228.  
  8229.                     Level 1 file information 
  8230.  
  8231.            11       FIL_STANDARDL 
  8232.  
  8233.                     Level 11 file information 
  8234.  
  8235.            2        FIL_QUERYEASIZE 
  8236.  
  8237.                     Level 2 file information 
  8238.  
  8239.            The structures described in pInfoBuf indicate the information being 
  8240.            set for each of these levels. 
  8241.  
  8242.  pInfoBuf  PVOID)  input 
  8243.            Address of the storage area containing the structures for file 
  8244.            information levels. 
  8245.  
  8246.            Level 1 File Information (ulInfoLevel == FIL_STANDARD) 
  8247.                     pInfoBuf contains the FILESTATUS3 data structure. 
  8248.  
  8249.            Level 11 File Information (ulInfoLevel == FIL_STANDARDL) 
  8250.                     pInfo contains the FILESTATUS3L data structure, in which 
  8251.                     file information is returned. 
  8252.  
  8253.            Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) 
  8254.                     pInfoBuf contains an EAOP2 data structure, and sets a 
  8255.                     series of EA name/value pairs. 
  8256.  
  8257.                     Input        pInfoBuf is an EAOP2 data structure in which 
  8258.                                  fpFEA2List points to a data area where the 
  8259.                                  relevant FEA2LIST is to be found. fpGEA2List 
  8260.                                  and oError are ignored. 
  8261.  
  8262.                     Output       fpGEA2List and fpFEA2List are unchanged. The 
  8263.                                  area pointed to by fpFEA2List is also 
  8264.                                  unchanged. If an error occurred during the 
  8265.                                  set, oError is the offset of the FEA2 where 
  8266.                                  the error occurred. The return code is the 
  8267.                                  error code corresponding to the condition 
  8268.                                  generating the error. If no error occurred, 
  8269.                                  oError is undefined. 
  8270.  
  8271.  cbInfoBuf  ULONG)  input 
  8272.            The length, in bytes, of pInfoBuf. 
  8273.  
  8274.  Returns 
  8275.  
  8276.  ulrc  APIRET)  returns 
  8277.            Return Code. 
  8278.  
  8279.            DosSetFileInfo returns one of the following values 
  8280.  
  8281.            0              NO_ERROR 
  8282.  
  8283.            1              ERROR_INVALID_FUNCTION 
  8284.  
  8285.            5              ERROR_ACCESS_DENIED 
  8286.  
  8287.            6              ERROR_INVALID_HANDLE 
  8288.  
  8289.            87             ERROR_INVALID_PARAMETER 
  8290.  
  8291.            122            ERROR_INSUFFICIENT_BUFFER 
  8292.  
  8293.            124            ERROR_INVALID_LEVEL 
  8294.  
  8295.            130            ERROR_DIRECT_ACCESS_HANDLE 
  8296.  
  8297.            254            ERROR_INVALID_EA_NAME 
  8298.  
  8299.            255            ERROR_EA_LIST_INCONSISTENT 
  8300.  
  8301.  Remarks 
  8302.  
  8303.  DosSetFileInfo is successful only when the file is opened for write access, 
  8304.  and access by other processes is prevented by a deny-both sharing mode. If the 
  8305.  file is already opened with conflicting sharing rights, any call to DosOpen 
  8306.  will fail. 
  8307.  
  8308.  A value of 0 in the date and time components of a field does not change the 
  8309.  field. For example, if both  last write date  and  last write time  are 
  8310.  specified as 0 in the Level 1 information structure, then both attributes of 
  8311.  the file are left unchanged. If either  last write date  or  last write time 
  8312.  are other than 0, both attributes of the file are set to the new values. 
  8313.  
  8314.  In the FAT file system, only the dates and times of the last write can be 
  8315.  modified. Creation and last-access dates and times are not affected. 
  8316.  
  8317.  The last-modification date and time will be changed if the extended attributes 
  8318.  are modified. 
  8319.  
  8320.  Related Functions 
  8321.  
  8322.      DosClose 
  8323.  
  8324.      DosEnumAttribute 
  8325.  
  8326.      DosOpen 
  8327.  
  8328.      DosOpenL 
  8329.  
  8330.      DosQueryFileInfo 
  8331.  
  8332.      DosQueryPathInfo 
  8333.  
  8334.      DosResetBuffer 
  8335.  
  8336.      DosSetFileSize 
  8337.  
  8338.      DosSetFileSizeL 
  8339.  
  8340.      DosSetPathInfo 
  8341.  
  8342.  Example Code 
  8343.  
  8344.  This example creates a read-only file named  DOSFDEL.DAT , and then changes 
  8345.  the file attributes. It uses DosForceDelete to delete the file so it cannot be 
  8346.  restored using UNDELETE. 
  8347.  
  8348.   #define INCL_DOSFILEMGR   /* File Manager values */
  8349.   #define INCL_DOSERRORS    /* DOS error values    */
  8350.   #include  os2.h
  8351.   #include  stdio.h
  8352.  
  8353.   int main(VOID)
  8354.  
  8355.   UCHAR       uchFileName     = "DOSFDEL.DAT";   /* File we want to delete    */
  8356.   HFILE       fhDelFile       = 0;               /* File handle from DosOpenL  */
  8357.   FILESTATUS3L fsts3FileInfo   =   0  ;  /* Information associated with file   */
  8358.   ULONG       ulBufferSize    = sizeof(FILESTATUS3L); /* File info buffer size */
  8359.   ULONG       ulOpenAction    = 0;                 /* Action taken by DosOpenL */
  8360.   APIRET      rc              = NO_ERROR;          /* Return code             */
  8361.  
  8362.   /* Create a read-only file */
  8363.  
  8364.   rc = DosOpenL(uchFileName,  fhDelFile,
  8365.    ulOpenAction, (LONGLONG)10, FILE_READONLY,
  8366.   OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
  8367.   OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE, 0L);
  8368.   if (rc != NO_ERROR)
  8369.   printf("DosOpenL error  return code = %u\n", rc);
  8370.   return 1;
  8371.  
  8372.   rc = DosQueryFileInfo(fhDelFile, FIL_STANDARDL,
  8373.    fsts3FileInfo, ulBufferSize);  /* Get standard info */
  8374.   if (rc != NO_ERROR)
  8375.   printf("DosQueryFileInfo error  return code = %u\n", rc);
  8376.   return 1;
  8377.     else   printf("File %s created read-only.\n",uchFileName);
  8378.  
  8379.   fsts3FileInfo.attrFile  = FILE_NORMAL;
  8380.   rc = DosSetFileInfo(fhDelFile, FIL_STANDARDL,
  8381.    fsts3FileInfo, ulBufferSize);
  8382.   if (rc != NO_ERROR)
  8383.   printf("DosSetFileInfo error  return code = %u\n", rc);
  8384.   return 1;
  8385.  
  8386.  
  8387.   rc = DosClose(fhDelFile);
  8388.   /* should check (rc != NO_ERROR) here... */
  8389.  
  8390.   /* Delete the file */
  8391.  
  8392.   rc = DosForceDelete(uchFileName);
  8393.   if (rc != NO_ERROR)
  8394.   printf("DosForceDelete error  return code = %u\n", rc);
  8395.   return 1;
  8396.     else
  8397.   printf("File %s has been deleted.\n",uchFileName);
  8398.     /* endif */
  8399.  
  8400.   return NO_ERROR;
  8401.  
  8402.  
  8403. ΓòÉΓòÉΓòÉ 5.34. DosSetFileLocksL ΓòÉΓòÉΓòÉ
  8404.  
  8405. Purpose 
  8406.  
  8407. DosSetFileLocksL locks and unlocks a range of an open file. 
  8408.  
  8409. Syntax 
  8410.  
  8411. #define INCL DOSFILEMGR
  8412. #include  os2.h
  8413.  
  8414.  APIRET DosSetFileLocksL (HFILE hFile, PFILELOCKL pflUnlock, PFILELOCKL 
  8415.            pflLock, ULONG timeout, ULONG flags) 
  8416.  
  8417.  Parameters 
  8418.  
  8419.  hFile  HFILE)  input 
  8420.            File handle. 
  8421.  
  8422.  pflUnlock  PFILELOCKL)  input 
  8423.            Address of the structure containing the offset and length of a range 
  8424.            to be unlocked. 
  8425.  
  8426.  pflLock  PFILELOCKL)  input 
  8427.            Address of the structure containing the offset and length of a range 
  8428.            to be locked. 
  8429.  
  8430.  timeout  ULONG)  input 
  8431.            The maximum time, in milliseconds, that the process is to wait for 
  8432.            the requested locks. 
  8433.  
  8434.  flags  ULONG)  input 
  8435.            Flags that describe the action to be taken. 
  8436.  
  8437.            This parameter has the following bit fields 
  8438.  
  8439.            Bits           Description 
  8440.  
  8441.            31 2           Reserved flags 
  8442.  
  8443.            1              Atomic 
  8444.  
  8445.                           This bit defines a request for atomic locking. If 
  8446.                           this bit is set to 1 and the lock range is equal to 
  8447.                           the unlock range, an atomic lock occurs. If this bit 
  8448.                           is set to 1 and the lock range is not equal to the 
  8449.                           unlock range, an error is returned. 
  8450.  
  8451.                           If this bit is set to 0, then the lock may or may not 
  8452.                           occur atomically with the unlock. 
  8453.  
  8454.            0              Share 
  8455.  
  8456.                           This bit defines the type of access that other 
  8457.                           processes may have to the file range that is being 
  8458.                           locked. 
  8459.  
  8460.                           If this bit is set to 0 (the default), other 
  8461.                           processes have no access to the locked file range. 
  8462.                           The current process has exclusive access to the 
  8463.                           locked file range, which must not overlap any other 
  8464.                           locked file range. 
  8465.  
  8466.                           If this bit is set to 1, the current process and 
  8467.                           other processes have shared read only access to the 
  8468.                           locked file range. A file range with shared access 
  8469.                           may overlap any other file range with shared access, 
  8470.                           but must not overlap any other file range with 
  8471.                           exclusive access. 
  8472.  
  8473.  Returns 
  8474.  
  8475.  ulrc  APIRET)  returns 
  8476.            Return Code. 
  8477.  
  8478.            DosSetFileLocksL returns one of the following values 
  8479.  
  8480.            0              NO_ERROR 
  8481.  
  8482.            1              ERROR_INVALID_FUNCTION 
  8483.  
  8484.            6              ERROR_INVALID_HANDLE 
  8485.  
  8486.            33             ERROR_LOCK_VIOLATION 
  8487.  
  8488.            36             ERROR_SHARING_BUFFER_EXCEEDED 
  8489.  
  8490.            87             ERROR_INVALID_PARAMETER 
  8491.  
  8492.            95             ERROR_INTERRUPT 
  8493.  
  8494.            174            ERROR_ATOMIC_LOCK_NOT_SUPPORTED 
  8495.  
  8496.            175            ERROR_READ_LOCKS_NOT_SUPPORTED 
  8497.  
  8498.  Remarks 
  8499.  
  8500.  DosSetFileLocksL allows a process to lock and unlock a range in a file. The 
  8501.  time during which a file range is locked should be short. 
  8502.  
  8503.  If the lock and unlock ranges are both zero, ERROR_LOCK_VIOLATION is returned 
  8504.  to the caller. 
  8505.  
  8506.  If you only want to lock a file range, set the unlock file offset and the 
  8507.  unlock range length to zero. 
  8508.  
  8509.  If you only want to unlock a file range, set the lock file offset and the lock 
  8510.  range length to zero. 
  8511.  
  8512.  When the Atomic bit of flags is set to 0, and DosSetFileLocksL specifies a 
  8513.  lock operation and an unlock operation, the unlock operation occurs first, and 
  8514.  then the lock operation is performed. If an error occurs during the unlock 
  8515.  operation, an error code is returned and the lock operation is not performed. 
  8516.  If an error occurs during the lock operation, an error code is returned and 
  8517.  the unlock remains in effect if it was successful. 
  8518.  
  8519.  The lock operation is atomic when all of these conditions are met 
  8520.  
  8521.      The Atomic bit is set to 1 in flags 
  8522.  
  8523.      The unlock range is the same as the lock range 
  8524.  
  8525.      The process has shared access to the file range, and has requested 
  8526.       exclusive access to it; or the process has exclusive access to the file 
  8527.       range, and has requested shared access to it. 
  8528.  
  8529.  Some file system drivers (FSDs) may not support atomic lock operations. 
  8530.  Versions of the operating system prior to OS/2 Version 2.00 do not support 
  8531.  atomic lock operations. If the application receives the error code 
  8532.  ERROR_ATOMIC_LOCK_NOT_SUPPORTED, the application should unlock the file range 
  8533.  and then lock it using a non-atomic operation (with the atomic bit set to 0 in 
  8534.  flags). The application should also refresh its internal buffers before making 
  8535.  any changes to the file. 
  8536.  
  8537.  If you issue DosClose to close a file with locks still in effect, the locks 
  8538.  are released in no defined sequence. 
  8539.  
  8540.  If you end a process with a file open, and you have locks in effect in that 
  8541.  file, the file is closed and the locks are released in no defined sequence. 
  8542.  
  8543.  The locked range can be anywhere in the logical file. Locking beyond the end 
  8544.  of the file is not an error. A file range to be locked exclusively must first 
  8545.  be cleared of any locked file subranges or overlapping locked file ranges. 
  8546.  
  8547.  If you repeat DosSetFileLocksL for the same file handle and file range, then 
  8548.  you duplicate access to the file range. Access to locked file ranges is not 
  8549.  duplicated across DosExecPgm. The proper method of using locks is to attempt 
  8550.  to lock the file range, and to examine the return value. 
  8551.  
  8552.  The following table shows the level of access granted when the accessed file 
  8553.  range is locked with an exclusive lock or a shared lock.  Owner  refers to a 
  8554.  process that owns the lock.  Non-owner  refers to a process that does not own 
  8555.  the lock. 
  8556.  
  8557.  
  8558.    Action       Exclusive Lock             Shared Lock
  8559.  
  8560.    Owner read   Success                    Success
  8561.  
  8562.    Non owner    Wait for unlock. Return    Success
  8563.    read         error code after time out.
  8564.  
  8565.    Owner write  Success                    Wait for unlock. Return
  8566.                                            error code after time out.
  8567.  
  8568.    Non owner    Wait for unlock. Return    Wait for unlock. Return
  8569.    write        error code after time out. error code after time out.
  8570.  
  8571.  If only locking is specified, DosSetFileLocksL locks the specified file range 
  8572.  using pflLock. If the lock operation cannot be accomplished, an error is 
  8573.  returned, and the file range is not locked. 
  8574.  
  8575.  After the lock request is processed, a file range can be unlocked using the 
  8576.  pflUnlock parameter of another DosSetFileLocksL request. If unlocking cannot 
  8577.  be accomplished, an error is returned. 
  8578.  
  8579.  Instead of denying read/write access to an entire file by specifying access 
  8580.  and sharing modes with DosOpenL requests, a process attempts to lock only the 
  8581.  range needed for read/write access and examines the error code returned. 
  8582.  
  8583.  Once a specified file range is locked exclusively, read and write access by 
  8584.  another process is denied until the file range is unlocked. If both unlocking 
  8585.  and locking are specified by DosSetFileLocksL, the unlocking operation is 
  8586.  performed first, then locking is done. 
  8587.  
  8588.  Related Functions 
  8589.  
  8590.      DosCancelLockRequestL 
  8591.  
  8592.      DosDupHandle 
  8593.  
  8594.      DosExecPgm 
  8595.  
  8596.      DosOpenL 
  8597.  
  8598.  Example Code 
  8599.  
  8600.  This example opens or creates and opens a file named  FLOCK.DAT,  and updates 
  8601.  it using file locks. 
  8602.  
  8603.   #define INCL_DOSFILEMGR       /* File Manager values */
  8604.   #define INCL_DOSERRORS        /* DOS Error values    */
  8605.   #include  os2.h
  8606.   #include  stdio.h
  8607.   #include  string.h
  8608.  
  8609.   int main(VOID)
  8610.  
  8611.   HFILE     FileHandle   = NULLHANDLE;  /* File handle */
  8612.   ULONG     Action       = 0,           /* Action taken by DosOpenL */
  8613.   Wrote        = 0,           /* Number of bytes written by DosWrite */
  8614.   i            = 0;           /* Loop index */
  8615.   CHAR      FileData 40  = "Forty bytes of demonstration text data\r\n";
  8616.   APIRET    rc           = NO_ERROR;    /* Return code */
  8617.   FILELOCKL  LockArea     =  0 ,         /* Area of file to lock */
  8618.   UnlockArea   =  0 ;         /* Area of file to unlock */
  8619.  
  8620.   rc = DosOpenL("flock.dat",                   /* File to open */
  8621.    FileHandle,                   /* File handle */
  8622.    Action,                       /* Action taken */
  8623.   (LONGLONG)4000,                /* File primary allocation */
  8624.   FILE_ARCHIVED,                 /* File attributes */
  8625.   FILE_OPEN | FILE_CREATE,       /* Open function type */
  8626.   OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE,
  8627.   0L);                           /* No extended attributes */
  8628.   if (rc != NO_ERROR)                         /* If open failed */
  8629.   printf("DosOpenL error  return code = %u\n", rc);
  8630.   return 1;
  8631.  
  8632.   LockArea.lOffset = 0;              /* Start locking at beginning of file */
  8633.   LockArea.lRange =  40;             /* Use a lock range of 40 bytes       */
  8634.   UnLockArea.lOffset = 0;            /* Start unlocking at beginning of file */
  8635.   UnLockArea.lRange =  0;            /* Use a unlock range of 0 bytes       */
  8636.  
  8637.   /* Write 8000 bytes to the file, 40 bytes at a time */
  8638.   for (i=0; i 200; ++i)
  8639.   rc = DosSetFileLocksL(FileHandle,        /* File handle   */
  8640.    UnlockArea,       /* Unlock previous record (if any) */
  8641.    LockArea,         /* Lock current record */
  8642.   2000L,             /* Lock time-out value of 2 seconds */
  8643.   0L);               /* Exclusive lock, not atomic */
  8644.   if (rc != NO_ERROR)
  8645.   printf("DosSetFileLocksL error  return code = %u\n", rc);
  8646.   return 1;
  8647.  
  8648.  
  8649.   rc = DosWrite(FileHandle, FileData, sizeof(FileData),  Wrote);
  8650.   if (rc != NO_ERROR)
  8651.   printf("DosWrite error  return code = %u\n", rc);
  8652.   return 1;
  8653.  
  8654.  
  8655.   UnlockArea = LockArea;      /* Will unlock this record on next iteration */
  8656.   LockArea.lOffset += 40;     /* Prepare to lock next record               */
  8657.  
  8658.     /* endfor - 8000 bytes written */
  8659.   rc = DosClose(FileHandle);    /* Close file, this releases outstanding locks */
  8660.   /* Should check if (rc != NO_ERROR) here ... */
  8661.   return NO_ERROR;
  8662.  
  8663.  
  8664. ΓòÉΓòÉΓòÉ 5.35. DosSetFilePtr ΓòÉΓòÉΓòÉ
  8665.  
  8666. Purpose 
  8667.  
  8668. DosSetFilePtr moves the read write pointer according to the type of move 
  8669. specified. 
  8670.  
  8671. Syntax 
  8672.  
  8673. #define INCL DOSFILEMGR
  8674. #include  os2.h
  8675.  
  8676.  APIRET DosSetFilePtr (HFILE hFile, LONG ib, ULONG method, PULONG ibActual) 
  8677.  
  8678.  Parameters 
  8679.  
  8680.  hFile  HFILE)  input 
  8681.            The handle returned by a previous DosOpen function. 
  8682.  
  8683.  ib  LONG)  input 
  8684.            The signed distance (offset) to move the read/write pointer, in 
  8685.            bytes. The raw file system requires that the offset be a multiple of 
  8686.            the sector size (512). 
  8687.  
  8688.  method  ULONG)  input 
  8689.            The method of moving. 
  8690.  
  8691.            Specifies a location in the file from where the ib to move the 
  8692.            read/write pointer starts. The values and their meanings are 
  8693.            described in the following list 
  8694.  
  8695.            0        FILE_BEGIN 
  8696.  
  8697.                     Move the pointer from the beginning of the file. 
  8698.  
  8699.            1        FILE_CURRENT 
  8700.  
  8701.                     Move the pointer from the current location of the read 
  8702.                     write pointer. 
  8703.  
  8704.            2        FILE_END 
  8705.  
  8706.                     Move the pointer from the end of the file. Use this method 
  8707.                     to determine a file s size. 
  8708.  
  8709.  ibActual  PULONG)  output 
  8710.            Address of the new pointer location. 
  8711.  
  8712.  Returns 
  8713.  
  8714.  ulrc  APIRET)  returns 
  8715.            Return Code. 
  8716.  
  8717.            DosSetFilePtr returns one of the following values 
  8718.  
  8719.            0              NO_ERROR 
  8720.  
  8721.            1              ERROR_INVALID_FUNCTION 
  8722.  
  8723.            6              ERROR_INVALID_HANDLE 
  8724.  
  8725.            25             ERROR_SEEK 
  8726.  
  8727.            130            ERROR_DIRECT_ACCESS_HANDLE 
  8728.  
  8729.            131            ERROR_NEGATIVE_SEEK 
  8730.  
  8731.            132            ERROR_SEEK_ON_DEVICE 
  8732.  
  8733.  Remarks 
  8734.  
  8735.  The read/write pointer in a file is a signed 32-bit number. A negative value 
  8736.  for ib moves the pointer backward; a positive value moves it forward. The 
  8737.  resulting pointer value cannot be negative or larger than the disk or an error 
  8738.  will be returned. The signed 32-bit value of the read/write pointer limits the 
  8739.  raw file system to the first 2 Gigabytes of a disk. 
  8740.  
  8741.  Related Functions 
  8742.  
  8743.      DosOpen 
  8744.  
  8745.      DosListIO 
  8746.  
  8747.      DosRead 
  8748.  
  8749.      DosWrite 
  8750.  
  8751.  Example Code 
  8752.  
  8753.  The following is NOT a complete usable program.  It is simply intended  to 
  8754.  provide an idea of how to use Raw I/O File System APIs (e.g. DosOpen, DosRead, 
  8755.  DosWrite, DosSetFilePtr, and DosClose). 
  8756.  
  8757.  This example opens physical disk #1 for reading and physical disk #2  for 
  8758.  writing.  DosSetFilePtr is used to set the pointer to the beginning of the 
  8759.  disks. Using DosRead and DosWrite, 10 megabytes of data is transferred from 
  8760.  disk #1 to disk #2. Finally, DosClosed is issued to close the disk handles. 
  8761.  
  8762.  It is assumed that the size of each of the two disks is at least 10 megabytes. 
  8763.  
  8764.   #define INCL_DOSFILEMGR          /* Include File Manager APIs */
  8765.   #define INCL_DOSMEMMGR           /* Includes Memory Management APIs */
  8766.   #define INCL_DOSERRORS           /* DOS Error values */
  8767.   #include  os2.h>
  8768.   #include  stdio.h>
  8769.   #include  string.h>
  8770.  
  8771.   #define SIXTY_FOUR_K 0x10000
  8772.   #define ONE_MEG     0x100000
  8773.   #define TEN_MEG     10*ONE_MEG
  8774.  
  8775.   #define UNC_DISK1  "\\\\.\\Physical_Disk1"
  8776.   #define UNC_DISK2  "\\\\.\\Physical_Disk2"
  8777.  
  8778.   int main(void) {
  8779.      HFILE  hfDisk1        = 0;      /* Handle for disk #1 */
  8780.      HFILE  hfDisk2        = 0;      /* Handle for disk #2 */
  8781.      ULONG  ulAction       = 0;      /* Action taken by DosOpen */
  8782.      ULONG  cbRead         = 0;      /* Bytes to read */
  8783.      ULONG  cbActualRead   = 0;      /* Bytes read by DosRead */
  8784.      ULONG  cbWrite        = 0;      /* Bytes to write */
  8785.      ULONG  ulLocation     = 0;
  8786.      ULONG  cbActualWrote  = 0;      /* Bytes written by DosWrite */
  8787.      UCHAR  uchFileName1[20]  = UNC_DISK1, /* UNC Name of disk 1 */
  8788.             uchFileName2[20]  = UNC_DISK2; /* UNC Name of disk 2 */
  8789.      PBYTE  pBuffer        = 0;
  8790.      ULONG  cbTotal        = 0;
  8791.  
  8792.      APIRET rc             = NO_ERROR;            /* Return code */
  8793.  
  8794.      /* Open a raw file system disk #1 for reading */
  8795.      rc = DosOpen(uchFileName1,               /* File name */
  8796.                    hfDisk1,                   /* File handle */
  8797.                    ulAction,                  /* Action taken by DosOpen */
  8798.                   0L,                         /* no file size */
  8799.                   FILE_NORMAL,                /* File attribute */
  8800.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  8801.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  8802.                   OPEN_ACCESS_READONLY,
  8803.                   0L);                        /* No extented attributes */
  8804.      if (rc != NO_ERROR) {
  8805.         printf("DosOpen error rc = %u\n", rc);
  8806.         return(1);
  8807.      } /* endif */
  8808.  
  8809.      /* Set the pointer to the begining of the disk */
  8810.      rc = DosSetFilePtr(hfDisk1,      /* Handle for disk 1 */
  8811.                         0L,           /* Offset must be multiple of 512 */
  8812.                         FILE_BEGIN,   /* Begin of the disk */
  8813.                          ulLocation); /* New pointer location */
  8814.      if (rc != NO_ERROR) {
  8815.         printf("DosSetFilePtr error rc = %u\n", rc);
  8816.         return(1);
  8817.      } /* endif */
  8818.  
  8819.      /* Open a raw file system disk #2 for writing */
  8820.      rc = DosOpen(uchFileName2,               /* File name */
  8821.                    hfDisk2,                   /* File handle */
  8822.                    ulAction,                  /* Action taken by DosOpen */
  8823.                   0L,                         /* no file size */
  8824.                   FILE_NORMAL,                /* File attribute */
  8825.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  8826.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  8827.                   OPEN_ACCESS_READWRITE,
  8828.                   0L);                        /* No extented attributes */
  8829.      if (rc != NO_ERROR) {
  8830.         printf("DosOpen error rc = %u\n", rc);
  8831.         return(1);
  8832.      } /* endif */
  8833.  
  8834.      /* Set the pointer to the begining of the disk */
  8835.      rc = DosSetFilePtr(hfDisk2,      /* Handle for disk 1 */
  8836.                         0L,           /* Offset must be multiple of 512 */
  8837.                         FILE_BEGIN,   /* Begin of the disk */
  8838.                          ulLocation); /* New pointer location */
  8839.      if (rc != NO_ERROR) {
  8840.         printf("DosSetFilePtr error rc = %u\n", rc);
  8841.         return(1);
  8842.      } /* endif */
  8843.  
  8844.  
  8845.      /* Allocate 64K of memory for transfer operations */
  8846.      rc = DosAllocMem((PPVOID) pBuffer, /* Pointer to buffer */
  8847.                        SIXTY_FOUR_K,      /* Buffer size */
  8848.                        PAG_COMMIT |     /* Allocation flags */
  8849.                        PAG_READ |
  8850.                        PAG_WRITE);
  8851.      if (rc != NO_ERROR) {
  8852.         printf("DosAllocMem error rc = %u\n", rc);
  8853.         return(1);
  8854.      } /* endif */
  8855.  
  8856.      cbRead = SIXTY_FOUR_K;
  8857.      while (rc == NO_ERROR    cbTotal   TEN_MEG) {
  8858.  
  8859.         /* Read from #1 */
  8860.         rc = DosRead(hfDisk1,         /* Handle for disk 1 */
  8861.                      pBuffer,         /* Pointer to buffer */
  8862.                      cbRead,          /* Size must be multiple of 512 */
  8863.                       cbActualRead);  /* Actual read by DosOpen */
  8864.         if (rc) {
  8865.            printf("DosRead error  return code = %u\n", rc);
  8866.            return 1;
  8867.         }
  8868.  
  8869.         /* Write to disk #2 */
  8870.         cbWrite = cbActualRead;
  8871.         rc = DosWrite(hfDisk2,         /* Handle for disk 2 */
  8872.                       pBuffer,         /* Pointer to buffer */
  8873.                       cbWrite,         /* Size must be multiple of 512 */
  8874.                        cbActualWrote); /* Actual written by DosOpen */
  8875.         if (rc) {
  8876.            printf("DosWrite error  return code = %u\n", rc);
  8877.            return 1;
  8878.         }
  8879.         if (cbActualRead != cbActualWrote) {
  8880.            printf("Bytes read (%u) does not equal bytes written (%u)\n",
  8881.                   cbActualRead, cbActualWrote);
  8882.            return 1;
  8883.         }
  8884.         cbTotal += cbActualRead; /* Update total transferred */
  8885.      }
  8886.  
  8887.      printf("Transfer successfully %d bytes from disk #1 to disk #2.\n",
  8888.             cbTotal);
  8889.  
  8890.      /* Free allocated memmory */
  8891.      rc = DosFreeMem(pBuffer);
  8892.      if (rc != NO_ERROR) {
  8893.         printf("DosFreeMem error  return code = %u\n", rc);
  8894.         return 1;
  8895.      }
  8896.  
  8897.      rc = DosClose(hfDisk1);
  8898.      if (rc != NO_ERROR) {
  8899.         printf("DosClose error  return code = %u\n", rc);
  8900.         return 1;
  8901.      }
  8902.  
  8903.      rc = DosClose(hfDisk2);
  8904.      if (rc != NO_ERROR) {
  8905.         printf("DosClose error  return code = %u\n", rc);
  8906.         return 1;
  8907.      }
  8908.   return NO_ERROR;
  8909.   }
  8910.  
  8911.  
  8912. ΓòÉΓòÉΓòÉ 5.36. DosSetFilePtrL ΓòÉΓòÉΓòÉ
  8913.  
  8914. Purpose 
  8915.  
  8916. DosSetFilePtrL moves the read write pointer according to the type of move 
  8917. specified. 
  8918.  
  8919. Syntax 
  8920.  
  8921. #define INCL DOSFILEMGR
  8922. #include  os2.h
  8923.  
  8924.  APIRET DosSetFilePtrL (HFILE hFile, LONGLONG ib, ULONG method, PLONGLONG 
  8925.            ibActual) 
  8926.  
  8927.  Parameters 
  8928.  
  8929.  hFile  HFILE)  input 
  8930.            The handle returned by a previous DosOpenL function. 
  8931.  
  8932.  ib  LONGLONG)  input 
  8933.            The signed distance (offset) to move, in bytes. 
  8934.  
  8935.  method  ULONG)  input 
  8936.            The method of moving. 
  8937.  
  8938.            Specifies a location in the file from where the ib to move the 
  8939.            read/write pointer starts. The values and their meanings are 
  8940.            described in the following list 
  8941.  
  8942.            0        FILE_BEGIN 
  8943.  
  8944.                     Move the pointer from the beginning of the file. 
  8945.  
  8946.            1        FILE_CURRENT 
  8947.  
  8948.                     Move the pointer from the current location of the read 
  8949.                     write pointer. 
  8950.  
  8951.            2        FILE_END 
  8952.  
  8953.                     Move the pointer from the end of the file. Use this method 
  8954.                     to determine a file s size. 
  8955.  
  8956.  ibActual  PLONGLONG)  output 
  8957.            Address of the new pointer location. 
  8958.  
  8959.  Returns 
  8960.  
  8961.  ulrc  APIRET)  returns 
  8962.            Return Code. 
  8963.  
  8964.            DosSetFilePtrL returns one of the following values 
  8965.  
  8966.            0              NO_ERROR 
  8967.  
  8968.            1              ERROR_INVALID_FUNCTION 
  8969.  
  8970.            6              ERROR_INVALID_HANDLE 
  8971.  
  8972.            132            ERROR_SEEK_ON_DEVICE 
  8973.  
  8974.            131            ERROR_NEGATIVE_SEEK 
  8975.  
  8976.            130            ERROR_DIRECT_ACCESS_HANDLE 
  8977.  
  8978.  Remarks 
  8979.  
  8980.  The read/write pointer in a file is a signed 64-bit number. A negative value 
  8981.  for ib moves the pointer backward in the file; a positive value moves it 
  8982.  forward. DosSetFilePtrL cannot be used to move to a negative position in the 
  8983.  file. 
  8984.  
  8985.  DosSetFilePtrL cannot be used for a character device or pipe. 
  8986.  
  8987.  Related Functions 
  8988.  
  8989.      DosOpenL 
  8990.  
  8991.      DosRead 
  8992.  
  8993.      DosSetFileSizeL 
  8994.  
  8995.      DosWrite 
  8996.  
  8997.  Example Code 
  8998.  
  8999.  This example opens or creates and opens a file named  DOSTEST.DAT , writes to 
  9000.  it, positions the file pointer back to the beginning of the file, reads from 
  9001.  the file, and finally closes it. 
  9002.  
  9003.   #define INCL_DOSFILEMGR          /* File Manager values */
  9004.   #define INCL_DOSERRORS           /* DOS Error values    */
  9005.   #include  os2.h
  9006.   #include  stdio.h
  9007.   #include  string.h
  9008.  
  9009.   int main(void)
  9010.   HFILE  hfFileHandle   = 0L;     /* Handle for file being manipulated */
  9011.   ULONG  ulAction       = 0;      /* Action taken by DosOpenL */
  9012.   ULONG  ulBytesRead    = 0;      /* Number of bytes read by DosRead */
  9013.   ULONG  ulWrote        = 0;      /* Number of bytes written by DosWrite */
  9014.   LONGLONG  ullLocal    = 0;      /* File pointer position after DosSetFilePtr */
  9015.   UCHAR  uchFileName 20   = "dostest.dat",     /* Name of file */
  9016.   uchFileData 100  = " ";               /* Data to write to file */
  9017.   APIRET rc             = NO_ERROR;            /* Return code */
  9018.  
  9019.   /* Open the file test.dat.  Use an existing file or create a new */
  9020.   /* one if it doesn't exist.                                      */
  9021.   rc = DosOpenL(uchFileName,                    /* File path name */
  9022.    hfFileHandle,                  /* File handle */
  9023.    ulAction,                      /* Action taken */
  9024.   (LONGLONG)100,                  /* File primary allocation */
  9025.   FILE_ARCHIVED | FILE_NORMAL,    /* File attribute */
  9026.   OPEN_ACTION_CREATE_IF_NEW |
  9027.   OPEN_ACTION_OPEN_IF_EXISTS,     /* Open function type */
  9028.   OPEN_FLAGS_NOINHERIT |
  9029.   OPEN_SHARE_DENYNONE  |
  9030.   OPEN_ACCESS_READWRITE,          /* Open mode of the file */
  9031.   0L);                            /* No extended attribute */if (rc != NO_ERROR)
  9032.   printf("DosOpenL error  return code = %u\n", rc);
  9033.   return 1;
  9034.     else
  9035.   printf ("DosOpenL  Action taken = %ld\n", ulAction);
  9036.     /* endif */
  9037.  
  9038.   /* Write a string to the file */
  9039.   strcpy (uchFileData, "testing...\n1...\n2...\n3\n");
  9040.  
  9041.   rc = DosWrite (hfFileHandle,                /* File handle */
  9042.   (PVOID) uchFileData,         /* String to be written */
  9043.   sizeof (uchFileData),        /* Size of string to be written */
  9044.    ulWrote);                   /* Bytes actually written */
  9045.  
  9046.   if (rc != NO_ERROR)
  9047.   printf("DosWrite error  return code = %u\n", rc);
  9048.   return 1;
  9049.     else
  9050.   printf ("DosWrite  Bytes written = %u\n", ulWrote);
  9051.     /* endif */
  9052.  
  9053.   /* Move the file pointer back to the beginning of the file */
  9054.   rc = DosSetFilePtrL (hfFileHandle,           /* File Handle */
  9055.   (LONGLONG)0,            /* Offset */
  9056.   FILE_BEGIN,             /* Move from BOF */
  9057.    ullLocal);             /* New location address */
  9058.   if (rc != NO_ERROR)
  9059.   printf("DosSetFilePtrL error  return code = %u\n", rc);
  9060.   return 1;
  9061.  
  9062.  
  9063.   /* Read the first 100 bytes of the file */
  9064.   rc = DosRead (hfFileHandle,                /* File Handle */
  9065.   uchFileData,                 /* String to be read */
  9066.   100L,                        /* Length of string to be read */
  9067.    ulBytesRead);               /* Bytes actually read */
  9068.  
  9069.   if (rc != NO_ERROR)
  9070.   printf("DosRead error  return code = %u\n", rc);
  9071.   return 1;
  9072.     else
  9073.   printf ("DosRead  Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
  9074.     /* endif */
  9075.  
  9076.   rc = DosClose(hfFileHandle);                /* Close the file */
  9077.  
  9078.   if (rc != NO_ERROR)
  9079.   printf("DosClose error  return code = %u\n", rc);
  9080.   return 1;
  9081.  
  9082.   return NO_ERROR;
  9083.  
  9084.  
  9085. ΓòÉΓòÉΓòÉ 5.37. DosSetFileSizeL ΓòÉΓòÉΓòÉ
  9086.  
  9087. Purpose 
  9088.  
  9089. DosSetFileSizeL changes the size of a file. 
  9090.  
  9091. Syntax 
  9092.  
  9093. #define INCL DOSFILEMGR
  9094. #include  os2.h
  9095.  
  9096.  APIRET DosSetFileSizeL (HFILE hFile, LONGLONG cbSize) 
  9097.  
  9098.  Parameters 
  9099.  
  9100.  hFile  HFILE)  input 
  9101.            The handle of the file whose size to be changed. 
  9102.  
  9103.  cbSize  LONGLONG)  input 
  9104.            The new size, in bytes, of the file. 
  9105.  
  9106.  Returns 
  9107.  
  9108.  ulrc  APIRET)  returns 
  9109.            Return Code. 
  9110.  
  9111.            DosSetFileSizeL returns one of the following values 
  9112.  
  9113.            0              NO_ERROR 
  9114.  
  9115.            5              ERROR_ACCESS_DENIED 
  9116.  
  9117.            6              ERROR_INVALID_HANDLE 
  9118.  
  9119.            26             ERROR_NOT_DOS_DISK 
  9120.  
  9121.            33             ERROR_LOCK_VIOLATION 
  9122.  
  9123.            87             ERROR_INVALID_PARAMETER 
  9124.  
  9125.            112            ERROR_DISK_FULL 
  9126.  
  9127.  Remarks 
  9128.  
  9129.  When DosSetFileSizeL is issued, the file must be open in a mode that allows 
  9130.  write access. 
  9131.  
  9132.  The size of the open file can be truncated or extended. If the file size is 
  9133.  being extended, the file system tries to allocate additional bytes in a 
  9134.  contiguous (or nearly contiguous) space on the medium. The values of the new 
  9135.  bytes are undefined. 
  9136.  
  9137.  Related Functions 
  9138.  
  9139.      DosOpenL 
  9140.  
  9141.      DosQueryFileInfo 
  9142.  
  9143.      DosQueryPathInfo 
  9144.  
  9145.  Example Code 
  9146.  
  9147.  This example writes to a file named  DOSMAN.DAT , resets the buffer, and 
  9148.  changes the file size. 
  9149.  
  9150.   #define INCL_DOSFILEMGR          /* File Manager values */
  9151.   #define INCL_DOSERRORS           /* DOS Error values    */
  9152.   #include  os2.h
  9153.   #include  stdio.h
  9154.   #include  string.h
  9155.  
  9156.   int main(VOID)
  9157.   HFILE  hfFileHandle   = 0L;     /* Handle for file being manipulated */
  9158.   ULONG  ulAction       = 0;      /* Action taken by DosOpenL */
  9159.   ULONG  ulWrote        = 0;      /* Number of bytes written by DosWrite */
  9160.   UCHAR  uchFileName 20   = "dosman.dat",     /* Name of file */
  9161.   uchFileData 4    = "DATA";            /* Data to write to file */
  9162.   APIRET rc             = NO_ERROR;            /* Return code */
  9163.  
  9164.   /* Open the file dosman.dat.  Use an existing file or create a new */
  9165.   /* one if it doesn't exist.                                      */
  9166.   rc = DosOpenL(uchFileName,  hfFileHandle,  ulAction, (LONGLONG)4,
  9167.   FILE_ARCHIVED | FILE_NORMAL,
  9168.   OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
  9169.   OPEN_FLAGS_NOINHERIT | OPEN_SHARE_DENYNONE  |
  9170.   OPEN_ACCESS_READWRITE, 0L);
  9171.   if (rc != NO_ERROR)
  9172.   printf("DosOpenL error  return code = %u\n", rc);
  9173.   return 1;
  9174.  
  9175.  
  9176.   rc = DosWrite (hfFileHandle, (PVOID) uchFileData,
  9177.   sizeof (uchFileData),  ulWrote);
  9178.   if (rc != NO_ERROR)
  9179.   printf("DosWrite error  return code = %u\n", rc);
  9180.   return 1;
  9181.  
  9182.  
  9183.   rc = DosResetBuffer (hfFileHandle);
  9184.   if (rc != NO_ERROR)
  9185.   printf("DosResetBuffer error  return code = %u\n", rc);
  9186.   return 1;
  9187.     /* endif */
  9188.  
  9189.   rc = DosSetFileSizeL (hfFileHandle, (LONGLONG)8);    /* Change file size */
  9190.   if (rc != NO_ERROR)
  9191.   printf("DosSetFileSizeL error  return code = %u\n", rc);
  9192.   return 1;
  9193.  
  9194.  
  9195.   return NO_ERROR;
  9196.  
  9197.  
  9198. ΓòÉΓòÉΓòÉ 5.38. DosSetPathInfo ΓòÉΓòÉΓòÉ
  9199.  
  9200. Purpose 
  9201.  
  9202. DosSetPathInfo sets information for a file or directory. 
  9203.  
  9204. Syntax 
  9205.  
  9206. #define INCL DOSFILEMGR
  9207. #include  os2.h
  9208.  
  9209.  APIRET DosSetPathInfo (PSZ pszPathName, ULONG ulInfoLevel, PVOID pInfoBuf, 
  9210.            ULONG cbInfoBuf, ULONG flOptions) 
  9211.  
  9212.  Parameters 
  9213.  
  9214.  pszPathName  PSZ)  input 
  9215.            Address of the ASCIIZ full path name of the file or subdirectory. 
  9216.  
  9217.            Global file-name characters are not permitted. 
  9218.  
  9219.            DosQuerySysInfo is called by an application during initialization to 
  9220.            determine the maximum path length allowed by the operating system. 
  9221.  
  9222.  ulInfoLevel  ULONG)  input 
  9223.            The level of file directory information being defined. 
  9224.  
  9225.            A value of 1, 11, or 2 can be specified, as shown in the following 
  9226.            list. 
  9227.  
  9228.            1        FIL_STANDARD 
  9229.  
  9230.                     Level 1 file information 
  9231.  
  9232.            11       FIL_STANDARDL 
  9233.  
  9234.                     Level 11 file information 
  9235.  
  9236.            2        FIL_QUERYEASIZE 
  9237.  
  9238.                     Level 2 file information 
  9239.  
  9240.            The structures described in pInfoBuf indicate the information being 
  9241.            set for each of these levels. 
  9242.  
  9243.  pInfoBuf  PVOID)  input 
  9244.            Address of the storage area containing the file information being 
  9245.            set. 
  9246.  
  9247.            Level 1 File Information (ulInfoLevel == FIL_STANDARD) 
  9248.                     pInfoBuf contains the FILESTATUS3 data structure. 
  9249.  
  9250.            Level 11 File Information (ulInfoLevel == FIL_STANDARDL) 
  9251.                     pInfo contains the FILESTATUS3L data structure, to which 
  9252.                     file information is returned. 
  9253.  
  9254.            Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) 
  9255.                     pInfoBuf contains an EAOP2 data structure. 
  9256.  
  9257.                     Level 2 sets a series of extended attribute (EA) name/value 
  9258.                     pairs. 
  9259.  
  9260.                     Input        pInfoBuf contains an EAOP2 data structure. 
  9261.                                  fpGEA2List is ignored. fpFEA2List points to a 
  9262.                                  data area where the relevant FEA2 list is to 
  9263.                                  be found. oError is ignored. The FEA2 data 
  9264.                                  structures must be aligned on a doubleword 
  9265.                                  boundary. Each oNextEntryOffset field must 
  9266.                                  contain the number of bytes from the beginning 
  9267.                                  of the current entry to the beginning of the 
  9268.                                  next entry in the FEA2 list. The 
  9269.                                  oNextEntryOffset field in the last entry of 
  9270.                                  the FEA2 list must be zero. 
  9271.  
  9272.                     Output       fpGEA2List and fpFEA2List are unchanged. The 
  9273.                                  area that fpFEA2List points to is unchanged. 
  9274.                                  If an error occurred during the set, oError is 
  9275.                                  the offset of the FEA2 entry where the error 
  9276.                                  occurred. The return code is the error code 
  9277.                                  corresponding to the condition that caused the 
  9278.                                  error. If no error occurred, oError is 
  9279.                                  undefined. 
  9280.  
  9281.  cbInfoBuf  ULONG)  input 
  9282.            The length, in bytes, of pInfoBuf. 
  9283.  
  9284.  flOptions  ULONG)  input 
  9285.            Information on how the set operation is to be performed. 
  9286.  
  9287.            If flOptions is 0x00000010 (DSPI_WRTTHRU), then all the information, 
  9288.            including extended attributes (EAs), must be written to the disk 
  9289.            before returning to the application. This guarantees that the EAs 
  9290.            have been written to the disk. All other bits are reserved, and must 
  9291.            be zero. 
  9292.  
  9293.  Returns 
  9294.  
  9295.  ulrc  APIRET)  returns 
  9296.            Return Code. 
  9297.  
  9298.            DosSetPathInfo returns one of the following values 
  9299.  
  9300.            0              NO_ERROR 
  9301.  
  9302.            2              ERROR_FILE_NOT_FOUND 
  9303.  
  9304.            3              ERROR_PATH_NOT_FOUND 
  9305.  
  9306.            32             ERROR_SHARING_VIOLATION 
  9307.  
  9308.            87             ERROR_INVALID_PARAMETER 
  9309.  
  9310.            124            ERROR_INVALID_LEVEL 
  9311.  
  9312.            206            ERROR_FILENAME_EXCED_RANGE 
  9313.  
  9314.            122            ERROR_INSUFFICIENT_BUFFER 
  9315.  
  9316.            254            ERROR_INVALID_EA_NAME 
  9317.  
  9318.            255            ERROR_EA_LIST_INCONSISTENT 
  9319.  
  9320.  Remarks 
  9321.  
  9322.  To use DosSetPathInfo to set any level of file information for a file or 
  9323.  subdirectory, a process must have exclusive write access to the closed file 
  9324.  object. Thus, if the file object is already accessed by another process, any 
  9325.  call to DosSetPathInfo will fail. 
  9326.  
  9327.  A value of 0 in the date and time components of a field causes that field to 
  9328.  be left unchanged. For example, if both  last write date  and  last write time 
  9329.  are specified as 0 in the Level 1 information structure, then both attributes 
  9330.  of the file are left unchanged. If either  last write date  or  last write 
  9331.  time  are other than 0, then both attributes of the file are set to the new 
  9332.  values. 
  9333.  
  9334.  For data integrity purposes, the Write-Through bit in flOptions should be used 
  9335.  only to write the extended attributes to the disk immediately, instead of 
  9336.  caching them and writing them later. Having the Write-Through bit set 
  9337.  constantly can degrade performance. 
  9338.  
  9339.  In the FAT file system, only the dates and times of the last write can be 
  9340.  modified. Creation and last-access dates and times are not affected. 
  9341.  
  9342.  The last-modification date and time will be changed if the extended attributes 
  9343.  are modified. 
  9344.  
  9345.  Related Functions 
  9346.  
  9347.      DosEnumAttribute 
  9348.  
  9349.      DosQueryFileInfo 
  9350.  
  9351.      DosQueryPathInfo 
  9352.  
  9353.      DosQuerySysInfo 
  9354.  
  9355.      DosSetFileInfo 
  9356.  
  9357.  Example Code 
  9358.  
  9359.  This example creates a directory named  HIDEME , makes it hidden, and finally 
  9360.  deletes it. 
  9361.  
  9362.   #define INCL_DOSFILEMGR   /* File Manager values */
  9363.   #define INCL_DOSERRORS    /* DOS Error values    */
  9364.   #include  os2.h
  9365.   #include  stdio.h
  9366.   #include  string.h
  9367.  
  9368.   int main(VOID)
  9369.   UCHAR       achNewDir 256   = "\\HIDEME";           /* Directory name    */
  9370.   FILESTATUS3 fsts3PathInfo   =   0  ;                /* Directory info    */
  9371.   ULONG       ulBufferSize    = sizeof(FILESTATUS3);  /* Buffer size       */
  9372.   APIRET      rc              = NO_ERROR;             /* Return code       */
  9373.  
  9374.   rc = DosCreateDir(achNewDir, (PEAOP2) NULL);        /* Create directory
  9375.   with no EAs       */
  9376.   if (rc != NO_ERROR)
  9377.   printf("DosCreateDir error  return code = %u\n", rc);
  9378.   return 1;
  9379.     else
  9380.   printf("Directory %s created.\n",achNewDir);
  9381.  
  9382.  
  9383.   rc = DosQueryPathInfo(achNewDir, FIL_STANDARD,
  9384.    fsts3PathInfo, ulBufferSize); /* Get standard info */
  9385.   if (rc != NO_ERROR)
  9386.   printf("DosQueryPathInfo error  return code = %u\n", rc);
  9387.   return 1;
  9388.  
  9389.  
  9390.   fsts3PathInfo.attrFile  = FILE_HIDDEN;   /* Add HIDDEN attribute to path */
  9391.  
  9392.   rc = DosSetPathInfo(achNewDir,           /* Change directory info on     */
  9393.   FIL_STANDARD,                            /* the disk using the buffer    */
  9394.    fsts3PathInfo,                   /*just updated.             */
  9395.   ulBufferSize,
  9396.   DSPI_WRTTHRU );      /* Write data before returning  */
  9397.   if (rc != NO_ERROR)
  9398.   printf("DosSetPathInfo error  return code = %u\n", rc);
  9399.   return 1;
  9400.     else
  9401.   printf("Directory %s hidden.\n",achNewDir);
  9402.    /* Delete the hidden directory.  If this step is omitted, the directory
  9403.   can still be manipulated by standard OS/2 commands like CHDIR and
  9404.   RMDIR, it will just not be displayed in a DIR command without the
  9405.   /AH display option specified.                                     */
  9406.  
  9407.   rc = DosDeleteDir (achNewDir);
  9408.   if (rc != NO_ERROR)
  9409.   printf ("DosDeleteDir error   return code = %u\n", rc);
  9410.   return 1;
  9411.     else
  9412.   printf("Directory %s deleted.\n",achNewDir);
  9413.  
  9414.  
  9415.   return NO_ERROR;
  9416.  
  9417.  
  9418. ΓòÉΓòÉΓòÉ 5.39. DosSetProcessorStatus ΓòÉΓòÉΓòÉ
  9419.  
  9420. Purpose 
  9421.  
  9422. DosSetProcessorStatus sets the ONLINE or OFFLINE status of a processor on an 
  9423. SMP system. The processor status may be queried using DosGetProcessorStatus. 
  9424. ONLINE status implies the processor is available for running work. OFFLINE 
  9425. status implies the processor is not available for running work. The processor 
  9426. that executes DosSetProcessorStatus must be ONLINE. 
  9427.  
  9428. Syntax 
  9429.  
  9430. #define INCL_DOS
  9431. #define INCL_DOSSPINLOCK
  9432. #include  os2.h>
  9433.  
  9434.  APIRET DosSetProcessorStatus (ULONG procid, ULONG status) 
  9435.  
  9436.  Parameters 
  9437.  
  9438.  procid (ULONG)  input 
  9439.            Processor ID numbered from 1 through n, where there are n processors 
  9440.            in total. 
  9441.  
  9442.  status (ULONG)  input 
  9443.            Status is defined as follows 
  9444.  
  9445.            PROC_OFFLINE 0x00000000 Processor is offline. 
  9446.  
  9447.            PROC_ONLINE 0x00000001 Processor is online. 
  9448.  
  9449.  Returns 
  9450.  
  9451.  ulrc (APIRET)  returns 
  9452.            Return Code. 
  9453.  
  9454.            DosSetProcessorStatus returns one of the following values 
  9455.  
  9456.            0              NO_ERROR 
  9457.  
  9458.            87             ERROR_INVALID_PARAMETER 
  9459.  
  9460.  Related Functions 
  9461.  
  9462.      DosGetProcessorStatus 
  9463.  
  9464.  Example Code 
  9465.  
  9466.   int main(int argc, char *argv[], char *envp[])
  9467.   {
  9468.      APIRET rc;
  9469.      ULONG procid;
  9470.      ULONG status;
  9471.      int i;
  9472.  
  9473.      if (argc   3) {
  9474.         printf("Syntax  SETPROC  ON|OFF\n");
  9475.         return 0;
  9476.      } /* endif */
  9477.  
  9478.      if (strcmpi(argv[argc-1],"OFF")==0) status = 0;
  9479.      else if (strcmpi(argv[argc-1],"ON")==0) status = 1;
  9480.      else {
  9481.         printf("Syntax  SETPROC  ON|OFF\n");
  9482.         return 0;
  9483.      } /* endif */
  9484.  
  9485.      for (i=1; i argc-1; ++i ) {
  9486.         procid = atol(argv[i]);
  9487.         rc = DosSetProcessorStatus(procid, status);
  9488.         if (rc) printf("DosSetProcesorStatus returned %u\n",rc);
  9489.      } /* endfor */
  9490.  
  9491.      return rc;
  9492.   }
  9493.  
  9494.  
  9495. ΓòÉΓòÉΓòÉ 5.40. DosSetThreadAffinity ΓòÉΓòÉΓòÉ
  9496.  
  9497. Purpose 
  9498.  
  9499. DosSetThreadAffinity allows the calling thread to change the processor affinity 
  9500. mask for the current thread. 
  9501.  
  9502. Syntax 
  9503.  
  9504.  APIRET DosSetThreadAffinity (PMPAffinity pAffinityMask) 
  9505.  
  9506.  Parameters 
  9507.  
  9508.  pAffinityMask (PMPAffinity)  input 
  9509.            Address of an MPAFFINITY structure that will become the current 
  9510.            thread's affinity mask. 
  9511.  
  9512.  Returns 
  9513.  
  9514.  ulrc  APIRET)  returns 
  9515.            Return Code. 
  9516.  
  9517.            DosSetThreadAffinity returns one of the following values 
  9518.  
  9519.            13             ERROR_INVALID_DATA 
  9520.  
  9521.            87             ERROR_INVALID_PARAMETER 
  9522.  
  9523.  Remarks 
  9524.  
  9525.  The processor affinity mask contains 1 bit per processor. A maximum of 64 
  9526.  processors can be designated. If affinity bits are on for non-existent 
  9527.  processors, the error ERROR_INVALID_DATA will be returned. 
  9528.  
  9529.  Related Functions 
  9530.  
  9531.      DosQueryThreadAffinity 
  9532.  
  9533.  Example Code 
  9534.  
  9535.   #define INCL_DOS
  9536.   #define INCL_32
  9537.   #define INCL_DOSERRORS
  9538.   #define INCL_NOPMAPI
  9539.   #include  os2.h>
  9540.   #include  stdio.h>
  9541.  
  9542.   int main(void)
  9543.   {
  9544.   APIRET rc;
  9545.   MPAFFINITY affinity;
  9546.  
  9547.   rc = DosSetThreadAffinity( affinity);
  9548.   printf("Set thread's affinity  rc = %08.8xh\n", rc);
  9549.   printf("Set thread's affinity  affinity[0] = %08.8xh, affinity[1] = %08.8xh\n",
  9550.           affinity.mask[0], affinity.mask[1]);
  9551.   return rc;
  9552.   }
  9553.  
  9554.  
  9555. ΓòÉΓòÉΓòÉ 5.41. Dos16SysTrace ΓòÉΓòÉΓòÉ
  9556.  
  9557. Purpose 
  9558.  
  9559. Dos16SysTrace writes a trace record to the system trace buffer. It provides a 
  9560. high speed event recording mechanism which may be used by PM and non-PM threads 
  9561. in ring 3 and ring 2 and by detached processes. 
  9562.  
  9563. Syntax 
  9564.  
  9565. #define INCL_DOSMISC
  9566. #include  os2.h>
  9567.  
  9568.  APIRET16 APIENTRY16 Dos16SysTrace (USHORT major, USHORT cBuffer, USHORT minor, 
  9569.            PCHAR pBuffer) 
  9570.  
  9571.  Parameters 
  9572.  
  9573.  major (USHORT)  input 
  9574.            Major code which identifies the trace record. Range reserved for 
  9575.            user. Use is 245 255. 
  9576.  
  9577.            Valid range  0 255 
  9578.  
  9579.  cBuffer (USHORT)  input 
  9580.            Length of optional buffer. Valid range 
  9581.  
  9582.            0 512 (before 4.0 FP 10 and 3.0 FP 35) 
  9583.  
  9584.            0 4099 (from 3.0 FP35 and 4.0 FP10 onwards). 
  9585.  
  9586.  minor (USHORT)  input 
  9587.            Minor code which identifies the trace record. Major-minor code pair 
  9588.            should uniquely identify the trace record. 
  9589.  
  9590.            Valid range  1 255 
  9591.  
  9592.  pBuffer (PCHAR)  input 
  9593.            Pointer to optional buffer. If cBuffer is 0, then pBuffer is 
  9594.            ignored. 
  9595.  
  9596.  Returns 
  9597.  
  9598.  ulrc (APIRET)  returns 
  9599.            Return Code. 
  9600.  
  9601.            Dos16SysTrace returns one of the following values 
  9602.  
  9603.            0              NO_ERROR 
  9604.  
  9605.            150            ERROR_SYSTEM_TRACE 
  9606.  
  9607.  Remarks 
  9608.  
  9609.  Dos16SysTrace creates a trace record that includes the following items 
  9610.  
  9611.      Header  Major code, minor code, time stamp, PID of logging process 
  9612.  
  9613.      Optional System Data  Controlled by the TRACE command 
  9614.  
  9615.      Optional User Data  Specified by the pBuffer parameter 
  9616.  
  9617.  If you use Dos16SysTrace, then you need to LINK specifying OS2386.LIB. If you 
  9618.  use DosSysTrace, then you need to LINK specifying OS2286.LIB as an additional 
  9619.  library file with the LINK386 command. 
  9620.  
  9621.  Related Functions 
  9622.  
  9623.      DosDumpProcess 
  9624.  
  9625.      DosForceSystemDump 
  9626.  
  9627.  Example Code 
  9628.  
  9629.   int main(int argc, char *argv[], char *envp[])
  9630.   {
  9631.      APIRET16 rc=0;          /* default return code */
  9632.      USHORT major=255;       /* default major code */
  9633.      USHORT minor=1;         /* default minor code */
  9634.      USHORT cBuffer=0;       /* default buffer length */
  9635.      PCHAR  pBuffer=NULL;    /* default buffer address */
  9636.  
  9637.      if (argc>1)
  9638.      {
  9639.         pBuffer = argv[1];
  9640.         cBuffer = strlen(argv[1]);
  9641.      }
  9642.  
  9643.      if (argc>2) major = atol(argv[2]);
  9644.      if (argc>3) minor = atol(argv[3]);
  9645.  
  9646.      rc = Dos16SysTrace(major, cBuffer, minor, pBuffer);
  9647.  
  9648.      if (rc) printf("DosSysTrace retuned rc=%u\n", rc);
  9649.  
  9650.      return rc;
  9651.   }
  9652.  
  9653.  
  9654. ΓòÉΓòÉΓòÉ 5.42. DosTmrQueryFreq ΓòÉΓòÉΓòÉ
  9655.  
  9656. Purpose 
  9657.  
  9658. DosTmrQueryFreq queries the frequency of the high resolution timer. To get the 
  9659. high resolution time interval in seconds, subtract two 64 bit times and divide 
  9660. by the frequency. 
  9661.  
  9662. Syntax 
  9663.  
  9664. #define INCL_DOSPROFILE
  9665. #include  os2.h>
  9666.  
  9667.  APIRET APIENTRY DosTmrQueryFreq (PQWORD freq) 
  9668.  
  9669.  Parameters 
  9670.  
  9671.  freq(PQWORD)  output 
  9672.  
  9673.  Returns 
  9674.  
  9675.  ulrc (APIRET)  returns 
  9676.            Return Code. 
  9677.  
  9678.            DosTmrQueryFreq returns one of the following values 
  9679.  
  9680.            0              NO_ERROR 
  9681.  
  9682.            87             ERROR_INVALID_PARAMETER 
  9683.  
  9684.            99             ERROR_DEVICE_IN_USE 
  9685.  
  9686.            535            ERROR_TMR_NO_DEVICE 
  9687.  
  9688.  Example Code 
  9689.  
  9690.   void int3(void);
  9691.  
  9692.   int main(int argc, char *argv[], char *envp[])
  9693.   {
  9694.      QWORD start_time;
  9695.      QWORD end_time;
  9696.      QWORD interval;
  9697.  
  9698.      ULONG freq;
  9699.      APIRET rc;
  9700.  
  9701.      rc=DosTmrQueryTime( start_time);
  9702.      printf("DosTmrQueryTime rc=%u time=0x%08x%08x\n", rc,start_time.ulHi,start_time.ulLo);
  9703.  
  9704.      DosSleep(100);
  9705.      printf("Sleeping 100ms\n");
  9706.  
  9707.      rc=DosTmrQueryTime( end_time);
  9708.      printf("DosTmrQueryTime rc=%u time=0x%08x%08x\n", rc,end_time.ulHi,end_time.ulLo);
  9709.  
  9710.      rc=DosTmrQueryFreq( freq);
  9711.      printf("DosTmrQueryFreq rc=%u freq=%uHz\n",rc,freq);
  9712.  
  9713.      interval.ulLo = end_time.ulLo - start_time.ulLo;
  9714.      interval.ulHi = (end_time.ulLo >= start_time.ulLo) ?
  9715.                          end_time.ulHi - start_time.ulHi
  9716.                          end_time.ulHi - start_time.ulHi - 1;
  9717.      printf("Time interval=0x%08x%08x units=%uns\n",interval.ulHi,interval.ulLo,1000000000/freq);
  9718.      if (interval.ulHi == 0) printf("Appox. %uns\n",interval.ulLo*(1000000000/freq));
  9719.  
  9720.      return 0;
  9721.   }
  9722.  
  9723.  
  9724. ΓòÉΓòÉΓòÉ 5.43. DosTmrQueryTime ΓòÉΓòÉΓòÉ
  9725.  
  9726. Purpose 
  9727.  
  9728. DosTmrQueryTime queries the 64 bit high resolution timer. 
  9729.  
  9730. Syntax 
  9731.  
  9732. #define INCL_DOSPROFILE
  9733. #include  os2.h>
  9734.  
  9735.  APIRET APIENTRY DosTmrQueryTime (PQWORD time) 
  9736.  
  9737.  Parameters 
  9738.  
  9739.  time(PQWORD)  output 
  9740.  
  9741.  Returns 
  9742.  
  9743.  ulrc (APIRET)  returns 
  9744.            Return Code. 
  9745.  
  9746.            DosTmrQueryTime returns one of the following values 
  9747.  
  9748.            0              NO_ERROR 
  9749.  
  9750.            87             ERROR_INVALID_PARAMETER 
  9751.  
  9752.            99             ERROR_DEVICE_IN_USE 
  9753.  
  9754.            535            ERROR_TMR_NO_DEVICE 
  9755.  
  9756.            536            ERROR_TMR_INVALID_TIME 
  9757.  
  9758.  Example Code 
  9759.  
  9760.   void int3(void);
  9761.  
  9762.   int main(int argc, char *argv[], char *envp[])
  9763.   {
  9764.      QWORD start_time;
  9765.      QWORD end_time;
  9766.      QWORD interval;
  9767.  
  9768.      ULONG freq;
  9769.      APIRET rc;
  9770.  
  9771.      rc=DosTmrQueryTime( start_time);
  9772.      printf("DosTmrQueryTime rc=%u time=0x%08x%08x\n",rc,start_time.ulHi,start_time.ulLo);
  9773.  
  9774.      DosSleep(100);
  9775.      printf("Sleeping 100ms\n");
  9776.  
  9777.      rc=DosTmrQueryTime( end_time);
  9778.      printf("DosTmrQueryTime rc=%u time=0x%08x%08x\n",rc,end_time.ulHi,end_time.ulLo);
  9779.  
  9780.      rc=DosTmrQueryFreq( freq);
  9781.      printf("DosTmrQueryFreq rc=%u freq=%uHz\n",rc,freq);
  9782.  
  9783.      interval.ulLo = end_time.ulLo - start_time.ulLo;
  9784.      interval.ulHi = (end_time.ulLo >= start_time.ulLo) ?
  9785.                          end_time.ulHi - start_time.ulHi
  9786.                          end_time.ulHi - start_time.ulHi - 1;
  9787.      printf("Time interval=0x%08x%08x units=%uns\n",interval.ulHi,interval.ulLo,1000000000/freq);
  9788.      if (interval.ulHi == 0) printf("Appox. %uns\n",interval.ulLo*(1000000000/freq));
  9789.  
  9790.      return 0;
  9791.   }
  9792.  
  9793.  
  9794. ΓòÉΓòÉΓòÉ 5.44. DosVerifyPidTid ΓòÉΓòÉΓòÉ
  9795.  
  9796. Purpose 
  9797.  
  9798. DosVerifyPidTid validates a PID/TID pair. If the thread and process exist, then 
  9799. a zero return code is set; otherwise the return code indicates whether the 
  9800. thread or the process is invalid. 
  9801.  
  9802. Syntax 
  9803.  
  9804. #define INCL_DOSMISC
  9805. #include  os2.h>
  9806.  
  9807.  APIRET APIENTRY DosVerifyPidTid (PID pid, TID tid) 
  9808.  
  9809.  Parameters 
  9810.  
  9811.  pid (PID)  input 
  9812.  
  9813.  tid (TID)  input 
  9814.  
  9815.  Returns 
  9816.  
  9817.  ulrc (APIRET)  returns 
  9818.            Return Code. 
  9819.  
  9820.            DosVerifyPidTid returns one of the following values 
  9821.  
  9822.            0              NO_ERROR 
  9823.  
  9824.            303            ERROR_INVALID_PROCID 
  9825.  
  9826.            309            ERROR_INVALID_THREADID 
  9827.  
  9828.  Related Functions 
  9829.  
  9830.      DosCreateThread 
  9831.  
  9832.      DosExecPgm 
  9833.  
  9834.  Example Code 
  9835.  
  9836.   int main(int argc, char *argv[], char *envp[])
  9837.   {
  9838.      PID pid=0;
  9839.      TID tid=1;
  9840.      int i;
  9841.      APIRET rc;
  9842.  
  9843.      if (argc 2) {
  9844.         printf("VPIDTID /P=pid [/T=tid]\n");
  9845.         return;
  9846.      } /* endif */
  9847.  
  9848.      for (i=1; i(argc ;++i ) {
  9849.      if (strnicmp (argv[i],"/P=",3)==0) pid=strtoul (argv[i]+3, NULL,16);
  9850.      else if (strnicmp (argv[i],"/T=",3)==0)
  9851.      tid=strtoul (argv[i]+3, NULL,16);
  9852.      } /* endfor */
  9853.  
  9854.      if (pid == 0) {
  9855.         printf("VPIDTID /P=pid [/T=tid\n");
  9856.         return;
  9857.      } /* endif */
  9858.  
  9859.      rc=DosVerifyPidTid (pid,tid);
  9860.  
  9861.      printf("Verify pid=0x%04x tid=0x%04x rc=%u\n", pid,tid,rc);
  9862.  
  9863.      return 0;
  9864.   }
  9865.  
  9866.  
  9867. ΓòÉΓòÉΓòÉ 5.45. DosWrite ΓòÉΓòÉΓòÉ
  9868.  
  9869. Purpose 
  9870.  
  9871. DosWrite writes a specified number of bytes from a buffer to the specified disk 
  9872.  
  9873. Syntax 
  9874.  
  9875. #define INCL_DOSFILEMGR
  9876. #include  os2.h>
  9877.  
  9878.  APIRET DosWrite (HFILE hFile,  PVOID pBuffer, ULONG cbWrite, PULONG pcbActual) 
  9879.  
  9880.  Parameters 
  9881.  
  9882.  hFile (HFILE)  input 
  9883.            File handle obtained from DosOpen. 
  9884.  
  9885.  pBuffer (PVOID)  input 
  9886.            Address of the buffer that contains the data to write. 
  9887.  
  9888.  cbWrite (ULONG)  input 
  9889.            The number of bytes to write. The raw file system requires that the 
  9890.            number of bytes be a multiple of the sector size (512). 
  9891.  
  9892.  pcbActual (PULONG)  output 
  9893.            Address of the variable to receive the number of bytes actually 
  9894.            written. 
  9895.  
  9896.  Returns 
  9897.  
  9898.  ulrc (APIRET)  returns 
  9899.            Return Code. 
  9900.  
  9901.            DosWrite returns one of the following values 
  9902.  
  9903.            0              NO_ERROR 
  9904.  
  9905.            5               ERROR_ACCESS_DENIED 
  9906.  
  9907.            6              ERROR_INVALID_HANDLE 
  9908.  
  9909.            19              ERROR_WRITE_PROTECT 
  9910.  
  9911.            26             ERROR_NOT_DOS_DISK 
  9912.  
  9913.            29              ERROR_WRITE_FAULT 
  9914.  
  9915.            33             ERROR_LOCK_VIOLATION 
  9916.  
  9917.            87             ERROR_INVALID_PARAMETER 
  9918.  
  9919.            109            ERROR_BROKEN_PIPE 
  9920.  
  9921.  Remarks 
  9922.  
  9923.  DosWrite begins writing at the current file pointer position. The file pointer 
  9924.  is updated to where the write completed. 
  9925.  
  9926.  If there is not enough space on the disk or diskette to write all of the bytes 
  9927.  specified by cbWrite, the DosWrite does not write any bytes. An error is 
  9928.  returned and pcbActual is set to zero. 
  9929.  
  9930.  Using the raw file system on logical partitions requires you to lock and 
  9931.  unlock the volume using the DosDevIOCtl Category 8, DSK_LOCKDRIVE and 
  9932.  DSK_UNLOCKDRIVE. Writes will not succeed until the logical drive is locked. 
  9933.  
  9934.  The raw file system requires that the number of bytes written be a multiple of 
  9935.  the sector size (512). 
  9936.  
  9937.  Related Functions 
  9938.  
  9939.      DosOpen 
  9940.  
  9941.      DosListIO 
  9942.  
  9943.      DosRead 
  9944.  
  9945.      DosSetFilePtr 
  9946.  
  9947.  Example Code 
  9948.  
  9949.  The following is NOT a complete usable program.  It is simply intended  to 
  9950.  provide an idea of how to use Raw I/O File System APIs (e.g. DosOpen, DosRead, 
  9951.  DosWrite, DosSetFilePtr, and DosClose). 
  9952.  
  9953.  This example opens physical disk #1 for reading and physical disk #2  for 
  9954.  writing.  DosSetFilePtr is used to set the pointer to the beginning of the 
  9955.  disks. Using DosRead and DosWrite, 10 megabytes of data is transferred from 
  9956.  disk #1 to disk #2. Finally, DosClosed is issued to close the disk handles. 
  9957.  
  9958.  It is assumed that the size of each of the two disks is at least 10 megabytes. 
  9959.  
  9960.   #define INCL_DOSFILEMGR          /* Include File Manager APIs */
  9961.   #define INCL_DOSMEMMGR           /* Includes Memory Management APIs */
  9962.   #define INCL_DOSERRORS           /* DOS Error values */
  9963.   #include  os2.h>
  9964.   #include  stdio.h>
  9965.   #include  string.h>
  9966.  
  9967.   #define SIXTY_FOUR_K 0x10000
  9968.   #define ONE_MEG     0x100000
  9969.   #define TEN_MEG     10*ONE_MEG
  9970.  
  9971.   #define UNC_DISK1  "\\\\.\\Physical_Disk1"
  9972.   #define UNC_DISK2  "\\\\.\\Physical_Disk2"
  9973.  
  9974.   int main(void) {
  9975.      HFILE  hfDisk1        = 0;      /* Handle for disk #1 */
  9976.      HFILE  hfDisk2        = 0;      /* Handle for disk #2 */
  9977.      ULONG  ulAction       = 0;      /* Action taken by DosOpen */
  9978.      ULONG  cbRead         = 0;      /* Bytes to read */
  9979.      ULONG  cbActualRead   = 0;      /* Bytes read by DosRead */
  9980.      ULONG  cbWrite        = 0;      /* Bytes to write */
  9981.      ULONG  ulLocation     = 0;
  9982.      ULONG  cbActualWrote  = 0;      /* Bytes written by DosWrite */
  9983.      UCHAR  uchFileName1[20]  = UNC_DISK1, /* UNC Name of disk 1 */
  9984.             uchFileName2[20]  = UNC_DISK2; /* UNC Name of disk 2 */
  9985.      PBYTE  pBuffer        = 0;
  9986.      ULONG  cbTotal        = 0;
  9987.  
  9988.      APIRET rc             = NO_ERROR;            /* Return code */
  9989.  
  9990.      /* Open a raw file system disk #1 for reading */
  9991.      rc = DosOpen(uchFileName1,               /* File name */
  9992.                    hfDisk1,                   /* File handle */
  9993.                    ulAction,                  /* Action taken by DosOpen */
  9994.                   0L,                         /* no file size */
  9995.                   FILE_NORMAL,                /* File attribute */
  9996.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  9997.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  9998.                   OPEN_ACCESS_READONLY,
  9999.                   0L);                        /* No extented attributes */
  10000.      if (rc != NO_ERROR) {
  10001.         printf("DosOpen error rc = %u\n", rc);
  10002.         return(1);
  10003.      } /* endif */
  10004.  
  10005.      /* Set the pointer to the begining of the disk */
  10006.      rc = DosSetFilePtr(hfDisk1,      /* Handle for disk 1 */
  10007.                         0L,           /* Offset must be multiple of 512 */
  10008.                         FILE_BEGIN,   /* Begin of the disk */
  10009.                          ulLocation); /* New pointer location */
  10010.      if (rc != NO_ERROR) {
  10011.         printf("DosSetFilePtr error rc = %u\n", rc);
  10012.         return(1);
  10013.      } /* endif */
  10014.  
  10015.      /* Open a raw file system disk #2 for writing */
  10016.      rc = DosOpen(uchFileName2,               /* File name */
  10017.                    hfDisk2,                   /* File handle */
  10018.                    ulAction,                  /* Action taken by DosOpen */
  10019.                   0L,                         /* no file size */
  10020.                   FILE_NORMAL,                /* File attribute */
  10021.                   OPEN_ACTION_OPEN_IF_EXISTS, /* Open existing disk */
  10022.                   OPEN_SHARE_DENYNONE |       /* Access mode */
  10023.                   OPEN_ACCESS_READWRITE,
  10024.                   0L);                        /* No extented attributes */
  10025.      if (rc != NO_ERROR) {
  10026.         printf("DosOpen error rc = %u\n", rc);
  10027.         return(1);
  10028.      } /* endif */
  10029.  
  10030.      /* Set the pointer to the begining of the disk */
  10031.      rc = DosSetFilePtr(hfDisk2,      /* Handle for disk 1 */
  10032.                         0L,           /* Offset must be multiple of 512 */
  10033.                         FILE_BEGIN,   /* Begin of the disk */
  10034.                          ulLocation); /* New pointer location */
  10035.      if (rc != NO_ERROR) {
  10036.         printf("DosSetFilePtr error rc = %u\n", rc);
  10037.         return(1);
  10038.      } /* endif */
  10039.  
  10040.  
  10041.      /* Allocate 64K of memory for transfer operations */
  10042.      rc = DosAllocMem((PPVOID) pBuffer, /* Pointer to buffer */
  10043.                        SIXTY_FOUR_K,      /* Buffer size */
  10044.                        PAG_COMMIT |     /* Allocation flags */
  10045.                        PAG_READ |
  10046.                        PAG_WRITE);
  10047.      if (rc != NO_ERROR) {
  10048.         printf("DosAllocMem error rc = %u\n", rc);
  10049.         return(1);
  10050.      } /* endif */
  10051.  
  10052.      cbRead = SIXTY_FOUR_K;
  10053.      while (rc == NO_ERROR    cbTotal   TEN_MEG) {
  10054.  
  10055.         /* Read from #1 */
  10056.         rc = DosRead(hfDisk1,         /* Handle for disk 1 */
  10057.                      pBuffer,         /* Pointer to buffer */
  10058.                      cbRead,          /* Size must be multiple of 512 */
  10059.                       cbActualRead);  /* Actual read by DosOpen */
  10060.         if (rc) {
  10061.            printf("DosRead error  return code = %u\n", rc);
  10062.            return 1;
  10063.         }
  10064.  
  10065.         /* Write to disk #2 */
  10066.         cbWrite = cbActualRead;
  10067.         rc = DosWrite(hfDisk2,         /* Handle for disk 2 */
  10068.                       pBuffer,         /* Pointer to buffer */
  10069.                       cbWrite,         /* Size must be multiple of 512 */
  10070.                        cbActualWrote); /* Actual written by DosOpen */
  10071.         if (rc) {
  10072.            printf("DosWrite error  return code = %u\n", rc);
  10073.            return 1;
  10074.         }
  10075.         if (cbActualRead != cbActualWrote) {
  10076.            printf("Bytes read (%u) does not equal bytes written (%u)\n",
  10077.                   cbActualRead, cbActualWrote);
  10078.            return 1;
  10079.         }
  10080.         cbTotal += cbActualRead; /* Update total transferred */
  10081.      }
  10082.  
  10083.      printf("Transfer successfully %d bytes from disk #1 to disk #2.\n",
  10084.             cbTotal);
  10085.  
  10086.      /* Free allocated memmory */
  10087.      rc = DosFreeMem(pBuffer);
  10088.      if (rc != NO_ERROR) {
  10089.         printf("DosFreeMem error  return code = %u\n", rc);
  10090.         return 1;
  10091.      }
  10092.  
  10093.      rc = DosClose(hfDisk1);
  10094.      if (rc != NO_ERROR) {
  10095.         printf("DosClose error  return code = %u\n", rc);
  10096.         return 1;
  10097.      }
  10098.  
  10099.      rc = DosClose(hfDisk2);
  10100.      if (rc != NO_ERROR) {
  10101.         printf("DosClose error  return code = %u\n", rc);
  10102.         return 1;
  10103.      }
  10104.   return NO_ERROR;
  10105.   }
  10106.  
  10107.  
  10108. ΓòÉΓòÉΓòÉ 6. Raw File System APIs ΓòÉΓòÉΓòÉ
  10109.  
  10110. This chapter contains an alphabetic list of the following data types. 
  10111.  
  10112.      FILELOCKL 
  10113.  
  10114.      FILEFINDBUF3L 
  10115.  
  10116.      FILEFINDBUF4L 
  10117.  
  10118.      FILESTATUS3L 
  10119.  
  10120.      FILESTATUS4L 
  10121.  
  10122.      MPAffinity 
  10123.  
  10124.  
  10125. ΓòÉΓòÉΓòÉ 6.1. FILEFINDBUF3L ΓòÉΓòÉΓòÉ
  10126.  
  10127. Definition 
  10128.  
  10129. Find the file buffer data structure 
  10130.  
  10131. Syntax 
  10132.  
  10133. typedef struct  FILEFINDBUF3L
  10134.   ULONG       oNextEntryOffset
  10135.   FDATE       fdateCreation
  10136.   FTIME       ftimeCreation
  10137.   FDATE       fdateLastAccess
  10138.   FTIME       ftimeLastAccess
  10139.   FDATE       fdateLastWrite
  10140.   FTIME       ftimeLastWrite
  10141.   LONGLONG    cbFile
  10142.   LONGLONG    cbFileAlloc
  10143.   ULONG       attrFile
  10144.   UCHAR       cchName
  10145.   CHAR        achName CCHMAXPATHCOMP
  10146.   FILEFINDBUF3L
  10147.  
  10148. typedef FILEFINDBUF3L *PFILEFINDBUF3L;
  10149.  
  10150. Fields 
  10151.  
  10152.  fdateCreation  FDATE) 
  10153.            Date of file creation. 
  10154.  
  10155.  ftimeCreation  FTIME) 
  10156.            Time of file creation. 
  10157.  
  10158.  fdateLastAccess  FDATE) 
  10159.            Date of last access. 
  10160.  
  10161.  ftimeLastAccess  FTIME) 
  10162.            Time of last access. 
  10163.  
  10164.  fdateLastWrite  FDATE) 
  10165.            Date of last write. 
  10166.  
  10167.  ftimeLastWrite  FTIME) 
  10168.            Time of last write. 
  10169.  
  10170.  cbFile  LONGLONG) 
  10171.            Size of file. 
  10172.  
  10173.  cbFileAlloc  LONGLONG) 
  10174.            Allocated size. 
  10175.  
  10176.  attrFile  ULONG) 
  10177.            File attributes. 
  10178.  
  10179.  cchName  UCHAR) 
  10180.            Length of file name. 
  10181.  
  10182.  achName CCHMAXPATHCOMP  CHAR) 
  10183.            File name including null terminator. 
  10184.  
  10185.  
  10186. ΓòÉΓòÉΓòÉ 6.2. FILEFINDBUF4L ΓòÉΓòÉΓòÉ
  10187.  
  10188. Definition 
  10189.  
  10190. Level 12 (32-bit) information (used with EAs). 
  10191.  
  10192. Syntax 
  10193.  
  10194. typedef struct  FILEFINDBUF4
  10195.   ULONG       oNextEntryOffset
  10196.   FDATE       fdateCreation
  10197.   FTIME       ftimeCreation
  10198.   FDATE       fdateLastAccess
  10199.   FTIME       ftimeLastAccess
  10200.   FDATE       fdateLastWrite
  10201.   FTIME       ftimeLastWrite
  10202.   LONGLONG    cbFile
  10203.   LONGLONG    cbFileAlloc
  10204.   ULONG       attrFile
  10205.   ULONG       cbList
  10206.   UCHAR       cchName
  10207.   CHAR        achName CCHMAXPATHCOMP
  10208.   FILEFINDBUF4
  10209.  
  10210. typedef FILEFINDBUF4L *PFILEFINDBUFL4;
  10211.  
  10212. Fields 
  10213.  
  10214.  oNextEntryOffset  ULONG) 
  10215.            Offset of next entry. 
  10216.  
  10217.  fdateCreation  FDATE) 
  10218.            Date of file creation. 
  10219.  
  10220.  ftimeCreation  FTIME) 
  10221.            Time of file creation. 
  10222.  
  10223.  fdateLastAccess  FDATE) 
  10224.            Date of last access. 
  10225.  
  10226.  ftimeLastAccess  FTIME) 
  10227.            Time of last access. 
  10228.  
  10229.  fdateLastWrite  FDATE) 
  10230.            Date of last write. 
  10231.  
  10232.  ftimeLastWrite  FTIME) 
  10233.            Time of last write. 
  10234.  
  10235.  cbFile  LONGLONG) 
  10236.            Size of file. 
  10237.  
  10238.  cbFileAlloc  LONGLONG) 
  10239.            Allocated size. 
  10240.  
  10241.  attrFile  ULONG) 
  10242.            File attributes. 
  10243.  
  10244.  cbList  ULONG) 
  10245.            Size of the file s extended attributes. 
  10246.  
  10247.            The size is measured in bytes and is the size of the file s entire 
  10248.            extended attribute set on the disk. 
  10249.  
  10250.  cchName  UCHAR) 
  10251.            Length of file name. 
  10252.  
  10253.  achName CCHMAXPATHCOMP  CHAR) 
  10254.            File name including null terminator. 
  10255.  
  10256.  
  10257. ΓòÉΓòÉΓòÉ 6.3. FILELOCKL ΓòÉΓòÉΓòÉ
  10258.  
  10259. Definition 
  10260.  
  10261. FILELOCKL data structure 
  10262.  
  10263. Syntax 
  10264.  
  10265. typedef struct  FILELOCKL
  10266.   LONGLONG       lOffset
  10267.   LONGLONG       lRange
  10268.   FILELOCK
  10269.  
  10270. typedef FILELOCK *PFILELOCK;
  10271.  
  10272. Fields 
  10273.  
  10274.  lOffset  LONGLONG) 
  10275.            Offset to the beginning of the lock (or unlock) range. 
  10276.  
  10277.  lRange  LONGLONG) 
  10278.            Length, in bytes, of the lock (or unlock) range. 
  10279.  
  10280.            A value of 0 indicates that locking (or unlocking) is not required. 
  10281.  
  10282.  
  10283. ΓòÉΓòÉΓòÉ 6.4. FILESTATUS3L ΓòÉΓòÉΓòÉ
  10284.  
  10285. Definition 
  10286.  
  10287. Level 11 (32-bit) (FIL_STANDARDL) information 
  10288.  
  10289. Syntax 
  10290.  
  10291. typedef struct  FILESTATUS3L
  10292.   FDATE       fdateCreation
  10293.   FTIME       ftimeCreation
  10294.   FDATE       fdateLastAccess
  10295.   FTIME       ftimeLastAccess
  10296.   FDATE       fdateLastWrite
  10297.   FTIME       ftimeLastWrite
  10298.   LONGLONG    cbFile
  10299.   LONGLONG    cbFileAlloc
  10300.   ULONG       attrFile
  10301.   FILESTATUS3L
  10302.  
  10303. typedef FILESTATUS3L *PFILESTATUS3L;
  10304.  
  10305. Fields 
  10306.  
  10307.  fdateCreation  FDATE) 
  10308.            Date of file creation. 
  10309.  
  10310.  ftimeCreation  FTIME) 
  10311.            Time of file creation. 
  10312.  
  10313.  fdateLastAccess  FDATE) 
  10314.            Date of last access. 
  10315.  
  10316.  ftimeLastAccess  FTIME) 
  10317.            Time of last access. 
  10318.  
  10319.  fdateLastWrite  FDATE) 
  10320.            Date of last write. 
  10321.  
  10322.  ftimeLastWrite  FTIME) 
  10323.            Time of last write. 
  10324.  
  10325.  cbFile  LONGLONG) 
  10326.            File size (end of data). 
  10327.  
  10328.  cbFileAlloc  LONGLONG) 
  10329.            File allocated size. 
  10330.  
  10331.  attrFile  ULONG) 
  10332.            Attributes of the file. 
  10333.  
  10334.  
  10335. ΓòÉΓòÉΓòÉ 6.5. FILESTATUS4L ΓòÉΓòÉΓòÉ
  10336.  
  10337. Definition 
  10338.  
  10339. Level 12 (32-bit) (FIL_QUERYEASIZEL) information 
  10340.  
  10341. Syntax 
  10342.  
  10343. typedef struct  FILESTATUS4L
  10344.   FDATE       fdateCreation
  10345.   FTIME       ftimeCreation
  10346.   FDATE       fdateLastAccess
  10347.   FTIME       ftimeLastAccess
  10348.   FDATE       fdateLastWrite
  10349.   FTIME       ftimeLastWrite
  10350.   LONGLONG    cbFile
  10351.   LONGLONG    cbFileAlloc
  10352.   ULONG       attrFile
  10353.   ULONG       cbList
  10354.   FILESTATUS4L
  10355.  
  10356. typedef FILESTATUS4L *PFILESTATUS4L;
  10357.  
  10358. Fields 
  10359.  
  10360.  fdateCreation  FDATE) 
  10361.            Date of file creation. 
  10362.  
  10363.  ftimeCreation  FTIME) 
  10364.            Time of file creation. 
  10365.  
  10366.  fdateLastAccess  FDATE) 
  10367.            Date of last access. 
  10368.  
  10369.  ftimeLastAccess  FTIME) 
  10370.            Time of last access. 
  10371.  
  10372.  fdateLastWrite  FDATE) 
  10373.            Date of last write. 
  10374.  
  10375.  ftimeLastWrite  FTIME) 
  10376.            Time of last write. 
  10377.  
  10378.  cbFile  LONGLONG) 
  10379.            File size (end of data). 
  10380.  
  10381.  cbFileAlloc  LONGLONG) 
  10382.            File allocated size. 
  10383.  
  10384.  attrFile  ULONG) 
  10385.            Attributes of the file. 
  10386.  
  10387.  cbList  ULONG) 
  10388.            Length of entire EA set. 
  10389.  
  10390.  
  10391. ΓòÉΓòÉΓòÉ 6.6. ListIOL ΓòÉΓòÉΓòÉ
  10392.  
  10393. Definition 
  10394.  
  10395. ListIOL data structure 
  10396.  
  10397. Syntax 
  10398.  
  10399. typedef struct  ListIOL
  10400.   HFILE       hFile
  10401.   ULONG       CmdFlag
  10402.   LONGLONG    Offset
  10403.   PVOID       pBuffer
  10404.   ULONG       NumBytes
  10405.   ULONG       Actual
  10406.   ULONG       RetCode
  10407.   ULONG       Reserved
  10408.   ULONG       Reserved2[3]
  10409.   ULONG       Reserved3[2]
  10410.   ListIOL
  10411.  
  10412. typedef  ListIOL * ListIOL
  10413.  
  10414. Fields 
  10415.  
  10416.  hFile  HFILE ) 
  10417.            File handle. 
  10418.  
  10419.  CmdFlag  ULONG ) 
  10420.            Command Flag. 
  10421.  
  10422.  Offset  LONGLONG) 
  10423.            Seek offse.t 
  10424.  
  10425.  pBuffer  PVOID ) 
  10426.            Pointer to buffer. 
  10427.  
  10428.  NumBytes  ULONG ) 
  10429.            Number of bytes to read/write. 
  10430.  
  10431.  Actual  ULONG ) 
  10432.            Actual number of bytes to read/write. 
  10433.  
  10434.  RetCode  ULONG ) 
  10435.            Operation return code. 
  10436.  
  10437.  Reserved  ULONG ) 
  10438.            (Internal.) 
  10439.  
  10440.  Reserved2[3] ULONG ) 
  10441.            (Internal). 
  10442.  
  10443.   Reserved3[2] ULONG ) 
  10444.            (Internal). 
  10445.  
  10446.  
  10447. ΓòÉΓòÉΓòÉ 6.7. MPAffinity ΓòÉΓòÉΓòÉ
  10448.  
  10449. Definition 
  10450.  
  10451. Multi-Processor affinity mask. The mask contains 1 bit per processor and 
  10452. supports a maximum of 64 processors. 
  10453.  
  10454. Syntax 
  10455.  
  10456. typedef struct  MPAffinity
  10457.   ULONG       mask [2]
  10458.  MPAFFINITY
  10459.  
  10460. typedef  MPAffinity *MPAffinity
  10461.  
  10462. Fields 
  10463.  
  10464.  mask  ULONG ) 
  10465.            CPUs 0 through 31 in [0] and CPUs 32 through 63 in [1]. 
  10466.  
  10467.            Non-existent processors are represented as reset bits (0). 
  10468.  
  10469.  
  10470. ΓòÉΓòÉΓòÉ 7. IOCtls ΓòÉΓòÉΓòÉ
  10471.  
  10472. This chapter contains the following IOCtl commands. 
  10473.  
  10474. Category        Function        Description
  10475. 08h             69h             Logical Volume Management
  10476. 80h             0Eh             Query HardDrive Geometry and
  10477.                                 Physical Parameters
  10478.  
  10479.  
  10480. ΓòÉΓòÉΓòÉ 7.1. Logical Volume ManagementDSK_LVMMGMT(69h) ΓòÉΓòÉΓòÉ
  10481.  
  10482. Purpose 
  10483.  
  10484.  This IOCtl may be used with any logical volume to which a drive letter has 
  10485. been assigned. This function will be used by FORMAT and will also be of use to 
  10486. those writing disk utilities for OS/2. 
  10487.  
  10488. Parameter Packet Format 
  10489.  
  10490. Field                      Length              C Datatype
  10491. Command Information        BYTE                UCHAR
  10492. Drive Unit                 BYTE                UCHAR
  10493. Table Number               WORD                USHORT
  10494. LSN                        4 BYTES             ULONG
  10495.  
  10496.  Command Information 
  10497.       Command information may be 
  10498.  
  10499.       0              Identify Volume Type 
  10500.  
  10501.       1              Enable Bad Block Relocation 
  10502.  
  10503.       2              Disable Bad Block Relocation 
  10504.  
  10505.       3              Get Bad Block Information 
  10506.  
  10507.       4              Get Table Size 
  10508.  
  10509.       5              Get Relocated Sector List 
  10510.  
  10511.       6              Get Relocated Data 
  10512.  
  10513.       7              Remove Relocation Table Entry 
  10514.  
  10515.       8              Clear Relocation Table 
  10516.  
  10517.       9              Get Drive Name 
  10518.  
  10519.       The Identify Volume Type command provides a way to determine whether a 
  10520.       volume is a Compatibility or LVM Volume. 
  10521.  
  10522.       The Enable Bad Block Relocation command enables bad block relocation on 
  10523.       the specified volume if that volume supports it. 
  10524.  
  10525.       The Disable Bad Block Relocation command disables bad block relocation on 
  10526.       the specified volume. 
  10527.  
  10528.       Get Bad Block Information returns the total number of bad block 
  10529.       relocations which are currently in effect for the specified volume, as 
  10530.       well as the number of relocation tables being used to perform bad block 
  10531.       relocation for the specified volume.  There is one bad block relocation 
  10532.       table per physical disk partition, so, for LVM volumes employing drive 
  10533.       linking, there may be several such tables. 
  10534.  
  10535.       Get Table Size returns the number of active entries in the specified bad 
  10536.       block relocation table, as well as the maximum number of entries that the 
  10537.       table can hold.  The size of a bad block relocation table is dependent 
  10538.       upon the size of the partition it is supporting.  Larger partitions have 
  10539.       larger relocation tables, while smaller partitions have smaller 
  10540.       relocation tables. 
  10541.  
  10542.       Get Relocated Sector List returns an array of Logical Sector Numbers 
  10543.       (LSN).  Each LSN in the array is a sector whose data had to be relocated 
  10544.       because of a problem writing to that sector.  The array returned is 
  10545.       specific to a Relocation Table.  The user supplied buffer must be large 
  10546.       enough to hold the entire array.  The size of the array can be determined 
  10547.       by using the Get Table Size command to find the number of active entries 
  10548.       in the table, and then multiplying that value by the size of a Logical 
  10549.       Sector Number (currently, 4 bytes). 
  10550.  
  10551.       Get Relocated Data returns the data associated with a sector that appears 
  10552.       in a relocation table for the specified volume.  The user supplied buffer 
  10553.       must be at least 512 bytes in length, because 512 bytes are returned. 
  10554.  
  10555.       Remove Relocation Table Entry removes the specified LSN from the 
  10556.       relocation tables on the specified volume.  This function is typically 
  10557.       used by utilities which adjust the file system on a volume so that all 
  10558.       LSNs requiring relocation are removed from use.  Since the file system 
  10559.       will never use these LSNs again, they can be safely removed from the 
  10560.       relocation tables for the volume, thereby freeing those entries to be 
  10561.       used again. 
  10562.  
  10563.       Clear Relocation Table is used to remove all of the entries in a 
  10564.       relocation table in a single operation.  This function is intended to be 
  10565.       used by FORMAT immediately before a long format is performed.  Typically, 
  10566.       FORMAT will disable bad block relocation and clear the bad block 
  10567.       relocation tables prior to a long format so that all bad sectors may be 
  10568.       detected by FORMAT.  FORMAT will place any bad sectors detected into the 
  10569.       bad block list for the appropriate file system. 
  10570.  
  10571.       Get Drive Name is used to return the user defined name associated with 
  10572.       the physical drive on which the specified relocation table resides.  This 
  10573.       function can be used to identify which physical drive contains a specific 
  10574.       relocation table associated with a volume.  The name returned will not 
  10575.       exceed 20 characters. 
  10576.  
  10577.  Drive Unit 
  10578.       Drive Unit is used only when the IOCtl is issued without using a 
  10579.       previously allocated file handle. In this case, the IOCtl must be issued 
  10580.       with a file handle of  1. Drive Unit values are 0=A, 1=B, 2=C, etc. 
  10581.  
  10582.  Table Number 
  10583.       Table Number is the number of the relocation table to operate on. This 
  10584.       field is not used for commands 0 3, and 6 8. 
  10585.  
  10586.  LSN 
  10587.       LSN is the logical sector number of sector requiring relocation. This 
  10588.       field is used only by commands 6 and 7. 
  10589.  
  10590.  Data Packet Format 
  10591.  
  10592.   Field                      Length              C Datatype
  10593.   Return Value               BYTE                UCHAR
  10594.   Buffer                     4 BYTEs             void*
  10595.  
  10596.  Return Value 
  10597.       Return Value is set by every command that this IOCtl accepts. The 
  10598.       specific meaning of the value it is set to is dependent upon the command 
  10599.       issued. 
  10600.  
  10601.  Buffer 
  10602.       Buffer is a pointer to an area of memory large enough to hold any return 
  10603.       value associated with the command issued. Some commands do not make use 
  10604.       of Buffer. For these commands, Buffer should be NULL. 
  10605.  
  10606.  Values Returned 
  10607.       Command Information and possible return values are 
  10608.  
  10609.   Command Information Return Value        Buffer
  10610.   0                   1 = Compatibility V Unused
  10611.                       2 = Logical Volume
  10612.   1                   0 = Success         Unused
  10613.                       1 = Failure
  10614.   2                   0 = Success         Unused
  10615.                       1 = Failure
  10616.   3                   0 = Success         typedef struct_BadBlockInf
  10617.                       1 = Failure         ULONG Total_Relocations;
  10618.                                           ULONG Total_Tables;
  10619.                                           }BadBlockInfo;
  10620.   4                   0 = Success         typedef struct_BadBlackInf
  10621.                       1 = Failure         ULONG Active_Relocations;
  10622.                                           ULONG Max_Relocations;
  10623.                                           }BadBlockTableInfo;
  10624.   5                   0 = Success         Array of LSNs.
  10625.                       1 = Failure         Each entry in array is
  10626.                                           sector requiring relocatio
  10627.   6                   0 = Success         Data written to
  10628.                       1 = Failure         specified sector
  10629.   7                   0 = Success         Unused
  10630.                       1 = Failure
  10631.   8                   0 = Success         Unused
  10632.                       1 = Failure
  10633.   9                   0 = Success         Text of name being
  10634.                       1 = Failure         returned by this function.
  10635.                                           Name will be null terminat
  10636.  
  10637.  Returns 
  10638.  
  10639.  Possible values are shown in the following list 
  10640.  
  10641.  0         NO_ERROR 
  10642.  
  10643.  6         ERROR_INVALID_HANDLE 
  10644.  
  10645.  15        ERROR_INVALID_DRIVE 
  10646.  
  10647.  31        ERROR_GEN_FAILURE 
  10648.  
  10649.  87        ERROR_INVALID_PARAMETER 
  10650.  
  10651.  
  10652. ΓòÉΓòÉΓòÉ 7.2. Query Hard Drive Geometry and Physical ParametersOEMHLP_QUERYDISKINFO (0Eh) ΓòÉΓòÉΓòÉ
  10653.  
  10654. Purpose 
  10655.  
  10656.  This function returns geometry and physical parameters about the specified 
  10657. physical hard disk, if available. This information is acquired from BIOS via 
  10658. INT 13h function 48h at system boot. 
  10659.  
  10660. Parameter Packet Format 
  10661.  
  10662. Field                            Length
  10663. Drive Number                     BYTE
  10664.  
  10665.  Drive Number 
  10666.       The BIOS drive number for which geometry and physical parameters are 
  10667.       requested. The value must be 80h or greater. 
  10668.  
  10669.  Data Packet Format 
  10670.  
  10671.   Field                                     Length
  10672.   Reserved                                  WORD
  10673.   Information Flags                         WORD
  10674.   Number of Physical Cylinders              DWORD
  10675.   Number of Physical Heads                  DWORD
  10676.   Number of Sectors Per Track               DWORD
  10677.   Number of Physical Sectors                QWORD
  10678.   Number of Bytes in a Sector               WORD
  10679.   Reserved                                  DWORD
  10680.   I/O Port Base Address                     WORD
  10681.   Control Port Address                      WORD
  10682.   Head Register Upper Nibble                BYTE
  10683.   Reserved                                  BYTE
  10684.   IRQ Information                           BYTE
  10685.   Block Count for ATA R/W Multiple          BYTE
  10686.   DMA Information                           BYTE
  10687.   PIO Information                           BYTE
  10688.   BIOS Selected Hardware Option Flags       WORD
  10689.   Reserved                                  WORD
  10690.   DPT Extension Revision                    BYTE
  10691.  
  10692.  Information Flags 
  10693.       Bits are defined as follows 
  10694.  
  10695.       Bit            Description 
  10696.  
  10697.       0              DMA boundary errors are handled transparently 
  10698.  
  10699.       1              The geometry returned in bytes 4 15 is valid 
  10700.  
  10701.       2              Media is removable. Bits 4 6 are not valid if this bit is 
  10702.                      0 
  10703.  
  10704.       3              Device supports write verify 
  10705.  
  10706.       4              Device has media change notification 
  10707.  
  10708.       5              Media is lockable 
  10709.  
  10710.       6              Device geometry is set to maximum and no media is present 
  10711.                      when this bit is set to 1. 
  10712.  
  10713.       7 15           Reserved 
  10714.  
  10715.  Number of Physical Cylinders 
  10716.       The number of physical cylinders on the physical drive. This field is 
  10717.       valid only if BIT 1 of the information flags is set to 1. 
  10718.  
  10719.  Number of Physical Heads 
  10720.       The number of physical heads on the physical drive. This field is valid 
  10721.       only if BIT 1 of the information flags is set to 1. 
  10722.  
  10723.  Number of Sectors Per Track 
  10724.       The number of sectors per track on the physical drive. This field is 
  10725.       valid only if BIT 1 of the information flags is set to 1. 
  10726.  
  10727.  Number of Physical Sectors 
  10728.       The number of physical sectors on the physical drive. 
  10729.  
  10730.  Number of Bytes in a Sector 
  10731.       The number of bytes per sector on the physical drive. 
  10732.  
  10733.  I/O Port Base Address 
  10734.       This word is the address of the data register in ATA Command Block. 
  10735.  
  10736.  Control Port Address 
  10737.       This word is the address of the ATA Control Block Register. 
  10738.  
  10739.  Head Register Upper Nibble 
  10740.       The upper nibble of this byte is logically ORed with the head number, or 
  10741.       upper 4 bits of the LBA, each time the disk is accessed. 
  10742.  
  10743.       Bit            Description 
  10744.  
  10745.       0 3            0 
  10746.  
  10747.       4              ATA DEV bit 
  10748.  
  10749.       5              1 
  10750.  
  10751.       6              LBA enabled (1 = enabled) 
  10752.  
  10753.       7              1 
  10754.  
  10755.  IRQ Information 
  10756.       Bits are defined as follows 
  10757.  
  10758.       Bit            Description 
  10759.  
  10760.       0 3            IRQ for this drive 
  10761.  
  10762.       4 7            0 
  10763.  
  10764.  Block Count for ATA R/W Multiple 
  10765.       If the hard disk was configured to use the READ/WRITE MULTIPLE command, 
  10766.       then this field contains the block size of the transfer in sectors. 
  10767.  
  10768.  DMA Information 
  10769.       If the BIOS has configured the system to perform multi-word DMA transfers 
  10770.       in place of the normal PIO transfers, this field specified the DMA mode 
  10771.       in the upper nibble, as per the ATA-2 or later definition, and the DMA 
  10772.       Channel in the lower nibble. ATA Channels which conform to SFF-8038i set 
  10773.       the DMA channel to 0. Note that the DMA Type field does not follow the 
  10774.       format of the data returned by the drive. The value of the DMA mode is 
  10775.       not limited to 2. 
  10776.  
  10777.       Bit            Description 
  10778.  
  10779.       0 3            DMA Channel 
  10780.  
  10781.       4 7            DMA Type 
  10782.  
  10783.  PIO Information 
  10784.       If the BIOS has configured the system to perform PIO data transfers other 
  10785.       than mode 0, this field specifies the PIO mode as per the ATA-2 or later 
  10786.       definition. 
  10787.  
  10788.       Bit            Description 
  10789.  
  10790.       0 3            PIO Type 
  10791.  
  10792.       4 7            0 
  10793.  
  10794.  BIOS Selected Hardware Option Flags 
  10795.       Bits are defined as follows 
  10796.  
  10797.       Bit            Description 
  10798.  
  10799.       0              Fast PIO accessing enabled 
  10800.  
  10801.       1              DMA accessing enabled 
  10802.  
  10803.       2              ATA READ/WRITE MULTIPLE accessing enabled 
  10804.  
  10805.       3              CHS translation enabled 
  10806.  
  10807.       4              LBA translation enabled 
  10808.  
  10809.       5              Removeable media 
  10810.  
  10811.       6              ATAPI device 
  10812.  
  10813.       7              32 bit transfer mode 
  10814.  
  10815.       8              ATAPI device uses command packet interrupt 
  10816.  
  10817.       9 10           Translation type 
  10818.  
  10819.                      00             Bit-shift translation 
  10820.  
  10821.                      01             LBA assisted translation 
  10822.  
  10823.                      10             Reserved 
  10824.  
  10825.                      11             Vendor specific translation 
  10826.  
  10827.       11             Ultra DMA accessing enabled 
  10828.  
  10829.       12 15          Reserved 
  10830.  
  10831.  DPT Extension Revision 
  10832.       Revision of DPT Extension provided by BIOS 
  10833.  
  10834.  Returns 
  10835.  
  10836.  Possible values are shown in the following list 
  10837.  
  10838.  0         NO_ERROR 
  10839.  
  10840.  87        ERROR_INVALID_PARAMETER 
  10841.  
  10842.  Remarks 
  10843.  
  10844.  Information in the data packet will be filled in, if BIOS supports INT 13h 
  10845.  Function 48h and if BIOS can access the entire hardfile through INT 13h 
  10846.  Function 42h and Function 43h. If either condition is not met, all fields in 
  10847.  the data packet with be 0. 
  10848.  
  10849.  
  10850. ΓòÉΓòÉΓòÉ 8. Network APIs ΓòÉΓòÉΓòÉ
  10851.  
  10852. This chapter contains an alphabetic list of the following Server Category APIs. 
  10853.  
  10854.      NetServerNameAdd or Net32ServerNameAdd 
  10855.  
  10856.      NetServerNameDel or Net32ServerNameDel 
  10857.  
  10858.      NetServerNameEnum or Net32ServerNameEnum 
  10859.  
  10860.  A number of Network APIs are multiple server name aware and will work in the 
  10861.  context of a servername, if the first parameter (the servername) is provided. 
  10862.  If no servername is provided and the API is issued locally, then the 
  10863.  information returned may be for shares, device queues, or sessions that exist 
  10864.  across all server names. If name conflicts exist, such as two shares with the 
  10865.  same name on different servernames, the API may act on the first match it 
  10866.  finds when no servername has been provided.The APIs that are multiple server 
  10867.  name aware include 
  10868.  
  10869.  Serial Device Category 
  10870.  
  10871.      NetCharDevQEnum 
  10872.  
  10873.      NetCharDevQGetInfo 
  10874.  
  10875.      NetCharDevQSetInfo 
  10876.  
  10877.      NetCharDevQPurge 
  10878.  
  10879.      NetCharDevQPurgeSelf 
  10880.  
  10881.  Share Category 
  10882.  
  10883.      NetShareEnum 
  10884.  
  10885.      NetShareGetInfo 
  10886.  
  10887.      NetShareSetInfo 
  10888.  
  10889.      NetShareAdd 
  10890.  
  10891.      NetShareDel 
  10892.  
  10893.      NetShareCheck 
  10894.  
  10895.  Session Category 
  10896.  
  10897.      NetSessionEnum 
  10898.  
  10899.      NetSessionGetInfo 
  10900.  
  10901.      NetSessionDel 
  10902.  
  10903.  Connection Category 
  10904.  
  10905.      NetConnectionEnum 
  10906.  
  10907.  
  10908. ΓòÉΓòÉΓòÉ 8.1. NetServerNameAdd or Net32ServerNameAdd ΓòÉΓòÉΓòÉ
  10909.  
  10910. Purpose 
  10911.  
  10912. NetServerNameAdd adds a secondary server computername to a server allowing 
  10913. network requests directed to the secondary server name to be received and 
  10914. processed by the server. 
  10915.  
  10916. Syntax 
  10917.  
  10918. #include  netcons.h>
  10919. #include  server.h>
  10920.  
  10921.  NetServerNameAdd (const UCHAR LSFAR* pszServerName, const UCHAR LSFAR* 
  10922.            pszAddName) 
  10923.  
  10924.  Net32ServerNameAdd (const UCHAR LSFAR* pszServerName, const UCHAR LSFAR* 
  10925.            pszAddName) 
  10926.  
  10927.  Parameters 
  10928.  
  10929.  pszServerName (const UCHAR LSFAR*)  input 
  10930.            Points to a NULL-terminated string containing the name of the server 
  10931.            to be added. 
  10932.  
  10933.  pszAddName (const UCHAR LSFAR*)  input 
  10934.  
  10935.  Returns 
  10936.  
  10937.  ulrc (APIRET)  returns for 32 bit 
  10938.  
  10939.  usrc (USHORT)  returns for 16 bit 
  10940.            Return Code. 
  10941.  
  10942.            NetServerNameAdd or Net32ServerNameAdd returns one of the following 
  10943.            values 
  10944.  
  10945.            0              NERR_Success 
  10946.  
  10947.            5              ERROR_ACCESS_DENIED 
  10948.  
  10949.            52             ERROR_DUP_NAME 
  10950.  
  10951.            53             ERROR_BAD_NETPATH 
  10952.  
  10953.            54             ERROR_NETWORK_BUSY 
  10954.  
  10955.            56             ERROR_TOO_MANY_CMDS 
  10956.  
  10957.            59             ERROR_UNEXP_NET_ERR 
  10958.  
  10959.            68             ERROR_TOO_MANY_NAMES 
  10960.  
  10961.            71             ERROR_REQ_NOT_ACCEP 
  10962.  
  10963.            87             ERROR_INVALID_PARAMETER 
  10964.  
  10965.            2102           NERR_NetNotStarted 
  10966.  
  10967.            2114           NERR_ServerNotStarted 
  10968.  
  10969.            2140           NERR_InternalError 
  10970.  
  10971.            2141           NERR_BadTransactConfig 
  10972.  
  10973.            2142           NERR_InvalidAPI 
  10974.  
  10975.            2468           NERR_TooManySrvNames 
  10976.  
  10977.  Remarks 
  10978.  
  10979.  The maximum number of names a server can support is defined by the manifest 
  10980.  SV_MAX_SRV_NAMES in server.h. 
  10981.  
  10982.  The machine must also be properly configured for the additional Netbios names 
  10983.  required as specified by the names parameter on the NETx= line of the 
  10984.  IBMLAN.INI file. 
  10985.  
  10986.  This API can be called from OS/2 workstations. Administrative or server 
  10987.  operator authority is required to call this API. 
  10988.  
  10989.  Related Functions 
  10990.  
  10991.      NetServerNameDel 
  10992.  
  10993.      NetServerNameEnum 
  10994.  
  10995.  Example Code 
  10996.  
  10997.  This example adds a servername called  Server18 , then enumerates the server 
  10998.  names in use and finally removes the  Server18  servername. 
  10999.  
  11000.   #define PURE_32
  11001.   #define INCL_DOS
  11002.   #define INCL_DOSERRORS
  11003.   #include  os2.h>
  11004.   #include  stdio.h>
  11005.   #include  stdlib.h>
  11006.   #include  string.h>
  11007.   #include  netcons.h>
  11008.   #include  server.h>
  11009.   int main(VOID)
  11010.   {
  11011.  
  11012.      struct server_info_0 LSFAR * pBuffer; /* pointer to enum return info */
  11013.      ULONG  ulBufLen=4096;                 /* length in bytes of enum buffer */
  11014.      ULONG  ulLevel=0;                     /* enum return info level */
  11015.      ULONG  ulEntriesRead=0;               /* total entries read from enum */
  11016.      ULONG  ulEntriesAvail=0;              /* total entries available from enum */
  11017.      CHAR   achServer[CNLEN+1];            /* remote server name or '\0' */
  11018.      CHAR   achName[CNLEN+1];              /* server name to add and delete */
  11019.      ULONG  ulReturnCode=0;                /* return code */
  11020.  
  11021.      strcpy(achName,"Server18");         /* initialize servername to use */
  11022.      achServer[0] = '\0';                  /* initialize for local API call */
  11023.  
  11024.      ulReturnCode = Net32ServerNameAdd(achServer,achName);
  11025.  
  11026.      if (ulReturnCode == NO_ERROR)
  11027.      {
  11028.         if ((pBuffer = malloc(ulBufLen)) != NULL)
  11029.         {
  11030.            ulReturnCode = Net32ServerNameEnum(achServer,
  11031.                                               ulLevel,
  11032.                                               (unsigned char *)pBuffer,
  11033.                                               ulBufLen,
  11034.                                                ulEntriesRead,
  11035.                                                ulEntriesAvail);
  11036.  
  11037.  
  11038.            if (ulReturnCode == NO_ERROR || ulReturnCode == ERROR_MORE_DATA)
  11039.            {
  11040.               printf("Total entries read == %u\n",ulEntriesRead);
  11041.               printf("Total entries available == %u\n",ulEntriesAvail);
  11042.               printf("Server names are \n");
  11043.  
  11044.               while (ulEntriesRead) {
  11045.                  printf("\t%s\n",pBuffer->sv0_name);  /* print out name */
  11046.                  pBuffer++;                           /* advance to next entry */
  11047.                  ulEntriesRead--;                     /* dec entries displayed */
  11048.               } /* endwhile */
  11049.            }
  11050.            else
  11051.            {
  11052.               printf("Net32ServerNameEnum() error  return code = %u.\n",
  11053.                      ulReturnCode);
  11054.               Net32ServerNameDel(achServer,achName);
  11055.               return 1;
  11056.            }
  11057.         } else {
  11058.            printf("malloc() failed!\n");
  11059.            return 1;
  11060.         }
  11061.  
  11062.         ulReturnCode = Net32ServerNameDel(achServer,achName);
  11063.  
  11064.         if (ulReturnCode != NO_ERROR)
  11065.         {
  11066.            printf("Net32ServerNameDel() error  return code = %u.\n",
  11067.                   ulReturnCode);
  11068.            return 1;
  11069.         }
  11070.      }
  11071.      else
  11072.      {
  11073.          printf("Net32ServerNameAdd() error  return code = %u.\n",
  11074.                 ulReturnCode);
  11075.          return 1;
  11076.      }
  11077.  
  11078.      return NO_ERROR;
  11079.   }
  11080.  
  11081.  
  11082. ΓòÉΓòÉΓòÉ 8.2. NetServerNameDel or Net32ServerNameDel ΓòÉΓòÉΓòÉ
  11083.  
  11084. Purpose 
  11085.  
  11086. NetServerNameDel removes a secondary server computername from a server and 
  11087. removes all shares and closes all sessions established to that name. 
  11088.  
  11089. Syntax 
  11090.  
  11091. #include  netcons.h>
  11092. #include  server.h>
  11093.  
  11094.  NetServerNameDel (const UCHAR LSFAR* pszServerName, const UCHAR LSFAR*, 
  11095.            pszDelName) 
  11096.  
  11097.  Net32ServerNameDel (const UCHAR LSFAR* pszServerName, const UCHAR LSFAR*, 
  11098.            pszDelName) 
  11099.  
  11100.  Parameters 
  11101.  
  11102.  pszServerName(const UCHAR LSFAR*)  input 
  11103.            Points to a NULL-terminated string containing the server name to be 
  11104.            deleted. 
  11105.  
  11106.  pszDelName(const UCHAR LSFAR*)  input 
  11107.  
  11108.  Returns 
  11109.  
  11110.  ulrc (APIRET)  returns FOR 32 bit 
  11111.  
  11112.  usrc (USHORT)  returns for 16 bit 
  11113.            Return Code. 
  11114.  
  11115.            NetServerNameDel or Net32ServerNameDel returns one of the following 
  11116.            values 
  11117.  
  11118.            0              NERR_Success 
  11119.  
  11120.            5              ERROR_ACCESS_DENIED 
  11121.  
  11122.            53             ERROR_BAD_NETPATH 
  11123.  
  11124.            54             ERROR_NETWORK_BUSY 
  11125.  
  11126.            56             ERROR_TOO_MANY_CMDS 
  11127.  
  11128.            59             ERROR_UNEXP_NET_ERR 
  11129.  
  11130.            71             ERROR_REQ_NOT_ACCEP 
  11131.  
  11132.            87             ERROR_INVALID_PARAMETER 
  11133.  
  11134.            2102           NERR_NetNotStarted 
  11135.  
  11136.            2114           NERR_ServerNotStarted 
  11137.  
  11138.            2140           NERR_InternalError 
  11139.  
  11140.            2141           NERR_BadTransactConfig 
  11141.  
  11142.            2142           NERR_InvalidAPI 
  11143.  
  11144.            2460           NERR_NoSuchServer 
  11145.  
  11146.            2469           NERR_DelPrimaryName 
  11147.  
  11148.  Remarks 
  11149.  
  11150.  Only secondary server names can be deleted by the API. An attempt to delete 
  11151.  the primary server name will result in NERR_DelPrimaryName being returned. 
  11152.  
  11153.  If a name successfully deleted had sessions to it, then the name may still 
  11154.  show in NetServerNameEnum and may not be re-added until the server has 
  11155.  completed closing all sessions established to that name. 
  11156.  
  11157.  Any shares that were added to the deleted name will also be removed. 
  11158.  
  11159.  This API can be called from OS/2 workstations. Administrative or server 
  11160.  operator authority is required to call this API. 
  11161.  
  11162.  Related Functions 
  11163.  
  11164.      NetServerNameAdd 
  11165.  
  11166.      NetServerNameEnum 
  11167.  
  11168.  Example Code 
  11169.  
  11170.  This example adds a servername called  Server18 , then enumerates the server 
  11171.  names in use and finally removes the  Server18  servername. 
  11172.  
  11173.   #define PURE_32
  11174.   #define INCL_DOS
  11175.   #define INCL_DOSERRORS
  11176.   #include  os2.h>
  11177.   #include  stdio.h>
  11178.   #include  stdlib.h>
  11179.   #include  string.h>
  11180.   #include  netcons.h>
  11181.   #include  server.h>
  11182.   int main(VOID)
  11183.   {
  11184.  
  11185.      struct server_info_0 LSFAR * pBuffer; /* pointer to enum return info */
  11186.      ULONG  ulBufLen=4096;                 /* length in bytes of enum buffer */
  11187.      ULONG  ulLevel=0;                     /* enum return info level */
  11188.      ULONG  ulEntriesRead=0;               /* total entries read from enum */
  11189.      ULONG  ulEntriesAvail=0;              /* total entries available from enum */
  11190.      CHAR   achServer[CNLEN+1];            /* remote server name or '\0' */
  11191.      CHAR   achName[CNLEN+1];              /* server name to add and delete */
  11192.      ULONG  ulReturnCode=0;                /* return code */
  11193.  
  11194.      strcpy(achName,"Server18");         /* initialize servername to use */
  11195.      achServer[0] = '\0';                  /* initialize for local API call */
  11196.  
  11197.      ulReturnCode = Net32ServerNameAdd(achServer,achName);
  11198.  
  11199.      if (ulReturnCode == NO_ERROR)
  11200.      {
  11201.         if ((pBuffer = malloc(ulBufLen)) != NULL)
  11202.         {
  11203.            ulReturnCode = Net32ServerNameEnum(achServer,
  11204.                                               ulLevel,
  11205.                                               (unsigned char *)pBuffer,
  11206.                                               ulBufLen,
  11207.                                                ulEntriesRead,
  11208.                                                ulEntriesAvail);
  11209.  
  11210.  
  11211.            if (ulReturnCode == NO_ERROR || ulReturnCode == ERROR_MORE_DATA)
  11212.            {
  11213.               printf("Total entries read == %u\n",ulEntriesRead);
  11214.               printf("Total entries available == %u\n",ulEntriesAvail);
  11215.               printf("Server names are \n");
  11216.  
  11217.               while (ulEntriesRead) {
  11218.                  printf("\t%s\n",pBuffer->sv0_name);  /* print out name */
  11219.                  pBuffer++;                           /* advance to next entry */
  11220.                  ulEntriesRead--;                     /* dec entries displayed */
  11221.               } /* endwhile */
  11222.            }
  11223.            else
  11224.            {
  11225.               printf("Net32ServerNameEnum() error  return code = %u.\n",
  11226.                      ulReturnCode);
  11227.               Net32ServerNameDel(achServer,achName);
  11228.               return 1;
  11229.            }
  11230.         } else {
  11231.            printf("malloc() failed!\n");
  11232.            return 1;
  11233.         }
  11234.  
  11235.         ulReturnCode = Net32ServerNameDel(achServer,achName);
  11236.  
  11237.         if (ulReturnCode != NO_ERROR)
  11238.         {
  11239.            printf("Net32ServerNameDel() error  return code = %u.\n",
  11240.                   ulReturnCode);
  11241.            return 1;
  11242.         }
  11243.      }
  11244.      else
  11245.      {
  11246.          printf("Net32ServerNameAdd() error  return code = %u.\n",
  11247.                 ulReturnCode);
  11248.          return 1;
  11249.      }
  11250.  
  11251.      return NO_ERROR;
  11252.   }
  11253.  
  11254.  
  11255. ΓòÉΓòÉΓòÉ 8.3. NetServerNameEnum or Net32ServerNameEnum ΓòÉΓòÉΓòÉ
  11256.  
  11257. Purpose 
  11258.  
  11259. NetServerNameEnum enumerates the set of computernames by which a server is 
  11260. known by on the network. 
  11261.  
  11262. Syntax 
  11263.  
  11264. #include  netcons.h>
  11265. #include  server.h>
  11266.  
  11267.  NetServerNameEnum (const UCHAR LSFAR* pszServerName, SHORT sLevel, UCHAR 
  11268.            LSFAR* buf, USHORT usBuflen, USHORT LSFAR* pusEntriesReturned, 
  11269.            USHORT LSFAR* pusEntriesAvail) 
  11270.  
  11271.  Net32ServerNameEnum (const UCHAR pszServerName, ULONG ulLevel, UCHAR* Buf, 
  11272.            ULONG ulBuflen,  ULONG* pulEntriesReturned, ULONG* pulEntriesAvail) 
  11273.  
  11274.  Parameters 
  11275.  
  11276.  pszServerName(const UCHAR LSFAR*)  input 
  11277.            Points to a string containing the network name of the server. 
  11278.  
  11279.  sLevel(SHORT)  input 
  11280.            Specifies the level of detail (MBZ) for the server_info data 
  11281.            structure, as described in Server Level 0. Other levels such as 1, 
  11282.            2, 3 and 20 are not valid for NetServerNameEnum. 
  11283.  
  11284.  buf(UCHAR*) output 
  11285.            Points to the local buffer address of the data structure to be sent 
  11286.            or received. 
  11287.  
  11288.  usBuflen(USHORT) or (ULONG) input 
  11289.            Specifies the amount of local memory allocated to the buf data 
  11290.            structure. 
  11291.  
  11292.  pusEntriesReturned(USHORT LSFAR*) or pulEntriesReturned(ULONG*) or (PULONG) 
  11293.  output 
  11294.            Points to the number of data structures returned. 
  11295.  
  11296.  pusEntriesAvail(USHORT LSFAR*) orpusEntriesAvail (ULONG*) or (PULONG) output 
  11297.            Points to the number of data structures currently available. 
  11298.  
  11299.  ulLevel(ULONG) input 
  11300.            Specifies the level of detail (MBZ) for the server_info data 
  11301.            structure, as described in Server Level 0. Other levels such as 1, 
  11302.            2, 3 and 20 are not valid for NetServerNameEnum. 
  11303.  
  11304.  Returns 
  11305.  
  11306.  ulrc (APIRET)  returns for 32 bit 
  11307.  
  11308.  usrc (USHORT)  returns for 16 bit 
  11309.            Return Code. 
  11310.  
  11311.            NetServerNameEnum or Net32ServerNameEnum returns one of the 
  11312.            following values 
  11313.  
  11314.            0              NERR_Success 
  11315.  
  11316.            5              ERROR_ACCESS_DENIED 
  11317.  
  11318.            124            ERROR_INVALID_LEVEL 
  11319.  
  11320.            234            ERROR_MORE_DATA 
  11321.  
  11322.            2102           NERR_NetNotStarted 
  11323.  
  11324.            2114           NERR_ServerNotStarted 
  11325.  
  11326.            2140           NERR_InternalError 
  11327.  
  11328.            2141           NERR_BadTransactConfig 
  11329.  
  11330.            2142           NERR_InvalidAPI 
  11331.  
  11332.  Remarks 
  11333.  
  11334.  If you call this API with the buffer length parameter equal to zero, the API 
  11335.  returns a value for total entries available. This technique is useful if you 
  11336.  do not know the exact buffer size required. 
  11337.  
  11338.  The NetServerNameEnum API can obtain only level 0 data structures. 
  11339.  
  11340.  This API returns the list of server names being used by a server. This may 
  11341.  include names in the process of being added or deleted, not just active server 
  11342.  names. 
  11343.  
  11344.  The set of server names returned will always list the primary server name 
  11345.  first, and if there are no other server names in use, the primary server name 
  11346.  will be the only name returned in the return buffer. 
  11347.  
  11348.  This API can be called from OS/2 workstations. Administrative or server 
  11349.  operator authority is required to call this API. 
  11350.  
  11351.  Related Functions 
  11352.  
  11353.      NetServerNameAdd 
  11354.  
  11355.      NetServerNameDel 
  11356.  
  11357.  Example Code 
  11358.  
  11359.  This example adds a servername called  Server18 , then enumerates the server 
  11360.  names in use and finally removes the  Server18 " servername. 
  11361.  
  11362.   #define PURE_32
  11363.   #define INCL_DOS
  11364.   #define INCL_DOSERRORS
  11365.   #include  os2.h>
  11366.   #include  stdio.h>
  11367.   #include  stdlib.h>
  11368.   #include  string.h>
  11369.   #include  netcons.h>
  11370.   #include  server.h>
  11371.   int main(VOID)
  11372.   {
  11373.  
  11374.      struct server_info_0 LSFAR * pBuffer; /* pointer to enum return info */
  11375.      ULONG  ulBufLen=4096;                 /* length in bytes of enum buffer */
  11376.      ULONG  ulLevel=0;                     /* enum return info level */
  11377.      ULONG  ulEntriesRead=0;               /* total entries read from enum */
  11378.      ULONG  ulEntriesAvail=0;              /* total entries available from enum */
  11379.      CHAR   achServer[CNLEN+1];            /* remote server name or '\0' */
  11380.      CHAR   achName[CNLEN+1];              /* server name to add and delete */
  11381.      ULONG  ulReturnCode=0;                /* return code */
  11382.  
  11383.      strcpy(achName,"Server18");         /* initialize servername to use */
  11384.      achServer[0] = '\0';                  /* initialize for local API call */
  11385.  
  11386.      ulReturnCode = Net32ServerNameAdd(achServer,achName);
  11387.  
  11388.      if (ulReturnCode == NO_ERROR)
  11389.      {
  11390.         if ((pBuffer = malloc(ulBufLen)) != NULL)
  11391.         {
  11392.            ulReturnCode = Net32ServerNameEnum(achServer,
  11393.                                               ulLevel,
  11394.                                               (unsigned char *)pBuffer,
  11395.                                               ulBufLen,
  11396.                                                ulEntriesRead,
  11397.                                                ulEntriesAvail);
  11398.  
  11399.  
  11400.            if (ulReturnCode == NO_ERROR || ulReturnCode == ERROR_MORE_DATA)
  11401.            {
  11402.               printf("Total entries read == %u\n",ulEntriesRead);
  11403.               printf("Total entries available == %u\n",ulEntriesAvail);
  11404.               printf("Server names are \n");
  11405.  
  11406.               while (ulEntriesRead) {
  11407.                  printf("\t%s\n",pBuffer->sv0_name);  /* print out name */
  11408.                  pBuffer++;                           /* advance to next entry */
  11409.                  ulEntriesRead--;                     /* dec entries displayed */
  11410.               } /* endwhile */
  11411.            }
  11412.            else
  11413.            {
  11414.               printf("Net32ServerNameEnum() error  return code = %u.\n",
  11415.                      ulReturnCode);
  11416.               Net32ServerNameDel(achServer,achName);
  11417.               return 1;
  11418.            }
  11419.         } else {
  11420.            printf("malloc() failed!\n");
  11421.            return 1;
  11422.         }
  11423.  
  11424.         ulReturnCode = Net32ServerNameDel(achServer,achName);
  11425.  
  11426.         if (ulReturnCode != NO_ERROR)
  11427.         {
  11428.            printf("Net32ServerNameDel() error  return code = %u.\n",
  11429.                   ulReturnCode);
  11430.            return 1;
  11431.         }
  11432.      }
  11433.      else
  11434.      {
  11435.          printf("Net32ServerNameAdd() error  return code = %u.\n",
  11436.                 ulReturnCode);
  11437.          return 1;
  11438.      }
  11439.  
  11440.      return NO_ERROR;
  11441.   }
  11442.  
  11443.  
  11444. ΓòÉΓòÉΓòÉ 9. Windows Functions ΓòÉΓòÉΓòÉ
  11445.  
  11446. This chapter contains an alphabetic list of the following Windows functions 
  11447.  
  11448.      WinHAPPfromPID 
  11449.  
  11450.      WinHSWITCHfromHAPP 
  11451.  
  11452.      WinRestartWorkplace 
  11453.  
  11454.      WinWaitForShell() 
  11455.  
  11456.  
  11457. ΓòÉΓòÉΓòÉ 9.1. WinHAPPfromPID ΓòÉΓòÉΓòÉ
  11458.  
  11459. Purpose 
  11460.  
  11461. WinHAPPfromPID returns the PM Application Handle (HAPP) from the process ID. If 
  11462. the proces ID is not a valid PM application, then 0 is returned. 
  11463.  
  11464. Syntax 
  11465.  
  11466. #define INCL_PMAPI
  11467. #include  os2.h>
  11468.  
  11469.  HAPP WinHAPPfromPID (PID pid) 
  11470.  
  11471.  Parameters 
  11472.  
  11473.  pid(PID)  input 
  11474.            Process ID 
  11475.  
  11476.  Returns 
  11477.  
  11478.  happ(HAPP)  returns 
  11479.            Application handle. 
  11480.  
  11481.            NULLHANDLE     If the PID is invalid, or an error occurred. 
  11482.  
  11483.            HAPP           The Application Handle, if PID is valid. 
  11484.  
  11485.  Remarks 
  11486.  
  11487.  WinHAPPfromHSWITCH and WinHSWITCHfromHAPP may be called from non-PM programs. 
  11488.  For some versions of OS/2 it may be necessary to import explicitly these APIs 
  11489.  using the following ordinals 
  11490.  
  11491.  WinHAPPfromPID PMMERGE.5198 
  11492.  
  11493.  WinHSWITCHfromHAPP PMMERGE.5199 
  11494.  
  11495.  Related Functions 
  11496.  
  11497.      WinHSWITCHfromHAPP 
  11498.  
  11499.      WinQuerySwitchEntry 
  11500.  
  11501.      WinQuerySwitchHandle 
  11502.  
  11503.      WinQuerySwitchList 
  11504.  
  11505.  Example Code 
  11506.  
  11507.   int main (int argc, char *argv[], char *envp[])
  11508.   {
  11509.  
  11510.      APIRET rc;
  11511.      HAPP happ;
  11512.      HSWITCH hswitch;
  11513.      SWCNTRL swcntrl;
  11514.      PID pid;
  11515.  
  11516.      if (argc==1) {
  11517.        printf("QSWLIST pid\n");
  11518.        return 0;
  11519.       }   /* endif */
  11520.  
  11521.      pid=strtoul(argv[1],NULL,0);
  11522.  
  11523.      happ=WinHAPPfromPID(pid);            /* get HAPP from PID */
  11524.  
  11525.      hswitch=WinHSWITCHfromHAPP(happ);     /* get HSWITCH from HAPP */
  11526.  
  11527.      rc=WinQuerySwitchEntry(hswitch,  swcntrl); /* interpret HSWITCH */
  11528.      if (rc) {
  11529.        printf("WinQuerySwitchEntry returned %u\n",rc);
  11530.        return rc;
  11531.      } /* endif */
  11532.  
  11533.      printf("Pid  %04x, Happ  %08x, Hswitch  %08x\n", pid, happ, hswitch);
  11534.      printf("swcntrl.hwnd      \t%08x,   swcntrl.hwndIcon     \t%08x\n",
  11535.              swcntrl.hwnd, swcntrl.hwndIcon);
  11536.      printf("swcntrl.hprog     \t%08x,   swcntrl.idProcess    \t%08x\n",
  11537.              swcntrl.hprog, swcntrl.idProcess);
  11538.      printf("swcntrl.idSession \t%08x,   swcntrl.uchVisbility \t%08x\n",
  11539.              swcntrl.idSession, swcntrl.uchVisibility);
  11540.      printf("swcntrl.fbJump    \t%08x,   swcntrl.bProgType    \t%08x\n",
  11541.              swcntrl.fbJump, swcntrl.bProgType);
  11542.      printf("swcntrl.szSwtitle %s\n",  sz.Swtitle);
  11543.  
  11544.      return 0;
  11545.   }
  11546.  
  11547.  
  11548. ΓòÉΓòÉΓòÉ 9.2. WinHSWITCHfromHAPP ΓòÉΓòÉΓòÉ
  11549.  
  11550. Purpose 
  11551.  
  11552. WinHSWITCHfromHAPP returns the handle of the switch list entry from the 
  11553. application handle. If the application handle is invalid or IF no switch list 
  11554. eNtry exists, then 0 is returned. 
  11555.  
  11556. Syntax 
  11557.  
  11558. #define INCL_PMAPI
  11559. #include  os2.h>
  11560.  
  11561.  HSWITCH WinHSWITCHfromHAPP (HAPP happ) 
  11562.  
  11563.  Parameters 
  11564.  
  11565.  happ(HAPP)  input 
  11566.            Application handle. 
  11567.  
  11568.  Returns 
  11569.  
  11570.  hswitch (HSWITCH)  returns 
  11571.            Switch list handle. 
  11572.  
  11573.            NULLHANDLE     If the HAPP is invalid, the Switch List Entry is not 
  11574.                           defined for this HAPP, or an error occurred. 
  11575.  
  11576.            HSWITCH        The Handle of the Switch List Entry, if HAPP is valid 
  11577.                           and a Switch List Entry exists. 
  11578.  
  11579.  Remarks 
  11580.  
  11581.  WinHAPPfromHSWITCH and WinHSWITCHfromHAPP may be called from non-PM programs. 
  11582.  For some versions of OS/2 it may be necessary to import explicitly these APIs 
  11583.  using the following ordinals 
  11584.  
  11585.  WinHAPPfromPID PMMERGE.5198 
  11586.  
  11587.  WinHSWITCHfromHAPP PMMERGE.5199 
  11588.  
  11589.  Related Functions 
  11590.  
  11591.      WinHAPPfromPID 
  11592.  
  11593.      WinQuerySwitchEntry 
  11594.  
  11595.      WinQuerySwitchHandle 
  11596.  
  11597.      WinQuerySwitchList 
  11598.  
  11599.  Example Code 
  11600.  
  11601.   int main (int argc, char *argv[], char *envp[])
  11602.   {
  11603.  
  11604.      APIRET rc;
  11605.      HAPP happ;
  11606.      HSWITCH hswitch;
  11607.      SWCNTRL swcntrl;
  11608.      PID pid;
  11609.  
  11610.      if (argc==1) {
  11611.        printf("QSWLIST pid\n");
  11612.        return 0;    }                     /* endif */
  11613.  
  11614.      pid=strtoul(argv[1],NULL,0);
  11615.  
  11616.      happ=WinHAPPfromPID(pid);            /* get HAPP from PID */
  11617.  
  11618.      hswitch=WinHSWITCHfromHAPP(happ);     /* get HSWITCH from HAPP */
  11619.  
  11620.      rc=WinQuerySwitchEntry(hswitch,  swcntrl); /* interpret HSWITCH */
  11621.      if (rc) {
  11622.        printf("WinQuerySwitchEntry returned %u\n",rc);
  11623.        return rc;
  11624.      } /* endif */
  11625.  
  11626.      printf("Pid  %04x, Happ  %08x, Hswitch  %08x\n", pid, happ, hswitch);
  11627.      printf("swcntrl.hwnd      \t%08x,   swcntrl.hwndIcon     \t%08x\n",
  11628.              swcntrl.hwnd, swcntrl.hwndIcon);
  11629.      printf("swcntrl.hprog     \t%08x,   swcntrl.idProcess    \t%08x\n",
  11630.              swcntrl.hprog, swcntrl.idProcess);
  11631.      printf("swcntrl.idSession \t%08x,   swcntrl.uchVisbility \t%08x\n",
  11632.              swcntrl.idSession, swcntrl.uchVisibility);
  11633.      printf("swcntrl.fbJump    \t%08x,   swcntrl.bProgType    \t%08x\n",
  11634.              swcntrl.fbJump, swcntrl.bProgType);
  11635.      printf("swcntrl.szSwtitle %s\n",  sz.Swtitle);
  11636.  
  11637.      return 0;
  11638.   }
  11639.  
  11640.  
  11641. ΓòÉΓòÉΓòÉ 9.3. WinRestartWorkplace ΓòÉΓòÉΓòÉ
  11642.  
  11643. Purpose 
  11644.  
  11645. This function causes the Workplace(TM) process to terminate and re-initialize. 
  11646.  
  11647. This function is applicable to OS/2 Warp 4, or higher, and WorkSpace On-Demand 
  11648. client operating systems. 
  11649.  
  11650. Syntax 
  11651.  
  11652. #include  os2.h>
  11653.  
  11654. BOOL32 APIENTRY WinRestartWorkplace(VOID);
  11655.  
  11656. Parameters 
  11657.  
  11658. None. 
  11659.  
  11660. Returns 
  11661.  
  11662.  rc (BOOL32)  returns 
  11663.            Always returns FALSE. 
  11664.  
  11665.  Remarks 
  11666.  
  11667.  This function will cause the Workplace process to terminate and re-initialize. 
  11668.  This call is useful in debugging workplace objects or for install programs 
  11669.  that reregister system classes. 
  11670.  
  11671.  Example Code 
  11672.  
  11673.  This example terminates and re-initializes the Workplace process. 
  11674.  
  11675.  
  11676.   #include  os2.h>
  11677.   BOOL32 EXPENTRY WinRestartWorkplace(VOID);
  11678.  
  11679.   /* Terminate and re-initialize the Workplace process */
  11680.   WinRestartWorkplace();
  11681.  
  11682.  
  11683. ΓòÉΓòÉΓòÉ 9.4. WinWaitForShell() ΓòÉΓòÉΓòÉ
  11684.  
  11685. Purpose 
  11686.  
  11687. WinWaitForShell() determines if various events in the Workplace Shell(R) have 
  11688. taken place. 
  11689.  
  11690. Syntax 
  11691.  
  11692. #define
  11693. #include  os2.h>
  11694.  
  11695.  BOOL EXPENTRY WinWaitForShell() (ULONG ulEvent) 
  11696.  
  11697.  Parameters 
  11698.  
  11699.  ulEvent (ULONG)  input 
  11700.            ulEvent has the following flags which indicate which event is to be 
  11701.            queried. One, and only one, of these flags must be turned on. 
  11702.  
  11703.            WWFS_DESKTOPCREATED Desktop has been created. 
  11704.  
  11705.            WWFS_DESKTOPOPENED A view of the Desktop has been opened. 
  11706.  
  11707.            WWFS_DESKTOPPOPULATED The desktop has been populated.. 
  11708.  
  11709.            WWFS_QUERY     Query if the event has taken place. If this flag is 
  11710.                           not turned on then this call will block until the 
  11711.                           event has taken place. 
  11712.  
  11713.  Returns 
  11714.  
  11715.  rc (BOOL)  returns 
  11716.            Success indicator. 
  11717.  
  11718.            True           Event has taken place 
  11719.  
  11720.            False          Event has not taken place 
  11721.  
  11722.            Possible returns from WinGetLastError 
  11723.  
  11724.            PMERR_INVALID_PARAMETER (0x1208) One of the defined WWFS_DESKTOP* 
  11725.                           flags was not passed in ulEvent. 
  11726.  
  11727.  Remarks 
  11728.  
  11729.  This function can be used to either determine if a Workpalce Shell event has 
  11730.  taken place or wait until that event has taken place. Set ulEvent to one of 
  11731.  the WWFS_DESKTOP* #defines above. 
  11732.  
  11733.  To block until the event has occurred, do not turn on the WWFS_QUERY flag. 
  11734.  
  11735.   Simply to query if the event has occurred and not to wait for it to occur, 
  11736.  turn on the WWFS_QUERY flag. 
  11737.  
  11738.  Example Code 
  11739.  
  11740.  This example checks (non-blocking) to see if the Workplalce Shell Desktop to 
  11741.  be populated has been populated or not. 
  11742.  
  11743.   #define
  11744.   #include  os2.h>
  11745.  
  11746.   BOOL fOccurred;
  11747.  
  11748.   fOccurred + WinWaitForShell(WWFS_DESKTOPPOPULATED | WWFS_QUERY);
  11749.   if (fOccurred)
  11750.      {
  11751.       /* The Desktop has been populated */
  11752.      }
  11753.   else
  11754.      {
  11755.       /* The Desktop has not been populated */
  11756.  
  11757.  
  11758. ΓòÉΓòÉΓòÉ 10. APIs Supporting High Memory Objects ΓòÉΓòÉΓòÉ
  11759.  
  11760.  
  11761. ΓòÉΓòÉΓòÉ 10.1. APIs in Warp Server 4 Advanced/SMP ΓòÉΓòÉΓòÉ
  11762.  
  11763.      DosFindFirst 
  11764.  
  11765.      DosFindNext 
  11766.  
  11767.      DosFreeMem 
  11768.  
  11769.      DosGetNamedSharedMem 
  11770.  
  11771.      DosGiveSharedMem 
  11772.  
  11773.      DosLoadModule 
  11774.  
  11775.      DosOpen 
  11776.  
  11777.      DosQueryMem 
  11778.  
  11779.      DosQueryModuleName 
  11780.  
  11781.      DosQueryPageUsage 
  11782.  
  11783.      DosQueryPathInfo 
  11784.  
  11785.      DosRead 
  11786.  
  11787.      DosSetMem 
  11788.  
  11789.      DosSetPathInfo 
  11790.  
  11791.      DosSubAllocMem 
  11792.  
  11793.      DosSubFreeMem 
  11794.  
  11795.      DosSubSetMem 
  11796.  
  11797.      DosSubUnsetMem 
  11798.  
  11799.      DosWrite 
  11800.  
  11801.  
  11802. ΓòÉΓòÉΓòÉ 10.2. Additional APIs Supported in Warp Server for e-business ΓòÉΓòÉΓòÉ
  11803.  
  11804.      DosAcknowledgeSignalException 
  11805.  
  11806.      DosAddMuxWaitSem 
  11807.  
  11808.      DosCloseEventSem 
  11809.  
  11810.      DosCloseMutexSem 
  11811.  
  11812.      DosCloseMuxWaitSem 
  11813.  
  11814.      DosCopy 
  11815.  
  11816.      DosCreateDir 
  11817.  
  11818.      DosCreateEventSem 
  11819.  
  11820.      DosCreateMutexSem 
  11821.  
  11822.      DosCreateMuxWaitSem 
  11823.  
  11824.      DosCreateNPipe 
  11825.  
  11826.      DosCreateQueue 
  11827.  
  11828.      DosCreateThread2 
  11829.  
  11830.      DosDelete 
  11831.  
  11832.      DosDeleteDir 
  11833.  
  11834.      DosDeleteMuxWaitSem 
  11835.  
  11836.      DosEnterMustComplete 
  11837.  
  11838.      DosExecPgm 
  11839.  
  11840.      DosExitMustComplete 
  11841.  
  11842.      DosMove 
  11843.  
  11844.      DosOpenEventSem 
  11845.  
  11846.      DosOpenMutexSem 
  11847.  
  11848.      DosOpenMutexWaitSem 
  11849.  
  11850.      DosPhysicalDisk 
  11851.  
  11852.      DosPostEventSem 
  11853.  
  11854.      DosQueryCurrentDir 
  11855.  
  11856.      DosQueryCurrentDisk 
  11857.  
  11858.      DosQueryEventSem 
  11859.  
  11860.      DosQueryFSAttach 
  11861.  
  11862.      DosQueryFSInfo 
  11863.  
  11864.      DosQueryFileInfo 
  11865.  
  11866.      DosQueryModuleHandle 
  11867.  
  11868.      DosQueryMutexSem 
  11869.  
  11870.      DosQueryMuxWaitSem 
  11871.  
  11872.      DosQueryNPHState 
  11873.  
  11874.      DosRaiseException 
  11875.  
  11876.      DosReadQueue 
  11877.  
  11878.      DosReleaseMutexSem 
  11879.  
  11880.      DosRequestMutexSem 
  11881.  
  11882.      DosResetEventSem 
  11883.  
  11884.      DosScanEnv 
  11885.  
  11886.      DosSearchPath 
  11887.  
  11888.      DosSendSignalException 
  11889.  
  11890.      DosSetCurrentDir 
  11891.  
  11892.      DosSetExceptionHandler 
  11893.  
  11894.      DosSetFileInfo 
  11895.  
  11896.      DosSetFileLocks 
  11897.  
  11898.      DosSetRelMaxFH 
  11899.  
  11900.      DosSetSignalExceptionFocus 
  11901.  
  11902.      DosUnsetExceptionHandler 
  11903.  
  11904.      DosUnwindException 
  11905.  
  11906.      DosWaitEventSem 
  11907.  
  11908.      DosWaitMuxWaitSem 
  11909.  
  11910.  
  11911. ΓòÉΓòÉΓòÉ 11. Notices ΓòÉΓòÉΓòÉ
  11912.  
  11913. This information was developed for products and services offered in the U.S.A. 
  11914. IBM may not offer the products, services, or features discussed in this 
  11915. document in other countries. Consult your local IBM representative for 
  11916. information on the products and services currently available in your area. Any 
  11917. reference to an IBM product, program, or service is not intended to state or 
  11918. imply that only that IBM product, program, or service may be used. Any 
  11919. functionally equivalent product, program, or service that does not infringe any 
  11920. IBM intellectual property right may be used instead.  However, it is the user's 
  11921. responsibility to evaluate and verify the operation of any non-IBM product, 
  11922. program, or service. 
  11923.  
  11924. IBM may have patents or pending patent applications covering subject matter in 
  11925. this document. The furnishing of this document does not give you any license to 
  11926. these patents. You can send license inquiries, in writing, to 
  11927.  
  11928. IBM Director of Licensing
  11929. IBM Corporation
  11930. North Castle Drive
  11931. Armonk, NY  10504-1785
  11932. U.S.A.
  11933.  
  11934. For license inquiries regarding double-byte (DBCS) information, contact the IBM 
  11935. Intellectual Property Department in your country or send inquiries, in writing, 
  11936. to 
  11937.  
  11938. IBM World Trade Asia Corporation Licensing
  11939. 2-31 Roppongi 3-chome, Minato-ku
  11940. Tokyo 106, Japan
  11941.  
  11942. The following paragraph does not apply to the United Kingdom or any other 
  11943. country where such provisions are inconsistent with local law  INTERNATIONAL 
  11944. BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION  AS IS  WITHOUT 
  11945. WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 
  11946. THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A 
  11947. PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied 
  11948. warranties in certain transactions, therefore, this statement may not apply to 
  11949. you. 
  11950.  
  11951. This information could include technical inaccuracies or typographical errors. 
  11952. Changes are periodically made to the information herein; these changes will be 
  11953. incorporated in new editions of the information.  IBM may make improvements 
  11954. and/or changes in the product(s) and/or the program(s) described in this 
  11955. information at any time without notice. 
  11956.  
  11957. Any references in this information to non-IBM Web sites are provided for 
  11958. convenience  only and do not in any manner serve as an endorsement of those Web 
  11959. sites.  The  materials at those Web sites are not part of the materials for 
  11960. this IBM product and use  of those Web sites is at your own risk. 
  11961.  
  11962. IBM may use or distribute any of the information you supply in any way it 
  11963. believes appropriate without incurring any obligation to you. 
  11964.  
  11965. Licensees of this program who wish to have information about it for the purpose 
  11966. of enabling  (i) the exchange of information between independently created 
  11967. programs and other programs (including this one) and (ii) the mutual use of the 
  11968. information which has been exchanged, should contact 
  11969.  
  11970. IBM Corporation
  11971. Department LZKS
  11972. 11400 Burnet Road
  11973. Austin, TX 78758
  11974. U.S.A.
  11975.  
  11976. Such information may be available, subject to appropriate terms and conditions, 
  11977. including in some cases, payment of a fee. 
  11978.  
  11979. The licensed program described in this document and all licensed material 
  11980. available for it are provided by IBM under terms of the IBM Customer Agreement, 
  11981. IBM International Program License Agreement, or any equivalent agreement 
  11982. between us. 
  11983.  
  11984. Any performance data contained herein was determined in a controlled 
  11985. environment.  Therefore, the results obtained in other operating environments 
  11986. may vary significantly.  Some measurements may have been made on 
  11987. development-level systems and there is no guarantee that these measurements 
  11988. will be the same on generally available systems. Furthermore, some measurement 
  11989. may have been estimated through extrapolation.  Actual results may vary. Users 
  11990. of this document should verify the applicable data for their specific 
  11991. environment. 
  11992.  
  11993. Information concerning non-IBM products was obtained from the suppliers of 
  11994. those products, their published announcements or other publicly available 
  11995. sources.  IBM has not tested those products and cannot confirm the accuracy of 
  11996. performance, compatibility or any other claims related to non-IBM products. 
  11997. Questions on the capabilities of non-IBM products should be addressed to the 
  11998. suppliers of those products. 
  11999.  
  12000. All statements regarding IBM's future direction or intent are subject to change 
  12001. or withdrawal without notice, and represent goals and objectives only. 
  12002.  
  12003. All IBM prices shown are IBM's suggested retail prices, are current and are 
  12004. subject to change without notice.  Dealer prices may vary. 
  12005.  
  12006. COPYRIGHT LICENSE 
  12007.  
  12008. This information contains sample application programs in source language, which 
  12009. illustrates programming techniques on various operating platforms.  You may 
  12010. copy, modify, and distribute these sample programs in any form without payment 
  12011. to IBM, for the purposes of developing, using, marketing or distributing 
  12012. application programs conforming to the application programming interface for 
  12013. the operating platform for which the sample programs are written. 
  12014.  
  12015. These examples have not been thoroughly tested under all conditions.  IBM, 
  12016. therefore, cannot guarantee or imply reliability, serviceability, or function 
  12017. of these programs. You may copy, modify, and distribute these sample programs 
  12018. in any form without payment to IBM for the purposes of developing, using, 
  12019. marketing, or distributing application programs conforming to IBM's application 
  12020. programming interfaces. 
  12021.  
  12022. Each copy or any portion of these sample programs or any derivative work, must 
  12023. include a copyright notice as follows 
  12024.  
  12025. (C) (your company name) (year).  Portions of this code are derived from IBM 
  12026. Corp.  Sample Programs.  (C) Copyright IBM Corp.  1999. All rights reserved. 
  12027.  
  12028. If you are viewing this information softcopy, the photographs and color 
  12029. illustrations may not appear. 
  12030.  
  12031.  
  12032. ΓòÉΓòÉΓòÉ 11.1. Trademarks ΓòÉΓòÉΓòÉ
  12033.  
  12034. The following terms are trademarks of International Business Machines 
  12035. Corporation in the United States, or other countries, or both 
  12036.  
  12037. IBM
  12038. OS/2
  12039. Presentation Manager
  12040. VisualAge
  12041. Workplace
  12042. Workplace Shell
  12043.  
  12044. Pentium is a registered trademark of Intel Corporation in the United States and
  12045. other countries.
  12046. Windows is a registered trademark of Microsoft Corporation.
  12047.  
  12048. Other company, product, and service names may be trademarks or service marks of 
  12049. others.