                                     			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:  2.0  A 	Operating System:   OpenVMS Alpha and VAX Version 6.0 or higher. 7 	                    OpenVMS I64 Version 8.2 or higher.           F 	Copyright  1996,2005 by Kari Salminen. This software and this manualC 	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:    December 2005                                                                             @ 	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. 8             - The name of the user who owns the process.C             - The name of the node on which the process is running. (             - The current process state.G             - The CPU time that has been charged to the process so far. 2             - Current virtual size of the process.3             - Number of total I/O's and pagefaults. 9             - Current system and 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 P      log file PQUOTA_xxx_yyy.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.   K      NOTE: Some processes, like servers, are doing internal caching and may )            always use 100 % of the WSQUO.             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 Alpha.<             PQUOTA.I64_EXE  Executable file for OpenVMS I64.<             PQUOTA.VAX_EXE  Executable file for OpenVMS VAX.O             PQUOTA.COM      Command file to build PQUOTA on Alpha, I64 and VAX. N             PQUOTA.MAR      Common source file for OpenVMS Alpha, I64 and VAX.?             PQUOTA.PS       PQUOTA User's guide Postscript file :             PQUOTA.TXT      PQUOTA User's guide text file.E             PQUOTA.DOC      PQUOTA User's guide DECwrite source file.     #      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.     D      The display is currently almost identical on Alpha, I64 and VAXJ      platforms. The only difference is in the reporting of the PGFLQUO andN      WSQUO quotas, which are shown in units of 'pagelets' on an Alpha and I64,L      but in units of 'pages' on a VAX. However, both VAX pages and Alpha/I64M      pagelets are equal to 512 bytes in size. (The Alpha and I64 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 Alpha:   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      K   A process with a large page file quota (PGFLQUO in K_Paglts) on an Alpha:   L   Node     : WS242            PQUOTA V2.0                6-DEC-2005 11:13:51H   Process  : _FTA20:          CPU :00:14:30.07                 Ena  PendH   Username : SALMINEN         State : LEF               AST's: KESU ----D   Virt size: 177872           I/O's : 176869            Pflts: 21777F           ---- Sysgen ----  ---------------- Process -----------------A                                                  curr         max F           max/def      min      max     free     used   %     used   %F  =====================================================================L  BYTCNT  10000000 10000000 10000000  9995584     4416   0     4416   0 BytesK  BIOCNT      1000      600    10000     9999        1   0        1   0 IO's K  DIOCNT      1000      600     4096     4096        0   0        0   0 IO's L  ASTCNT      1200      800     4096     4093        3   0        3   0 Ast'sL  FILCNT       800      600     1000     1000        0   0        0   0 FilesL  ENQCNT      6000     4000    20000    20000        0   0        0   0 LocksM  TQCNT        200      100     2000     2000        0   0        0   0 Timers O  PGFLQUO   100000        2   100000      395        4   1        4   1 K_Paglts O  WSQUO    1763328       20  1763328  1760560     2768   0     2768   0 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 Alpha 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 *                                  Pagelets                                   M                                                                            10             5.2 QUOTA VALUES     G      There are two main quota value categories, "Sysgen" and "Process":           5.2.1 Sysgen Values                 max /def  min     H      The maximum/default and minimum limits per quota value that are set      system-wide.   D      (These values correspond to the appropriate SYSGEN parameters).           5.2.2 Process Values                 max     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.)                  free    2       The currently available amount per resource.                 curr             used    %     >      The current amount used and percentage used per resource.                max             used    %   K      The maximum amount used and maximum percentage used per resource since -      the beginning of the current PQUOTA run.   K      The rightmost column of the display indicates the units of measurement M      of each resource quota value. For instance, BYTCNT is shown in bytes and        BIOCNT in (number of) IO's.                        M                                                                            11       #      6. EXPLANATION OF QUOTA VALUES     K      The System Max(imum) and Min(imum) values shown below are the names of %      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 of 0      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 a (      user's job can consume at one time.M      Nonpaged dynamic memory is consumed in such operations as I/O buffering, (      mailboxes, and file-access windows.          System  Max:  PQL_DBYTLM               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.           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 be       outstanding at one time.         System  Max:  PQL_DDIOLM               Min:  PQL_MDIOLM         Process Max:  DIOLM                              M                                                                            12       !      6.4 ASTCNT - AST Queue Limit   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_MASTLM         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_MFILLM         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_DENQLM               Min:  PQL_MENQLM         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.           System  Max:  PQL_DTQELM               Min:  PQL_MTQELM         Process Max:  TQELM                                      M                                                                            13     "      6.8 PGFLQUO - Page File QuotaG      The maximum number of pages that the process can use in the system       paging file.   !      System  Max:  PQL_DPGFLQUOTA !              Min:  PQL_MPGFLQUOTA         Process Max:  PGFLQUOTA  G      NOTE: on Alpha and I64 PGFLQUO is shown in Pagelets or in K_Paglts 8 	   (= kilopagelets) if larger than 99'999'999 pagelets.  "      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 system M      reserves for this process and the maximum amount of physical memory that M      the system allows the process to consume if the systemwide memory demand       is significant.          System  Max:  PQL_DWSQUOTA               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 should       be as follows:     %                             Ena  Pend %                      AST's: KESU ----   K      If any pending AST's are shown, the process is probably either hanging ;      or stopped at a debugger breakpoint in an AST routine.     =      The letters KES and U correspond to the processor modes:                  K = Kernel             E = Executive              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 or       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 