home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dosqps.zip / dosqproc.INF (.txt) next >
OS/2 Help File  |  1993-07-12  |  17KB  |  521 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Warnings ΓòÉΓòÉΓòÉ
  3.  
  4. This document includes a written description of the DosQProcStatus API for IBM 
  5. OS/2 Version 2.0. 
  6.  
  7. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS DOCUMENT "AS IS" 
  8. WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
  9. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 
  10. PARTICULAR PURPOSE. 
  11.  
  12. IN NO EVENT WILL IBM BE LIABLE FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO 
  13. ANY LOST PROFITS, LOST SAVINGS OR ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN 
  14. IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY YOU BASED ON 
  15. A THIRD PARTY CLAIM. 
  16.  
  17. Some or all of the interfaces described in this document are unpublished. IBM 
  18. reserves the right to change or delete them in future versions of OS/2 at IBM's 
  19. sole discretion, without notice to you.  IBM does not guarantee that 
  20. compatibility of your applications will be maintained with future versions of 
  21. OS/2. 
  22.  
  23. This document could include technical inaccuracies or typographical errors.  It 
  24. is possible that this document may contain reference to, or information about, 
  25. IBM products, programming or services that are not announced in your country. 
  26. Such references or information must not be construed to mean that IBM intends 
  27. to announce such IBM products, programming or services in your country. 
  28.  
  29. IBM may have patents or pending patent applications covering subject matter in 
  30. this document.  The furnishing of this document does not give you any license 
  31. to these patents.  You can send license inquiries, in writing, to the IBM 
  32. Director of Commercial Relations, IBM Corporation, Armonk NY 10504. 
  33.  
  34. Copyright International Business Machines Corporation 1992.  All rights 
  35. reserved. 
  36.  
  37. Note to US Government Users - Documentation related to restricted rights - Use, 
  38. duplication or disclosure is subject to restrictions set forth in GSA ADP 
  39. Schedule Contract with IBM Corp. 
  40.  
  41.  
  42. ΓòÉΓòÉΓòÉ 2. DosQProcStatus API Purpose ΓòÉΓòÉΓòÉ
  43.  
  44. The DosQProcStatus API is a 16 bit API that returns information that summarizes 
  45. the system resources that are in use of an OS/2 2.0 system. DosQProcStatus 
  46. reports on the following classes of OS/2 2.0 system resources: 
  47.  
  48. o Processes and Threads 
  49.  
  50. o Dynamic Link Library Modules 
  51.  
  52. o 16 bit System Semaphores 
  53.  
  54. o Named Shared Memory Segments 
  55.  
  56.  
  57. ΓòÉΓòÉΓòÉ 3. API Calling Sequence ΓòÉΓòÉΓòÉ
  58.  
  59. The following 16 bit C language function prototype can be used to call the 
  60. DosQProcStatus API: 
  61.  
  62. EXTERN UNSIGNED FAR PASCAL DosQProcStatus(ULONG far *buffer, USHORT 
  63. buffer_size) 
  64.  
  65. Parameter                                         Definition 
  66.  
  67. buffer                                            A pointer to a buffer that 
  68.                                                   will be filled with system 
  69.                                                   resource summary information 
  70.                                                   records 
  71.  
  72. buffer_size                                       The size of the buffer in 
  73.                                                   bytes (the maximum value of 
  74.                                                   64KB is typically the safest 
  75.                                                   sized buffer to use since it 
  76.                                                   is impossible to predict how 
  77.                                                   much information a 
  78.                                                   DosQProcStatus call will 
  79.                                                   return) 
  80.  
  81. Return Value                                      Definition 
  82.  
  83. 0                                                 Indicates correct operation, 
  84.                                                   buffer is now filled with 
  85.                                                   system resource summary 
  86.                                                   information records 
  87.  
  88. non-zero                                          Error returns 
  89.  
  90. Pointers 
  91.  
  92. The OS/2 Process Status Utility (PSTAT) uses a conversion formula to convert 
  93. the pointers that are returned by DosQProcStatus. 
  94.  
  95. #define CONVERT(fp) (*((unsigned far*) &(fp) + 1) = QSsel) 
  96.  
  97. Parameter                                         Definition 
  98.  
  99. fp                                                A pointer that points to the 
  100.                                                   head of a record structure. 
  101.  
  102. QSel                                              The 16 bit selector for the 
  103.                                                   segment that contains the 
  104.                                                   DosQProcStatus buffer. 
  105.  
  106.  
  107. ΓòÉΓòÉΓòÉ 4. Linker Considerations ΓòÉΓòÉΓòÉ
  108.  
  109. In order to successfully resolve DosQProcStatus function calls in your program, 
  110. the following lines must be added to the Linker Definition (DEF) file: 
  111.  
  112.  
  113. IMPORTS
  114. DOSQPROCSTATUS=DOSCALL1.154
  115.  
  116.  
  117. ΓòÉΓòÉΓòÉ 4.1. Overview ΓòÉΓòÉΓòÉ
  118.  
  119. DosQProcStatus returns a buffer that is filled with a series of sections of 
  120. resource information: 
  121.  
  122.  1. A section that contains an array of pointers to the other sections in the 
  123.     buffer. 
  124.  
  125.  2. A small global data section that contains system-wide information.  In OS/2 
  126.     2.0 the only value of interest in this section is the total number of 
  127.     threads in the system at the time the DosQProcStatus call was made. 
  128.  
  129.  3. A section consisting of Process and Thread records.  There is one Process 
  130.     record for each process in the system.  Each Process record is immediately 
  131.     followed by a set of Thread records (one Thread record for each thread 
  132.     within the process).  Process records contain arrays of resource 
  133.     identifiers (16 bit semaphore indices, dynamic link library handles and 
  134.     shared memory segment handles) that identify the resources that the process 
  135.     currently has in use.  The handles and indices can be used to indirectly 
  136.     point to 16 bit semaphore records, dynamic link library records and shared 
  137.     memory segment records that reside in the subsequent sections of the 
  138.     buffer. 
  139.  
  140.  4. A section consisting of 16 Bit System Semaphore records.  This section is 
  141.     headed by a small record that contains some summary information concerning 
  142.     16 bit system semaphores.  The summary record is followed by a series of 16 
  143.     Bit System Semaphore records.  Each record characterizes a separate 16 bit 
  144.     system semaphore.  Among other information, each record contains the name 
  145.     of the 16 bit system semaphore, how many processes have opened it, and what 
  146.     thread (if any) currently owns it. 
  147.  
  148.  5. A section consisting of Executable Module records.  Program (.EXE) files, 
  149.     dynamic link library (.DLL) modules and device driver (.SYS) modules are 
  150.     all examples of executable modules.  Each record characterizes a separate 
  151.     executable module.  Each record includes the full pathname of the module, 
  152.     the module's handle and an array of handles of the DLL modules that are 
  153.     directly referenced by the module.  The full pathname of a process is 
  154.     obtained from the Executable Module record of its program file module 
  155.     (which is pointed to by the .EXE module handle value contained in its 
  156.     Process record). 
  157.  
  158.  6. A section consisting of Shared Memory Segment records.  Each record 
  159.     includes the handle of the segment, the 16 bit selector associated with the 
  160.     segment, the number of processes using the segment and the name of the 
  161.     segment. 
  162.  
  163.  
  164. ΓòÉΓòÉΓòÉ 4.2. Pointer Record Section ΓòÉΓòÉΓòÉ
  165.  
  166. The following pointer record structure is the first section in the buffer. It 
  167. contains pointers to the heads of the system resource information sections. 
  168.  
  169.  
  170. typedef struct qsPtrRec_s {
  171.     qsGrec_t     *pGlobalRec;   /* ptr to the global data section */
  172.     qsPrec_t     *pProcRec;    /* ptr to process record section  */
  173.     qsS16Headrec_t  *p16SemRec;   /* ptr to 16 bit sem section    */
  174.     qsMrec_t     *pShrMemRec;   /* ptr to shared mem section    */
  175.     qsLrec_t     *pLibRec;    /*ptr to exe module record section*/
  176. } qsPtrRec_t;
  177.  
  178.  
  179. ΓòÉΓòÉΓòÉ 4.3. Global Data Section ΓòÉΓòÉΓòÉ
  180.  
  181. The following C language structure defines the information contained within the 
  182. global data section that describes global system information. 
  183.  
  184.  
  185. typedef struct qsGrec_s {
  186.     ULONG     cThrds;   /* number of threads in use */
  187.     ULONG     Reserved;
  188.     ULONG     Reserved;
  189. }qsGrec_t;
  190.  
  191.  
  192. ΓòÉΓòÉΓòÉ 4.4. Process and Thread Data Section ΓòÉΓòÉΓòÉ
  193.  
  194. The following C language declarations define the information contained within 
  195. the system resource summary information record that describes an OS/2 process. 
  196. Each process record is immediately followed by one or more thread records for 
  197. the given process.  The pointer qsTrec_t points to the first thread record 
  198. structure for the process. 
  199.  
  200.  
  201. typedef struct qsPrec_s {
  202.     ULONG     RecType;     /* type of record being processed */
  203.                    /* process rectype = 1       */
  204.     qsTrec_t  FAR  *pThrdRec;   /* ptr to 1st thread rec for this prc*/
  205.     USHORT     pid;       /* process ID */
  206.     USHORT     ppid;      /* parent process ID */
  207.     ULONG     type;      /* process type */
  208.     ULONG     stat;      /* process status */
  209.     ULONG     sgid;      /* process screen group */
  210.     USHORT     hMte;      /* program module handle for process */
  211.     USHORT     cTCB;      /* # of TCBs in use in process */
  212.     ULONG     Reserved
  213.     void    FAR Reserved
  214.     USHORT     c16Sem;     /*# of 16 bit system sems in use by proc*/
  215.     USHORT     cLib;      /* number of runtime linked libraries */
  216.     USHORT     cShrMem;     /* number of shared memory handles */
  217.     USHORT     Reserved
  218.     USHORT  FAR  *p16SemRec;   /*ptr to head of 16 bit sem inf for proc*/
  219.     USHORT  FAR  *pLibRec;    /*ptr to list of runtime lib in use by  */
  220.                    /*process*/
  221.     USHORT  FAR  *pShrMemRec;   /*ptr to list of shared mem handles in  */
  222.                    /*use by process*/
  223.     USHORT  FAR  Reserved
  224. } qsPrec_t;
  225.  
  226. Process Record structure  Holds all per process information. 
  227.  
  228.  ___________________________
  229.  | RecType  (=0x00000001)  |
  230.  |-------------------------|
  231.  | pThrdRec                |----|
  232.  |-------------------------|    |
  233.  | pid                     |    |
  234.  |-------------------------|    |
  235.  | ppid                    |    |
  236.  |-------------------------|    |
  237.  | type                    |    |
  238.  |-------------------------|    |
  239.  | stat                    |    |
  240.  |-------------------------|    |
  241.  | sgid                    |    |
  242.  |-------------------------|    |
  243.  | hMte                    |    |
  244.  |-------------------------|    |
  245.  | cTCB                    |    |
  246.  |-------------------------|    |
  247.  | c16Sem                  |    |
  248.  |-------------------------|    |
  249.  | cLib                    |    |
  250.  |-------------------------|    |
  251.  | cShrMem                 |    |
  252.  |-------------------------|    |
  253.  | p16SemRec               |----|----|
  254.  |-------------------------|    |    |
  255.  | pLibRec                 |----|----|---|
  256.  |-------------------------|    |    |   |
  257.  | pShrMemRec              |----|----|---|----|
  258.  |-------------------------|    |    |   |    |
  259.  | 16SemIndx[0]            |<---|----|   |    |
  260.  |    .                    |    |        |    |
  261.  |    .                    |    |        |    |
  262.  |    .                    |    |        |    |
  263.  | 16SemIndx[c16Sem-1]     |    |        |    |
  264.  |-------------------------|    |        |    |
  265.  | hmte[0] (or "name str") |<---|--------|    |
  266.  |    .                    |    |             |
  267.  |    .                    |    |             |
  268.  |    .                    |    |             |
  269.  | hmte[cLib-1]            |    |             |
  270.  |-------------------------|    |             |
  271.  | hshmem[0]               |<---|-------------|
  272.  |    .                    |    |
  273.  |    .                    |    |
  274.  |    .                    |    |
  275.  | hshmem[cShrMem-1]       |    |
  276.  |-------------------------|    |
  277.   * refer to thread rec <-------|
  278.     structure
  279.  
  280. The pLibRec value points to an array of mte handles that indicate the DLL 
  281. modules that are directly referred to by the process (.EXE) program file 
  282. module.  The cLib value indicates how many dynamic link library module handles 
  283. are in the array. 
  284.  
  285. The pShrMemRec value points to an array of shared memory handles that indicate 
  286. the shared memory segments that are being used by the process.  The cShrMem 
  287. value indicates how many shared memory segment handles are in the array. 
  288.  
  289. The p16SemRec value points to an array of 16 bit system semaphore indices that 
  290. indicate the 16 bit system semaphores that are being used by the process.  The 
  291. c16Sem value indicates how many 16 bit system semaphore indices are in the 
  292. array. 
  293.  
  294. The status flag gives an indication of the current status of a process. The 
  295. following list defines the possible values for the status flag: 
  296.  
  297.    0x01 - Doing ExitList Processing
  298.    0x02 - Exiting thread 1
  299.    0x04 - The whole process is exiting
  300.    0x10 - Parent cares about termination
  301.    0x20 - Parent did an exec-and-wait
  302.    0x40 - Process is dying
  303.    0x80 - Process in embryonic state
  304.  
  305. The following C language declarations define the information contained within 
  306. the system resource summary information record that describes an OS/2 thread: 
  307.  
  308.  
  309. /* Thread Record structure
  310.  *    Holds all per thread information.
  311.  */
  312. typedef struct qsTrec_s {
  313.     ULONG     RecType;     /* Record Type */
  314.                    /* Thread rectype = 100 */
  315.     USHORT     tid;       /* thread ID */
  316.     USHORT     slot;      /* "unique" thread slot number */
  317.     ULONG     sleepid;     /* sleep id thread is sleeping on */
  318.     ULONG     priority;    /* thread priority */
  319.     ULONG     systime;     /* thread system time */
  320.     ULONG     usertime;    /* thread user time */
  321.     UCHAR     state;      /* thread state */
  322.     PADCHAR
  323.     PADSHORT
  324. } qsTrec_t;
  325.  
  326. Thread Record Structure 
  327.  
  328. __________________________
  329. | RecType  (=0x00000100)  |----|
  330. |-------------------------|    |
  331. | tid                     |    |
  332. |-------------------------|    |
  333. | slot                    |    |
  334. |-------------------------|    |
  335. | sleepid                 |    |
  336. |-------------------------|    |
  337. | priority                |    |
  338. |-------------------------|    |
  339. | systime                 |    |
  340. |-------------------------|    |
  341. | usertime                |    |
  342. |-------------------------|    |
  343. | state                   |    |
  344. |-------------------------|    |
  345.                       <--------|
  346.  
  347. The thread slot number is an internal OS/2 thread identifier.  OS/2 must 
  348. uniquely identify all threads within the system. 
  349.  
  350. The state value gives an indication of the current state of a thread. The 
  351. following list defines some typical thread state values: 
  352.  
  353.  
  354.    1 - Ready to run
  355.    2 - Blocked
  356.    5 - Running
  357.  
  358. It is outside the scope of this document to further describe and explain the 
  359. various thread state values. 
  360.  
  361.  
  362. ΓòÉΓòÉΓòÉ 4.5. 16 Bit System Semaphore Section ΓòÉΓòÉΓòÉ
  363.  
  364. The following C language declarations define the information contained within 
  365. the system resource summary information record that is the first record in the 
  366. 16 bit system semaphore record section of the DosQProcStatus buffer: 
  367.  
  368.  
  369. typedef struct qsS16Headrec_s {
  370.     ULONG     SRecType;  /* semaphore rectype = 3 */
  371.     ULONG     Reserved;  /* overlays NextRec of 1st qsS16rec_t*/
  372.     ULONG     Reserved;
  373.     ULONG     S16TblOff;  /* index of first semaphore,SEE PSTAT OUTPUT*/
  374.                  /* System Semaphore Information Section   */
  375. } qsS16Headrec_t;
  376.  
  377. 16 bit System Semaphore Header Record Structure 
  378.  
  379. ________________________________
  380. |       qsS16Headrec            |
  381. |-------------------------------|
  382. |       qsS16rec_s              |____
  383. |_______________________________|    |
  384. |                               |<---|
  385. |       qsS16rec_s              |____
  386. |______________________________ |    |
  387. |                               |<---|
  388. |       qsS16rec_s              |____
  389. |_______________________________|    |
  390. |            .                  |<---|
  391. |-------------------------------|
  392.  
  393. The following C language declarations define the 16 bit system semaphore 
  394. records: 
  395.  
  396.  
  397. typedef struct qsS16rec_s {
  398.     ULONG      NextRec;      /* offset to next record in buffer*/
  399.     UINT       s_SysSemOwner ;  /* thread owning this semaphore  */
  400.     UCHAR      s_SysSemFlag ;   /* system semaphore flag bit field*/
  401.     UCHAR      s_SysSemRefCnt ;  /* number of references to this  */
  402.                      /*  system semaphore       */
  403.     UCHAR      s_SysSemProcCnt ; /*number of requests by sem owner*/
  404.     UCHAR      Reserved;
  405.     ULONG      Reserved;
  406.     UINT       Reserved;
  407.     CHAR       SemName;      /* start of semaphore name string */
  408. } qsS16rec_t;
  409.  
  410. 16 bit System Semaphore Record Structure 
  411.  
  412. ________________________________
  413. |       pNextRec                |----|
  414. |-------------------------------|    |
  415. |                               |    |
  416. |       SysSemOwner             |    |
  417. |       SysSemFlag              |    |
  418. |       SysSemRecCnt            |    |
  419. |       SysSemProcCnt           |    |
  420. |                               |    |
  421. |-------------------------------|    |
  422. |SemName:                       |    |
  423. |       "pathname"              |    |
  424. |-------------------------------|    |
  425.                                 <-----
  426.  
  427. The s_SysSemOwner is the slot ID of the semaphore's owner 
  428.  
  429. The s_SysSemFlag is the system semaphore flag bit field which describes the 
  430. type or action the semaphore is performing. 
  431.  
  432. The s_SysSemRecCnt is the number of references to a specific semaphore. 
  433.  
  434. The SemName value is actually the first byte of an ASCIIZ string that is the 
  435. complete pathname of the 16 bit system semaphore. 
  436.  
  437.  
  438. ΓòÉΓòÉΓòÉ 4.6. Executable Module Section ΓòÉΓòÉΓòÉ
  439.  
  440. The following C language declarations define the information contained within 
  441. the system resource summary information record that describes an OS/2 DLL 
  442. module: 
  443.  
  444.  
  445. typedef struct qsLrec_s {
  446.     void  FAR    *pNextRec;   /* pointer to next record in buffer */
  447.     USHORT     hmte;      /* handle for this mte */
  448.     USHORT     Reserved;    /* Reserved */
  449.     ULONG     ctImpMod;    /* # of imported modules in table */
  450.     ULONG     Reserved     /* Reserved */
  451.   *** qsLObjrec_t FAR *Reserved;   /* Reserved */
  452.     UCHAR   FAR *pName;     /* ptr to name string following stru*/
  453. } qsLrec_t;
  454.  
  455. System wide MTE information 
  456.  
  457. ________________________________
  458. |       pNextRec                |----|
  459. |-------------------------------|    |
  460. |       hmte                    |    |
  461. |-------------------------------|    |
  462. |       ctImpMod                |    |
  463. |-------------------------------|    |
  464. |       Reserved                |    |
  465. |-------------------------------|    |
  466. |       Reserved                |    |
  467. |-------------------------------|    |
  468. |       pName                   |----|----|
  469. |-------------------------------|    |    |
  470. |       imported module handles |    |    |
  471. |          .                    |    |    |
  472. |          .                    |    |    |
  473. |          .                    |    |    |
  474. |-------------------------------| <--|----|
  475. |       "pathname"              |    |
  476. |_______________________________|    |
  477.                                 <-----
  478.  
  479. The hmte value is a unique identifier that identifies this DLL module. 
  480.  
  481. The ctImpMod value indicates how many other DLL's this module statically 
  482. references.  The ctImpMod value does not take into account any DLL's that were 
  483. dynamically linked at run time. 
  484.  
  485. The pName value is a 16 bit pointer that points to an ASCIIZ string that 
  486. follows the DLL module record.  The string contains the pathname of the DLL 
  487. module. 
  488.  
  489.  
  490. ΓòÉΓòÉΓòÉ 4.7. Shared Memory Segment Section ΓòÉΓòÉΓòÉ
  491.  
  492. The following C language declarations define the information contained within 
  493. the system resource summary information record that describes an OS/2 shared 
  494. memory segment: 
  495.  
  496.  
  497. typedef struct qsMrec_s {
  498.     ULONG     MemNextRec;    /* offset to next record in buffer */
  499.     USHORT     hmem;       /* handle for shared memory */
  500.     USHORT     sel;        /* shared memory selector */
  501.     USHORT     refcnt;      /* reference count */
  502.     CHAR      Memname;      /* start of shared memory name string */
  503. } qsMrec_t;
  504.  
  505. Shared Mem Record Structure 
  506.  
  507. ________________________________
  508. |       MemNextRec              |----|
  509. |-------------------------------|    |
  510. |       hmem                    |    |
  511. |-------------------------------|    |
  512. |       sel                     |    |
  513. |-------------------------------|    |
  514. |       refcnt                  |    |
  515. |-------------------------------|    |
  516. |       Memname                 |    |
  517. |_______________________________|    |
  518.                                 <-----
  519.  
  520. Like the 16 bit system semaphore record, the shared memory segment record 
  521. contains its full ASCIIZ string pathname at the end of the record.