by Jeff Vance, CSY
Enhancements summary:
- The new PINFO evaluator function returns information for a process.
- The JINFO function has 4 new items and restriction changes on the IP address, CI PIN and JSMAIN PIN items.
Pinfo
Syntax: PINFO ( pin, item [,status] )
pin Required. String or integer identifying the target process or
thread. The format for pin is:
nnn or '[#P]nnn[.tid]'
where nnn is a simple number and 'tid' is the optional
thread id. A pin value of '0' refers to the caller's process.
item Required. String label specifying the information requested for
the target process. Only one item can be requested per call to
PINFO, although some of the items below return multiple pieces
of information.
status Optional. An unquoted CI variable name to hold the integer status
value for PINFO. If passed, the variable named by this argument
contains the status of the call to pinfo: zero indicates success,
non-zero indicates a failure. When 'status' is passed and an
error occurs, the CI ignores the error. Specifically, no message
is written to $STDLIST or to $STDERR, and the CIERROR variable is
not set. The PINFO function return is always -1 when 'status' is
specified and a PINFO error occurs. If this argument is omitted
and an error in PINFO occurs, a CI error message is written to
$STDLIST (within the definition of the HPMSGFENCE variable).
status values:
0 - success
9952 - unknown PINFO item
9955 - information for the requested item is unavailable for
the target process
9956 - item security violation, the user needs greater
privileges to retrieve the item
11001 - cannot access pin
11004 - process does not exist
... and various SHOWPROC CIERROR values.
Example: :calc PINFO('#P123','IPaddr')
Result: 15.192.90.81
Example: :calc PINFO(0,'ExecState')
Result: READY
Example: :calc PINFO( 263,'NumProcesses')
Result: 8, $8, %10
Example: :calc PINFO('263','children')
Result: 8/277 281 290 155 120 311 296 315
Example: :calc PINFO( JINFO( '#J123','CIpin'), 'NumOpenFiles')
Result: 10, $A, %12
Example: setvar i HPPIN
(walk up while PINFO( i,'ProcType') <> 'JSMAIN' do
process setvar i PINFO( i,'parent')
tree) endwhile
Restrictions
PINFO does not allow users to access process data if the same user cannot issue the SHOWPROC command against the target PIN. Thus, SHOWPROC access rules are enforced by PINFO. Specifically, the user must have SM or OP capability, or the user must have AM capability and the target process has the same 'user.account', or the process' 'user.account' matches the user's and JOBSECURITY is low, or the target PIN is actually the user's PIN.
Furthermore, certain items have additional restrictions: to obtain the IP address the user needs to posses one of: SM, OP, NM, NA or PM capbilities, which are the same rules enforced by the SHOWCONN utility. To retrieve the program name or the info= string the user needs full access to the PIN. The info= string has
any text that resembles a lockword blanked out. Enter ':help showproc all' for more details on access and security rules.
Pinfo item values and descriptions
Label Type Description
-------------- ------ --------------------------------------------------
Alive bool True if pin is alive (not dead)
Boosted bool True if pin's priority has been boosted
BoostReason string 'NO BOOST','OWNS PRI SEMA','OWNS SIR','LONG SYS
TRANS','BREAK','BLOCKED UNPREEMPTABLE','IPC SERV
CONTENTION',LONG USER TRANS','OWNS PRI SEMA PORT',
'PRI OSCILLATION'
BoostType string 'NO BOOST','LINEAR','DECAY'
Child int pin of first child process
ChildPin int same as 'child'
Children string list of all descendant pins, format:
'total/pin1 pin2 ... pinN'.
Note that truncation is evident when 'total' is
greater than number of pins returned, e.g.
:setvar x pinfo('123','children')
:if wordcnt(x) < ![word(x,'/')] then
# truncation occurred...
ChildrenPins string same as 'children'
CMask int POSIX cmask for file creation security
CMMode bool True if pin is currently in CM
CMProg bool True if pin is a CM program (PROG filecode)
CPUMilliSec int number of milliseconds of CPU
Creator int creator pin, usually the parent pin
CreatorPin int same as 'creator'
CriticalDepth int > 0 means process is critical and cannot be aborted,
unless it is waiting on a terminal read
EGID int POSIX effective group ID
EUID int POSIX effective user ID
ExecState string execution state: 'BLOCK MEM MGR','BLOCK CB',
'BLOCK MSG','READY','BLOCK TERM'
Exist bool True if the target pin exists in any state
Exists bool same as 'exist'
FmtCPUMilliSec string formatted CPU time 'MM:SS.mls' or 'HH:MM:SS'
FmtEGID string formatted EGID ('account name')
FmtEUID string formatted EUID ('user.account')
FmtGID string formatted GID ('account name')
FmtPID string MPE internal process ID: 'pin reuse_cnt'
FmtUID string formatted UID ('user.account')
FmtWaitMilliSec string formatted CPU time 'MM:SS.mls' or 'HH:MM:SS'
GID int POSIX group ID
HasSIR bool true if pin owns a SIR
HPEPri int internal priority in the range of 0..32767; a
higher number is greater priority
InBreak bool true if pin is in break mode
Info string * info= string with all lockwords removed
InfoString string same as 'info'
InitThreadPin int the PIN of the initial thread, 0 if not a
thread
IntProcType int process type, 0=user, 1=son, 2=usermain,
3=task, 4=system, 5=detach, 6=jsmain
IntWaitReason int see 'waitreason' item
IPAddr string ** IP address in dotted format (xx.xx.xx.xx)
JobNum string job/session ID, '#J|Snnn'
JSMAIN int pin of JSMAIN process
JSMAINPin int same as 'jsmain'
Linear bool true if process priority does not decay
LinearPriority bool same as 'linear'
MPECmask int internal MPE cmask
MPEPri int MPE external priority in the range 0..255; a
higher number is less priority
NumFilesOpen int number of open files including system files
NumOpenFiles int same as 'numfilesopen'
NumPINs int number of descendant processes
NumProcesses int same as 'numpins'
Parent int parent pin
ParentPin int same as 'parent'
Parm int run/creation parm= value
PendingIOCount int total IOs outstanding for pin
PendIOs int same as 'pendingiocount'
PIN int pin, useful if target pin is a thread
PriAfterBoost int pin priority when boost period is over
ProcState string 'DYING','DEAD','ALIVE','INITIATE','UNBORN' --
all states but 'alive' are rare
ProcType string 'USER','SON','MAIN','TASK','SYSTEM',
'DETACH','JSMAIN'
Program string * MPE or POSIX name of program file
ProgramName string same as 'program'
PxPID int POSIX PID: 16 bit reuse_cnt, 16 bit PIN
QPri string scheduling queue followed by MPE priority
QueuePriority string same as 'qpri'
SchedQ string scheduling queue, 'AS','BS,'CS','DS','ES'
SchedQueue string same as 'schedq'
SchedState string 'EXECUTING','READY','SHORT WAIT','LONG WAIT'
SecondaryThreads string list of secondary threads in the same format
as used by "Children"
Setdump bool true if SETDUMP enbabled
Sibling int first sibling pin
SiblingPin int same as 'sibling'
SystemDepth int system code depth, >0 means in system code
ThreadID int TIN (thread ID number), 1 for non-threaded
processes, >1 for threaded processes
ThreadType string 'NONE','INITIAL','SECONDARY'
TIN int same as 'threadid'
UID int POSIX user ID
UnboostPri int same as 'priafterboost'
UserAcct string 'user.account'
UserProcess bool true if pin is a user process, process type
is 0,1,2
WaitMilliSec int time pin has been waiting (need MI)
WaitReason string 'PAGE FLT NM CODE','PAGE FLT NM STK','PAGE FLT
NM TRANSIENT','PAGE FLT FILE','PAGE FLT CM CODE',
'PAGE FLT CM STK','PAGE FLT CM TRANSIENT' (above
7 require MI),'TERMINAL READ','TERMINAL WRITE',
'DISC IO','OTHER IO','IPC TRANS COMPLETE','SIR',
'RIN','MM PREFETCH','EXPIRED QUANTUM','TIMER',
'PARENT','CB','CHILD','DATA COMM','RIT','DISP
WORK','PORT','MAIL','JUNK','MSG','IMPEDE','BREAK',
'WAIT QUEUE','MEM MGR','PORT BLOCK','FILE BLOCK',
'FILE UNBLOCK','STORAGE MGT','DEBUG MSG','IO CONF',
'PFP REPLY','DBMON','FILL DISC','HILO','FS TERM IO',
'MM POST','SIG TIMER','PREEMPTION','DISC IO
PREMPTION','PRI PREEMPTION','SQL LOCK','SQL LATCH',
'SQL BUFF','LONG PAUSE','MM FREEZE','RELEASE',
'DEFERRED PREEMPT','MM PSEUDO IO READ','MM PSEUDO IO
WRITE','OTHER','NOT WAITING','DEAD PROCESS'
WG string workgroup name
WorkGroup string same as 'wg'
* indicates further restrictions apply to these items: you must have SM
capability, or the PIN must be you, or the user.account of the PIN must
be the same as your user.account and JOBSECURITY is low. Otherwise, the
item is not returned and an error is generated.
** indicates you must have at least one of SM,OP,NA,NM,PM capabilities.
PINFO is a CI interface to the AIFPROCGET Architected Interface. In many cases there is a one-to-one mapping of a PINFO item and the associated item retrieved via AIFPROCGET. However, there are also many PINFO items that are formatted based on the raw data returned by the AIF. Below are a few notes on a subset of the returned PINFO items.
children - as mentioned above, the format for the returned string of all decendant processes is: 'NNN/pin1 pin2 ... pinN', where the actual (real) number of descendants is returned to the left of the '/' delimiter. CI string variables are currently limited to 1024 characters, and thus, subject to truncation if there are a large number of descendant processes. Even if the returned string is truncated the number left of the '/' is the true number of descendants. The easiest way to detect truncation is to compare the number of tokens in the returned string versus the first number in the string. For example:
setvar kids PINFO('1234', 'children')
setvar num_tokens WORDCNT(kids) # '/' is not a delimiter to WORDCNT
setvar num_kids ![WORD(kids, '/')] # convert to integer
if num_kids <> num_token then # truncation
There is no work-around for truncation, other than choosing a PIN closer to the end of the process tree. Also note that the target PIN is not counted as a descendant nor is it included in the string of children. The same format and truncation logic applies to the secondarythreads item.
cmask - MPE stores a process' file creation default security (cmask) differently from the POSIX representation. PINFO returns the POSIX version and the MPE version of the cmask. For POSIX, the cmask is the ones compliment of the nine file permissions: read, write, execute access for Owner, for Group and for Other. The shell's umask and umask -S commands provide cmask information. For example, if the POSIX cmask is %007, the one compliment is %770, which provides default file permissions of rwxrwx--- (in ls -l format).
The mpecmask item returns the internal MPE cmask as shown below:
1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-------------------|------------------|------------------|----------
|R W X A L TdRdCdDd|R W X A L TdRdCdDd|R W X A L TdRdCdDd|I x x x x|
-------------------|------------------|------------------|----------
OWNER GROUP OTHER
where 'A' is append access, 'L' is lock access, 'Td' is traverse directory entries permission, 'Rd' is read directory entries permission, 'Cd' is create directory entries permissions, 'Dd' is delete directory entries permission, and 'I' is an ACD validity bit.
POSIX read access is granted if the 'R' or 'Rd' bits are set. POSIX write access is granted if the 'W', 'Cd', or 'Dd' bits are set. POSIX execute access is granted if the 'X' or 'Td' bits are set.
fmtcpumillisec - returns the same formatted time as shown by :SHOWPROC. The initial format is: MM:SS.milliseconds. Once this format overflows it is automatically converted to HH:MM:SS. The same formatting applies to fmtwaitmillisec.
fmtpid - a process ID (PID) is unique for the life of the system. It consists of 32 bits of a PIN and 32 bits of a reuse count. Since the CI does not yet support 64 bit numbers, the formatted MPE PID is returned in a string. The string contains the ASCII PIN, followed by a single space, followed by the ASCII reuse count. The pxpid is the POSIX PID and consists of the 16 bit reuse count followed by the 16 bit PIN. This value is returned as a 32 bit CI integer, and is the same number seen in the shell's 'ps' command output.
hpepri - the internal priority for the process. Integers in the range of 0..32767 are valid. A larger number indicates a higher (greater) priority for the process. This value can be converted to the mpepri as follows:
mpepri = (32767 - hpepri) div 128
Thus, a larger MPE priority number indicates a smaller (less) priority for the process in question.
program - if the program filename can be represented in MPE syntax then it is returned in the traditional MPE 'file.group.account' format. Otherwise, the program name is returned in POSIX (HFS) syntax as an absolute pathname.
Jinfo
Four new items have been added to the JINFO function:
Executing bool True if the target job exists and is in the
INTRO, EXEC* or EXEC states.
Scheduled bool True if the target job exists and is in the
SCHED state.
Suspended bool True if the target job exists and is in the
SUSP state.
Waiting bool True if the target job exists and is in the
WAIT state.
ipaddr, the IP address item, now requires the same capabilities as enforced by the SHOWCONN utility and by the :LISTFILE,access command. Namely, one of: SM, OP, NA, NM, or PM capbility is required in order to obtain the IP address of the target session.
The cipin and jsmainpin items no longer have special restrictions in place. Any user can retrieve the CI PIN or the JSMAIN PIN for any job/session.
CPU time, in both seconds and milliseconds, is now accurate for all jobs and sessions.
|
Printable version
