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