persistent class %SYS.ProcessQuery
extends %Persistent, %SYSTEM.Help
This class allows manipulation and display of Cache processes running on the system.
An instance of the class can be opened by passing the PID (O/S process id)
to the %OpenId Method. The PID is in decimal form ($J) for all platforms.
NOTE: Previous versions of this class allowed you to call the %OpenId method
and pass in either a PID preceded by the letter "P", or a job number preceded
by the letter "J". This functionality has been removed from the %OpenId() method,
and moved to the new Open() method which supports this syntax.
For example, the following open a process with a PID of 2078:
s Process=##CLASS(%SYS.ProcessQuery).%OpenId("2078")
s Process=##CLASS(%SYS.ProcessQuery).Open("P2078")
s Process=##CLASS(%SYS.ProcessQuery).Open("2078")
The following will open Job number 23
s Process=##CLASS(%SYS.ProcessQuery).Open("J23")
Performance considerations:
When you use %OpenId() to examine a process, several mailbox messages will get sent to
the process to return ALL of the properties for the object. On systems with lots of processes
running, and you are collecting data for a lot of processes, this can cause a lot of overhead.
The call to each %OpenId() in this case may actually take several seconds to complete.
Most of a processes properties can be retrieved without the overhead of a mailbox message. See
the description of the individual properties below for which properties require a mailbox message
to be sent.
If you want to minimize overhead, you should use an SQL statement to select ONLY the data
which you want returned. For example, here is some code which loops through all the processes
on the system, and retrieves specific data for each process. Note that the properties which
are returned in this example are ones which do not require a mailbox messages to be sent to the
process being examined. Note that the %syPidtab.inc file needs to be included in your routine
in order for the following code to compile cleanly.
#include %syPidtab
Set Rset = ##class(%ResultSet).%New("%SYS.ProcessQuery:ListPids")
d Rset.Execute()
While Rset.Next() {
&sql(SELECT CommandsExecuted,GlobalReferences INTO :CommandsExecuted,:GlobalReferences
FROM %SYS.ProcessQuery
WHERE Pid = :Rset.GetData(1))
i SQLCODE'=0 w !,"SQL Error "_SQLCODE continue ; 100 means process does not exist (halted)
w !,Rset.GetData(1)," ",CommandsExecuted," ",GlobalReferences
}
d Rset.Close()
Security considerations:
Any process can open an instance to their own process by passing the value of $J to
the %OpenId() method:
s Process=##CLASS(%SYS.ProcessQuery).%OpenId($j)
If you wish to open another process, you must own the %Admin_Manage:Use
resource, or have read or write access to the CACHESYS database. To minimize overhead in
the %OpenId() method, having the %Admin_Manage:Use privilege is recommended.
This class has an SQL table called %SYS.ProcessQuery where you can execute an SQL
query to return process data. For example you could execute the following
queries:
Select * from %SYS.ProcessQuery - Return all information about all processes
Select * from %SYS.ProcessQuery where NameSpace = 'User" - Return all information about
all processes in the USER namespace.
Note that in order to run this from an unprivileged user, you may need to grant privileges
to that user on the table as follows:
GRANT SELECT ON %SYS.ProcessQuery TO _PUBLIC
Notes:
Replace _PUBLIC to a specific user or role name if you don't want everyone to have the privilege.
This is per-namespace. This needs to be executed in each namespace the table needs to be queried from.
• parameter DEFAULTCONCURRENCY = 0;
DEFAULTCONCURRENCY is the default value for the concurrency formal argument
defined for %Open, %OpenId, %Delete and %DeleteId methods. It is not the default
value of the %Concurrency property of persistent classes. If the value of the actual
concurrency argument passed to any of the above methods is -1 then the formal argument value will
be set to the value of the DEFAULTCONCURRENCY parameter value defined for the class.
• parameter DOMAIN = "%Utility";
Set this to the correct domain.
• property CSPSessionID
as %String [ ReadOnly ];
CSP Session ID of client connected to process.
CSP session ID of the client which initiated the connection.
It is passed down to the process as part of the initial connection message,
and used to manager the CSP session.
• property CanBeExamined
as %Boolean [ ReadOnly ];
Process can be examined.
Flag checked by JOBEXAM and Mgt Portal to see if a process can
be examined in detail.
• property CanBeSuspended
as %Boolean [ ReadOnly ];
Process can be suspended.
Flag checked by JOBEXAM and Mgt Portal to see if a process can
be suspended.
• property CanBeTerminated
as %Boolean [ ReadOnly ];
Process can be terminated.
Flag checked by JOBEXAM and Mgt Portal to see if a process can
be terminated.
• property CanReceiveBroadcast
as %Boolean [ ReadOnly ];
Process can receive broadcast.
Flag checked by JOBEXAM and Mgt Portal to see if a process can
receive a broadcast. Usually this means they are attached to a terminal.
• property ClientExecutableName
as %String;
Executable name of the process on the client.
The name of the Executable or DLL on the client which initiated the connection.
It is passed down to the process as part of the initial connection message.
This property may be set by the end-user if they are managing their own connections.
• property ClientIPAddress
as %String;
IP Address of client connected to the process.
IP address of the client which initiated the connection.
It is passed down to the process as part of the initial connection message.
This property may be set by the end-user if they are managing their own connections.
• property ClientNodeName
as %String;
Node Name of the client connected to the process.
Node name of the client which initiated the connection.
It is passed down to the process as part of the initial connection message.
This property may be set by the end-user if they are managing their own connections.
• property CommandsExecuted
as %BigInt [ ReadOnly ];
Number of Commands Executed.
Total number of commands which the process has executed.
• property CurrentDevice
as %String [ ReadOnly ];
Current Device ($i).
Current device that the process has open and is USEing via the USE command.
• property CurrentLineAndRoutine
as %String [ ReadOnly ];
Current Line and Routine.
Current line and routine that the process is executing.
Returned in +number^routine format.
This property requires a mailbox message to be sent to the process being examined.
• property CurrentSrcLine
as %String [ ReadOnly ];
Current Source Line being executed.
Current line of source code which is being executed by the process. If "",
then the source code line is unavailable.
This property requires a mailbox message to be sent to the process being examined.
• property GlobalBlocks
as %Integer [ ReadOnly ];
Number of Database Block Allocations.
Total number of new database blocks the process has allocated. An indication of database growth.
• property GlobalDiskReads
as %Integer [ ReadOnly ];
Number of Physical Database Reads.
Total number of times the process has fetched data from disk.
• property GlobalReferences
as %BigInt [ ReadOnly ];
Number of Global References.
Total number of global references the process has made.
• property GlobalUpdates
as %Integer [ ReadOnly ];
Number of Global Updates.
Total number of global updates (sets and kills) the process has made.
• property InTransaction
as %Integer [ ReadOnly ];
In a transaction.
If 0, the process is not in a transaction.
If >0, the process has executed a tstart command, is in a transaction, and the value
is the offset in the journal file where the transaction has started.
• property IsGhost
as %Boolean [ ReadOnly ];
Is a Ghost process.
The process has been killed at the O/S level, and has not yet been cleaned
up by the CLNDMN process. Until the process is cleaned, their may be outstanding
locks or resources which may be unavailable to other processes.
This property requires a mailbox message to be sent to the process being examined.
• property JobNumber
as %Integer [ ReadOnly ];
Job number in process table.
Used as an index into the job table. May be passed to the Open() method to
open an object instance to that process.
• property JobType
as %Integer [ ReadOnly ];
Job type.
Number which tells what type of process it is.
See the %syPidtab.inc include file for a definition of macros for these fields.
Only use the defined macros in %syPidtab when referencing these fields.
For example:
If Process.JobType=$$$WDTYPE w !,"Process is the write daemon"
• property LastGlobalReference
as %String [ ReadOnly ];
Last Global Reference.
Last global reference that the process made.
This property requires a mailbox message to be sent to the process being examined.
• property LicenseUserId
as %String [ ReadOnly ];
User Id used for license.
The User ID which took out the license for the process.
• property LinesExecuted
as %BigInt [ ReadOnly ];
Number of Lines Executed.
Total number of lines which the process has executed.
NOTE: This property is deprecated, line counts are no longer available and this actually returns the CommandsExecuted.
It is left here for backwards compatibility, but should no longer be used.
• property Location
as %String [ ReadOnly ];
Location.
If a system process, will be the system processes name.
If a user process, will be the value of $g(^%IS(0,Job.CurrentDevice),"")
• property MemoryAllocated
as %Integer [ ReadOnly ];
Maximum memory able to be used in KB ($ZS).
Maximum amount of memory in KB that the process is allowed to use.
This property requires a mailbox message to be sent to the process being examined.
• property MemoryPeak
as %Integer [ ReadOnly ];
Peak memory allocated in KB.
This property requires a mailbox message to be sent to the process being examined.
• property MemoryUsed
as %Integer [ ReadOnly ];
Memory used in KB (Current $s).
Current amount of memory the process has used in KB.
This property requires a mailbox message to be sent to the process being examined.
• property NameSpace
as %String [ ReadOnly ];
Namespace process is executing in.
• property OSUserName
as %String [ ReadOnly ];
Operating system username of process.
Username given to the process by the operating system when the process
is created. When displayed, it is truncated to 16 characters. Note that the real O/S
username is only returned when connecting to UNIX or VMS systems; For Windows, it
will return the O/S username for a console process, but for telnet it will return
the $USERNAME of the process. For client connections, it contains the O/S username
of the client.
• property OpenDevices
as %String [ ReadOnly ];
List of open devices.
List of devices which the process has opened. Returned as a
comma separated string.
This property requires a mailbox message to be sent to the process being examined.
• property Pid
as %String [ ReadOnly ];
Process ID.
Process ID ($J) given to the process by the O/S, decimal form on all platforms.
• property PidExternal
as %String [ ReadOnly ];
External Process PID.
Decimal value for Windows, Unix and Mac, hex for VMS.
• property PrincipalDevice
as %String [ ReadOnly ];
Principal Device ($P).
This property requires a mailbox message to be sent to the process being examined.
• property Priority
as %Integer [ ReadOnly ];
Priority.
Priority of the process at the O/S level.
• property PrivateGlobalBlockCount
as %Integer [ ReadOnly ];
Number of private global database blocks.
This property contains the # of database blocks currently
allocated to store process private globals.
• property Routine
as %String [ ReadOnly ];
Routine currently executing.
Name of the routine which the process is currently executing.
• property StartupClientIPAddress
as %String [ ReadOnly ];
Startup IP Address of client.
IP address of the client as detected on the TCP channel by the server process.
• property StartupClientNodeName
as %String [ ReadOnly ];
Startup Node Name of client.
IP Node name of the client as detected on the TCP channel by the server process.
• property State
as %String [ ReadOnly ];
State.
Current state of the process as determined by the processes state bits.
The following are all the different states a process can be in. The process may
also have a number of different flags within these states which are appended to
the end of the state name:
LOCK - Executing a Lock command
OPEN - Opening a device
CLOS - Closing a device
USE - Using a device
READ - Read command
WRT - Write command
GET - Executing a $Get on a global
GSET - Setting a global
GKLL - Killing a global
GORD - $Order on a global
GQRY - $Query on a global
GDEF - $Data on a global
ZF - Executing a $ZF command
HANG - Executing a Hang command
JOB - Executing a Job command
EXAM - Executing a variable exam
BRD - Executing a broadcast
SUSP - Process is suspended
INCR - Executing a $Increment
BSET - Set $bitset
BGET - get $bitset
EVT - Waiting on event
RUN - Process is running
Here are the flags which can be appended to the state:
CS - cluster slave job waiting for net answer
NL - Net lock waiting
DT - The dead job has open transaction
S - Suspension requested
GW - Global Wait
NR - Net Read
D - Dead
H - Halting
NH - Netharden
N - Remote network
W - Hibernating
• property Switch10
as %Boolean [ ReadOnly ];
Process Owns switch 10.
This property is set to 1 if the process has set switch 10.
• property UserInfo
as %String(MAXLEN=16);
User defined information.
This is a user-defined property where the process can set any value into it up
to 16 bytes long. The data in it is viewable in JOBEXAM. Note that
the information can only be set into one's own process, not into
another user's process.
• property UserName
as %String [ ReadOnly ];
$Username of process.
$Username of the process as set by the processes authentication method.
• classmethod GetCPUTime()
as %String
Get CPU time used for current process.
Returns two comma-delimited pieces, "system" CPU time and "user" CPU time
(except on VMS where no separate times are available). Time is returned
as milliseconds of CPU time.
• classmethod GetLoginRoutine(ByRef Label As %String, ByRef Routine As %String)
as %Status
Get routine and label specified in process login.
Available only for the current process, you can not query
another process. If a class method is passed on the command line
then 'Label' will be the method name and 'Routine' will be the
class name with a trailing '#' to identify it as a class.
• classmethod KillAllPrivateGlobals()
as %Status
Kill all process private globals for the calling process.
• classmethod NextProcess(Pid As %String, Flag As %Integer = 0)
as %String
Returns the next process pid on the system.
This is like a $order function on processes running on the system, similar to the way
$ZJOB works. It differs from $zjob in one respect though. If the pid passed into
the function has halted before this call, we will still return the next pid on the
system. $zjob would return the first pid on the system in this case. Using $zjob in
this way with lots of processes starting and halting could lead to inaccurate results.
Flag=1 means pass in and return the internal decimal representation of a VMS pid ($zh(pid))
• classmethod Open(Id As %String, concurrency As %Integer = -1, ByRef sc As %Status = 1)
as %ObjectHandle
Open an instance to a process.
This method will open an instance to a process by passing either
a PID or Job number to the method. A Pid can either be directly passed in or
prefaced with a "P". A Job number can be passed in prefaced by a "J".
The following open an instance to a process with a pid = 2078:
s Process=##CLASS(%SYS.ProcessQuery).Open("P2078")
s Process=##CLASS(%SYS.ProcessQuery).Open("2078")
The following will open Job number 23
s Process=##CLASS(%SYS.ProcessQuery).Open("J23")
Parameters:
Id - Pid or Job number to open
Concurrency - Pass -1 or use default
sc (by ref)- Status of the Open
Return values:
On success, the method returns an object handle to the opened process.
On failure, the method returns a null string, and an error in sc.
• classmethod PPGClose(ByRef qHandle As %Binary)
as %Status
• classmethod PPGExecute(ByRef qHandle As %Binary, filter As %String = "*", pid As %Integer = -1, flags As %String = "")
as %Status
• classmethod PPGFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0)
as %Status
• query AllFields()
SQL Query
:
SELECT * FROM %SYS.ProcessQuery
Returns ALL properties for a process
This query performs a Select * on %SYS.ProcessQuery SQL query.
Note that this query uses a $v(-1,$j) mailbox message to
query processes. This causes a lot of overhead, but is necessary in
order to return all fields. Use the JOBEXAM, CONTROLPANEL, or SS
query for less overhead.
This query will change in future versions as field are added or removed.
• query CONTROLPANEL(JobNumber As %Integer = 1, Filter As %String = "")
Selects
Job# As %Integer, Pid As %String, DisplayPID As %String, Username As %String, Device As %String, Nspace As %String, Routine As %String, Commands As %BigInt, Globals As %BigInt, State As %String, Client Name As %String, EXE Name As %String, IP Address As %String, Can Be Examined As %Boolean, Can Be Suspended As %Boolean, Can Be Terminated As %Boolean, Can Receive Broadcast As %Boolean, PrvGblBlkCnt As %Integer
Returns fields for the Management Portal display
Note that this query does not use a $v(-1,$j) mailbox message to
query processes. This avoids unecessary overhead.
This query may change in future versions.
Parameters:
JobNumber - Job number of where to start the query, default = 1 (first job)
Filter - Display processes which contain this filter in the line, "" means display all.
For example, if Filter="READ", this will only display processes which have the word
"READ" in one of the columns.
• query JOBEXAM(JobNumber As %Integer = 1)
Selects
Job# As %Integer, Nspace As %String, Routine As %String, Commands As %BigInt, Globals As %BigInt, State As %String, Pid As %String, Current Device As %String
Returns fields for the JOBEXAM display.
Note that this query does not use a $v(-1,$j) mailbox message to
query processes. This avoids unecessary overhead.
This query may change in future versions.
Parameters:
JobNumber - Job number of where to start the query, default = 1 (first job)
• query ListPids(JobNumber As %Integer = 1)
Selects
Pid As %String
Return PIDS for all processes running on the system.
This query returns the internal pid for each process on the system. This pid can
then be passed directly to the %OpenId() method, or as an argument to an embedded
SQL query which does a SELECT based on the Pid. See the example above for SQL useage.
Parameters:
JobNumber - Job number of where to start the query, default = 1 (first job)
• query PPG(filter As %String)
Selects
key, name As %String, value As %String, blocks As %String
Selects the Process Private Globals for a specified process id.
The 'filter' parameter can be a variable name definition and/or subscript
definition, using * as wildcards. A filter name of '*' will return all
PPG variables for that process id.
As an example of using the wildcards, a filter specification of "CUST*(12*,*COOP*" would
mean return all PPG variables whose name starts with CUST, that have 2 or more subscripts,
the first subscript must start with 12, the second subscript must contain COOP.
• query SS(JobNumber As %Integer = 1)
Selects
Process As %Integer, JobType As %Integer, Device As %String, Namespace As %String, Routine As %String, CPU As %BigInt, Glob As %BigInt, Pr As %Integer, User As %String, Location As %String
Returns fields for the %SS display
Note that this query does not use a $v(-1,$j) mailbox message to
query processes. This avoids unecessary overhead.
This query may change in future versions.
Parameters:
JobNumber - Job number of where to start the query, default = 1 (first job)
• query Top(Sort As %String = "COMMANDS", Number As %Integer = 10)
Selects
Process As %Integer, JobType As %Integer, Device As %String, Namespace As %String, Routine As %String, CPU As %BigInt, Glob As %BigInt, Pr As %Integer, User As %String, Location As %String
Returns the top Processes as measured by the recent activity of either
CommandsExecuted or GlobalReferences
Parameters:
Sort - sort by "COMMANDS" (default) or "GLOREFS"
Number - number of processes to list. Default is 10 and max is 50
Note that the evaluation of the actual 'top' process list is handled by the
Application Monitor (%MONAPP) using the %Monitor.System.Dashboard2 class. This
is 'on' by default and can be managed using the %MONAPPMGR utility. Also, the
counts of CommandsExecuted and GlobalReferences returned are for the latest sample
period and not the total for the life of the process.
• query TopGlobal(Sort As %String = "REFS", Number As %Integer = 20, Seconds As %Integer = 5)
Selects
Process As %Integer, User As %String, Namespace As %String, Routine As %String, JobType As %Integer, GloRefs As %BigInt, PhysReads As %Integer, GloUpdates As %Integer, BlkAlloc As %Integer
Returns the top Processes for certain types of database activity for the next 'n' seconds.
The query can be sorted by one of the following properties: 'GlobalReferences',
'GlobalUpdates', 'GlobalDiskReads', or 'GlobalBlocks'
Parameters:
Sort - sort by "REFS", "UPDATES", "READS", or "BLOCKS". Default is "REFS".
Number - number of processes to list. Default is 20.
Seconds - number of seconds to wait. Default is 5 seconds.
The query will fetch the values for all processes, wait for 'n' seconds, and then
fetch the values again. It will return the list of the 'top' processes for the selected
'Sort' property, and the delta values for all four properties over that time period.
• query VariableByJobNumber(JobNumber, VariableName As %String, Format As %Integer, MaxRows As %Integer)
Selects
Name As %String, Value As %CacheString
Returns the variables of a process
Pass VariableName as a null string to return all variables.
This query requires the %Admin_Manage:Use permission to execute.
Parameters:
JobNumber - Job number to query.
NOTE: You may not use this query to examine your own job.
VariableName - Variable to return, or ""=All
Format - Bit string of how to format the variable data, default = 0 (no formattimg)
Bit 0 - Format the data with $c() and $lb() notation
Bit 1 - Embed bolded cursor sequences around $c() and $lb() notation
MaxRows - Maximum number of rows to return
This query may change in future versions.
• query VariableByPid(Pid As %String, VariableName As %String, Format As %Integer, MaxRows As %Integer)
Selects
Name As %String, Value As %CacheString
Returns the variables of a process, PID is decimal value for all platforms.
Pass VariableName as a null string to return all variables.
This query requires the %Admin_Manage:Use permission to execute.
Parameters:
Pid - Pid of process to query
VariableName - Variable to return, or ""=All
Format - Bit string of how to format the variable data, default = 0 (no formattimg)
Bit 0 - Format the data with $c() and $lb() notation
Bit 1 - Embed bolded cursor sequences around $c() and $lb() notation
MaxRows - Maximum number of rows to return
Note that the fields returned here may change or be removed in future versions.
• index (IdKey on Pid) [IdKey];
Index on Pid field.
Uses NextProcess(Pid) to retrieve next process id.
