PQUOTA User's Guide @ PQUOTA displays information on resource usage by VMS processes. ; This manual contains a description of the PQUOTA program, C including usage details and an explanation of the output produced. Software Version: 1.16 @ Operating System: OpenVMS/AXP and VAX Version 6.0 or higher. A Copyright ⌐ 1996 by Kari Salminen. This software and this manual C may be freely distributed and modified for non-commercial purposes ? as long as this copyright notice is retained. This software is D provided "AS IS". The author makes no representations or warrantiesD with respect to the software and specifically disclaims any impliedE warranties of merchantability or fitness for any particular purpose. First printing: October 1995 Last revised: March 1998 @ I would like to thank Jim Good for his feedback concerning this documentation. 1. PURPOSE OF PQUOTA M A PQUOTA program run provides information about resource utilisation for C an individual VMS process. The information retrieved includes: - The process name. C - The name of the node on which the process is running. ( - The current process state.B - The CPU time that has been charged to the process so far. . - Current process resource quotas. A - The maximum quota values used by the process during & the current PQUOTA run. 9 - Enabled and pending AST's for this process. I This information is made available in a dynamically updated terminal M display. The maximum quota values used are also written to a session log
file.K Runs of the PQUOTA program may be of indefinite length, and a user may M run several PQUOTA sessions simultaneously on different terminal devices ) (e.g. in different DECterm windows). # 2. STARTING THE PQUOTA PROGRAM L A PQUOTA session is started by running the PQUOTA.EXE executable image.K This image does not require any logical names or symbols to be defined - first. So, to run PQUOTA.EXE just enter: * $ RUN device:[directory]PQUOTA I where 'device:[directory]' is the disk device and directory in which G PQUOTA.EXE is located. (As usual, if PQUOTA.EXE is in your current J default directory, then the device and directory specification can beJ omitted. In this case, the command simply becomes $ RUN PQUOTA. ThisA remark applies also to the other command lines shown below.) G You will then be prompted to identify the process to be monitored: 1 Please enter the target Process PID: F Enter the process identification (PID) of the process you want toI investigate. (The PID value can be obtained from the output of the G $SHOW PROCESS or $SHOW SYSTEM commands. PID values are hexadecimal numbers, e.g. '5060013B') M 3 E Alternatively you can define a DCL 'foreign command' as follows: 2 $ PQUOTA :== $device:[directory]PQUOTA M It is important to note that if you do define a foreign command then the E device and directory specification MUST be included, even if the K PQUOTA.EXE file is in your current default directory. (You may find it @ useful to define such a foreign command in your LOGIN.COM.) L With such a foreign command definition, a PQUOTA session can be startedM just by entering 'PQUOTA', and the PID of the process to be investigated F can be entered directly on the command line. Thus, PQUOTA can be started as follows: $ PQUOTA pid I (If you do not specify a process identification on the command line, L then you will be prompted for a PID value as when you start PQUOTA with an explicit RUN command.) K A third alternative is to copy the PQUOTA.EXE into SYS$COMMON:[SYSEXE] M (or have it copied by your system manager.) Then you can start PQUOTA as follows: $ MC PQUOTA pid or $ MC PQUOTA M when you will then be prompted for the PID. Or, if you define a foreign L command, you can omit the device and directory specification, i.e. whenJ the PQUOTA.EXE program is in SYS$COMMON:[SYSEXE], the foreign command specification is simply: ! $ PQUOTA :== $PQUOTA M Placing the PQUOTA.EXE file in SYS$COMMON:[SYSEXE] makes it available to 8 all users on the system that have CMKRNL privilege. 2.1 Single Sample Mode K In this mode the PQUOTA runs once and stores the output in the session L log file PQUOTA_xxx.OUT. This mode enables you to start the PQUOTA fromH a program or an indirect command file for a snap shot of the target process. E The PQUOTA.EXE must be located in SYS$COMMON:[SYSEXE] or defined G as a foreign command. This feature is not available in interactive
mode. K The PQUOTA is started in 'single sample mode' as follows (the letter X * informs PQUOTA for a single sample) : $ MC PQUOTA pid X or $ PQUOTA pid X = Note: the pid must be 8 digits, even with leading zeros. B Example of a command file which can be called from a program: $! ' $! Input: P1 = pid of target process $! $ define/user sys$output NL: $! $ mc pquota 'P1' X $! M 4 3. SESSION LOG FILE F PQUOTA writes the process name, PID, time stamp, maximum used andG percentage used quota values to the file PQUOTA_xxx_yyy.OUT on the F current default directory, where 'xxx' is the target process name) and 'yyy' is the target process PID. O Any characters in the process name that are not valid file name characters K are replaced by '$' signs. (Valid file name characters are a - z, A - Z, 0 - 9, _, -, and $). C Note: RMS will automatically convert lowercase characters into uppercase. H Entries are appended to the log file at the beginning of the PQUOTAI session and then at 10 minute intervals. If the target process exits F during the PQUOTA run, then the last maximum values available are written also.N A new PQUOTA_xxx_yyy.OUT file is created for each PQUOTA session. If youJ are running a number of PQUOTA sessions simultaneously then each will& have a separate PQUOTA file open. H The PQUOTA_xxx_yyy.OUT is opened as a shared file, which allows you( to type it while PQUOTA is running. B If the target process is outswapped, then some of the processE information is not available. The fields ASTCNT and WSQUO in the < PQUOTA_xxx_yyy.OUT file are written as " * Outswapped". * Example of a PQUOTA_xxx_yyy.OUT file: . _FTA15: 3600029F 31-JAN-1996 16:27:30 Max % BYTCNT 576 0 Bytes BIOCNT 1 0 IO's DIOCNT 0 0 IO's ASTCNT 3 0 Ast's FILCNT 0 0 Files ENQCNT 0 0 Locks TQCNT 0 0 Timers ! PGFLQUO 1680 2 Pagelets ! WSQUO 1104 3 Pagelets . _FTA15: 3600029F 31-JAN-1996 16:37:33 Max % BYTCNT 576 0 Bytes BIOCNT 1 0 IO's DIOCNT 1 0 IO's ASTCNT 3 0 Ast's FILCNT 0 0 Files ENQCNT 0 0 Locks TQCNT 0 0 Timers ! PGFLQUO 1872 2 Pagelets ! WSQUO 1232 3 Pagelets M 5 D Example of a PQUOTA_xxx_yyy.OUT file for an outswapped process: 0 CONFIGURE 36000085 16-APR-1996 19:49:14 Max % BYTCNT 448 0 Bytes BIOCNT 0 0 IO's DIOCNT 0 0 IO's ASTCNT * Outswapped Ast's FILCNT 2 1 Files ENQCNT 0 0 Locks TQCNT 0 0 Timers ! PGFLQUO 1200 3 Pagelets ! WSQUO * Outswapped Pagelets M 6 4. USAGE NOTES 4.1 PRIVILEGES REQUIRED J The Change Mode to Kernel (CMKRNL) privilege is needed to run PQUOTA. I (Use $SET PROC/PRIV=CMKRNL to get this privilege. If it happens that L you're not authorized to set the CMKRNL privilege, you'll have to plead( with your friendly system manager.) & 4.2 INTERPRETING THE QUOTA VALUES K To get reliable results for the maximum values you should usually run J the PQUOTA for several hours or even longer, depending on the type of0 the application process you are monitoring. C Maximum resource usage values less than 5 % indicate that that * particular quota may be set too high.M Usage values of 90 % or more are displayed blinking to draw attention to ' a quota value that may be too low. 4.3 ERROR MESSAGES 1 Possible error messages from PQUOTA include: E #SS$_INVARG - Unknown MWAIT state, should never happen. M #SS$_ITEMNOTFOUND - Can not read Process Control Block (PCB), Process H Header (PHD) or Job Information Block (JIB). L #SS$_NONEXPR - No process found on local node for the specified PID. N #SS$_REMOTE_PROC - Target process not found on local node. PQUOTA can9 monitor only local processes. M 7 4.4 RESTRICTIONS I Quotas may only be displayed for processes running on the same node. 3 The SWAPPER is not allowed as target process. G N.B.: PQUOTA runs partly in Kernel Mode, i.e. a program error or J access violation usually leads to a system crash. Thus, PQUOTA SHOULD1 NOT BE EXECUTED IN A PRODUCTION ENVIRONMENT. 4.5 PQUOTA KIT FILES - The PQUOTA distribution kit consists of: < PQUOTA.EXE Executable file for OpenVMS AXP.< PQUOTA.VAX_EXE Executable file for OpenVMS VAX.K PQUOTA.COM Command file to build PQUOTA on OpenVMS AXP and VAX.G PQUOTA.MAR Common source file for OpenVMS AXP and VAX. J PQUOTA.PS PQUOTA User's guide Postscript file (i.e. this& document).: PQUOTA.TXT PQUOTA User's guide text file.E PQUOTA.DOC PQUOTA User's guide DECwrite source file. > ARCH_DEFS.MAR Architectural definitions file for ALPHA. # 4.6 BUILD OF PQUOTA EXECUTABLE D To build the PQUOTA executable image, set your current defaultI directory to the one containing the PQUOTA kit files and execute the ( command file PQUOTA.COM as follows: $ @PQUOTA M 8 5. SCREEN DISPLAY L The display is updated once per second. If a maximum used value reachesH 90 %, then the maximum values for that particular quota will blink. I Ctrl-W will refresh the screen, and Ctrl-Z exits the PQUOTA program. H The display is currently almost identical on both VAX and Alpha AXPJ platforms. The only difference is in the reporting of the PGFLQUO andK WSQUO quotas, which are shown in units of 'pagelets' on an AXP, but in L units of 'pages' on a VAX. However, both VAX pages and AXP pagelets areM equal to 512 bytes in size. (The AXP page size is currently 8192 bytes.) B If the target process is outswapped, then some of the processI information is not available. The fields CPU time, ASTCNT and WSQUO M are displayed as " * Outswapped * ", the AST's enable field is displayed as "----". G VIRT SIZE is the size of current virtual address space in 512 byte page(let)s. 5.1 SAMPLE DISPLAYS On an AXP: K Node : AXP PQUOTA V1.15 12-MAR-1998 18:18:43 G Process : _FTA15: CPU : 0 00:03:27.38 Ena Pend G Username : SALMINEN State : COM AST's: KESU ---- B Virt size: 38448 I/O's : 456879 Pflts: 6158C ---- Sysgen ---- -------------- Process --------------- ? curr max B max/def min max free used % used %C ================================================================== I BYTCNT 1000000 1000000 1000000 484160 515840 56 524032 57 Bytes H BIOCNT 1000 200 3150 3097 53 1 54 1 IO'sH DIOCNT 1000 200 1250 1197 53 4 54 4 IO'sI ASTCNT 200 200 4096 3932 164 4 166 4 Ast's I FILCNT 200 200 1000 985 15 1 15 1 Files I ENQCNT 1000 1000 20000 19990 10 0 10 0 Locks J TQCNT 200 64 1200 1190 10 0 10 0 TimersL PGFLQUO 65536 65536 50000 48940 1060 2 1060 2 PageletsL WSQUO 327680 20 20669 18135 2534 12 2534 12 Pagelets M 9 On a VAX: J Node : VAX PQUOTA V1.9 31-JAN-1996 10:57:21F Process : _FTA12: CPU : 0 00:00:33.84 Ena PendF Username : SALMINEN State : LEF AST's: KESU ---- B ---- Sysgen ---- -------------- Process ---------------> curr maxA max/def min max free used % used % B ==================================================================H BYTCNT 100000 65536 100000 98336 1664 1 1664 1 BytesG BIOCNT 100 18 100 100 0 0 0 0 IO's G DIOCNT 100 18 100 100 0 0 0 0 IO's H ASTCNT 600 24 600 597 3 0 3 0 Ast'sH FILCNT 300 16 300 298 2 0 2 0 FilesH ENQCNT 200 30 200 200 0 0 0 0 LocksI TQCNT 200 0 200 200 0 0 0 0 Timers H PGFLQUO 32768 512 30000 29799 1201 0 1201 0 PagesH WSQUO 236214 20 234484 233886 598 0 598 0 Pages $ On an AXP for an outswapped process: J Node : AXP PQUOTA V1.9 16-APR-1996 19:11:57F Process : CONFIGURE CPU : * Outswapped * Ena PendF Username : SYSTEM State : HIBO AST's: ---- ---- D ---- Sysgen ---- -------------- Process ---------------D curr maxH max/def min max free used % used %B ==================================================================H BYTCNT 65536 100000 100000 99552 448 0 448 0 BytesG BIOCNT 32 100 200 200 0 0 0 0 IO's G DIOCNT 32 100 200 200 0 0 0 0 IO's H ASTCNT * Process is Outswapped * Ast'sH FILCNT 128 100 200 198 2 1 2 1 FilesH ENQCNT 64 300 300 300 0 0 0 0 LocksI TQCNT 16 0 200 200 0 0 0 0 Timers K PGFLQUO 65536 32768 32768 31568 1200 3 1200 3 Pagelets K WSQUO * Process is Outswapped * PageletsT M 10t 5.2 QUOTA VALUES G There are two main quota value categories, "Sysgen" and "Process":e 5.2.1 Sysgen Values max /def min H The maximum/default and minimum limits per quota value that are set system-wide.d D (These values correspond to the appropriate SYSGEN parameters). 5.2.2 Process Values maxT H The maximum limit per quota value that is specified for the processK owner in the SYSUAF.DAT file. (As defined with the AUTHORIZE utility.)i free 2 The currently available amount per resource. curr used % > The current amount used and percentage used per resource. max used %n K The maximum amount used and maximum percentage used per resource sinceP- the beginning of the current PQUOTA run.s K The rightmost column of the display indicates the units of measurementeM of each resource quota value. For instance, BYTCNT is shown in bytes and BIOCNT in (number of) IO's. M 11h r # 6. EXPLANATION OF QUOTA VALUES K The System Max(imum) and Min(imum) values shown below are the names ofe% corresponding SYSGEN parameters. D The Process Max(imum) in each case is the name of a field in anM AUTHORIZE entry. The runtime value for a process maximum is the value oft0 this AUTHORIZE entry for the process owner. ) 6.1 BYTCNT - Buffered I/O Byte Limit I The maximum number of bytes of nonpaged system dynamic memory that ae( user's job can consume at one time.M Nonpaged dynamic memory is consumed in such operations as I/O buffering,i( mailboxes, and file-access windows. System Max: PQL_DBYTLMe Min: PQL_MBYTLM Process Max: BYTLM * 6.2 BIOCNT - Buffered I/O Count Limit I The maximum number of buffered I/O operations, such as terminal I/O, ) that can be outstanding at one time.Q System Max: PQL_DBIOLM. Min: PQL_MBIOLM. Process Max: BIOLM ( 6.3 DIOCNT - Direct I/O Count LimitK The maximum number of direct I/O operations (usually disk) that can bef outstanding at one time.I System Max: PQL_DDIOLMe Min: PQL_MDIOLMr Process Max: DIOLM M 12 ! 6.4 ASTCNT - AST Queue Limito F The total number of asynchronous system trap (AST) operations andJ scheduled wake-up requests that the user can have queued at one time. System Max: PQL_DASTLM Min: PQL_MASTLMe Process Max: ASTLM ! 6.5 FILCNT - Open File Limit H The maximum number of files that can be open at one time, including# active network logical links. System Max: PQL_DFILLM Min: PQL_MFILLMe Process Max: FILLM " 6.6 ENQCNT - Lock Queue Limit L The maximum number of locks that can be queued by the user at one time. System Max: PQL_DENQLMP Min: PQL_MENQLMn Process Max: ENQLM I 6.7 TQCNT - Timer Queue / Temporary Common Event Flag Clusters Limit H The maximum number of entries in the timer queue plus the number ofM temporary common event flag clusters that the user can have at one time.e System Max: PQL_DTQELM Min: PQL_MTQELM Process Max: TQELM M 13 e " 6.8 PGFLQUO - Page File QuotaG The maximum number of pages that the process can use in the systemt paging file. ! System Max: PQL_DPGFLQUOTAN! Min: PQL_MPGFLQUOTA Process Max: PGFLQUOTA " 6.9 WSQUO - Working Set Quota K The maximum amount of physical memory a user process can lock into its working set. E Also represents the maximum amount of swap space that the systemoM reserves for this process and the maximum amount of physical memory thatXM the system allows the process to consume if the systemwide memory demand is significant. System Max: PQL_DWSQUOTAP Min: PQL_MWSQUOTA$ Process Max: WSQUOTA ; 6.10 AST's - Enabled and pending AST's for the process. J The enabled and pending AST's for this process are shown in the upperL right corner. The "Ena" field shows the currently enabled AST's and theK "Pend" field shows currently pending AST's. Usually the display shouldi be as follows: % Ena Pend.% AST's: KESU ----X K If any pending AST's are shown, the process is probably either hanginge; or stopped at a debugger breakpoint in an AST routine. = The letters KES and U correspond to the processor modes:i K = Kernel E = Executiveo S = Supervisor U = User K An entry of - indicates that the corresponding AST is not enabled or M not pending (depending on whether it is shown under the 'Ena' heading ore the 'Pend' heading.)/ M 14 6 6.11 Virt size - Size of process virtual address space < The size of the current virtual address space in page(let)s. 6.12 I/O's - Process total I/O's L The total amount of buffered and direct I/O's since the process was started. & 6.13 Pflts - Process total page faults > The total amount of page faults since the process was started. M 15
