%SYS.ProcessQuery

Class %SYS.ProcessQuery Extends (%Persistent, %SYSTEM.Help) [ Inheritance = right, StorageStrategy = Process, System = 4 ]

This class allows manipulation and display of InterSystems IRIS 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.

Parameters

DEFAULTCONCURRENCY

Parameter DEFAULTCONCURRENCY = 0;

DOMAIN

Parameter DOMAIN = "%Utility";

Set this to the correct domain.

Properties

AppFrameInfo

Property AppFrameInfo As %List [ ReadOnly, SqlColumnNumber = 52 ];

The entire application metadata frame information.

CanBeExamined

Property CanBeExamined As %Boolean [ ReadOnly, SqlColumnNumber = 20 ];

Process can be examined.
Flag checked by JOBEXAM and Management Portal to see if a process can be examined in detail.

CanBeSuspended

Property CanBeSuspended As %Boolean [ ReadOnly, SqlColumnNumber = 21 ];

Process can be suspended.
Flag checked by JOBEXAM and Management Portal to see if a process can be suspended.

CanBeTerminated

Property CanBeTerminated As %Boolean [ ReadOnly, SqlColumnNumber = 22 ];

Process can be terminated.
Flag checked by JOBEXAM and Management Portal to see if a process can be terminated.

CanReceiveBroadcast

Property CanReceiveBroadcast As %Boolean [ ReadOnly, SqlColumnNumber = 23 ];

Process can receive broadcast.
Flag checked by JOBEXAM and Management Portal to see if a process can receive a broadcast. Usually this means they are attached to a terminal.

ClientExecutableName

Property ClientExecutableName As %String [ SqlColumnNumber = 16 ];

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.

ClientIPAddress

Property ClientIPAddress As %String [ SqlColumnNumber = 9 ];

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.

ClientNodeName

Property ClientNodeName As %String [ SqlColumnNumber = 10 ];

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.

CommandsExecuted

Property CommandsExecuted As %BigInt [ ReadOnly, SqlColumnNumber = 38 ];

Number of Commands Executed.
Total number of commands which the process has executed.

CSPSessionID

Property CSPSessionID As %String [ ReadOnly, SqlColumnNumber = 24 ];

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.

CurrentDevice

Property CurrentDevice As %String [ ReadOnly, SqlColumnNumber = 11 ];

Current Device ($i).
Current device that the process has open and is USEing via the USE command.

CurrentLineAndRoutine

Property CurrentLineAndRoutine As %String [ ReadOnly, SqlColumnNumber = 13 ];

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.

CurrentSrcLine

Property CurrentSrcLine As %String(MAXLEN = "") [ ReadOnly, SqlColumnNumber = 14 ];

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. If the routine has been modified compared to the pcode being run then this will point to the current routine source rather than the actual source of the code being executed.

EscalatedRoles

Property EscalatedRoles As %String [ Calculated, SqlColumnNumber = 47 ];

Additional roles granted to the set of login roles.

GlobalReferences

Property GlobalReferences As %BigInt [ ReadOnly, SqlColumnNumber = 5 ];

Number of Global References.
Total number of global references the process has made.

GlobalUpdates

Property GlobalUpdates As %Integer [ ReadOnly, SqlColumnNumber = 40 ];

Number of Global Updates.
Total number of global updates (sets and kills) the process has made.

GlobalDiskReads

Property GlobalDiskReads As %Integer [ ReadOnly, SqlColumnNumber = 41 ];

Number of Physical Database Reads.
Total number of times the process has fetched data from disk.

GlobalBlocks

Property GlobalBlocks As %Integer [ ReadOnly, SqlColumnNumber = 42 ];

Number of Database Block Allocations.
Total number of new database blocks the process has allocated. An indication of database growth.

DataBlockWrites

Property DataBlockWrites As %Integer [ ReadOnly, SqlColumnNumber = 48 ];

Total number of database blocks queued for writing by this process.

InTransaction

Property InTransaction As %Integer [ ReadOnly, SqlColumnNumber = 25 ];

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.

IsGhost

Property IsGhost As %Boolean [ ReadOnly, SqlColumnNumber = 26 ];

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, there 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.

JobNumber

Property JobNumber As %Integer [ ReadOnly, SqlColumnNumber = 27 ];

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.

JobType

Property JobType As %Integer [ ReadOnly, SqlColumnNumber = 28 ];

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"

JournalEntries

Property JournalEntries As %Integer [ ReadOnly, SqlColumnNumber = 43 ];

Number of Journal Entries.
Total number of journaled global updates the process has recorded. An indication of journal file growth.

LastGlobalReference

Property LastGlobalReference As %String(MAXLEN = "") [ ReadOnly, SqlColumnNumber = 15 ];

Last Global Reference.
Last global reference that the process made.
This property requires a mailbox message to be sent to the process being examined.

LicenseUserId

Property LicenseUserId As %String [ ReadOnly, SqlColumnNumber = 29 ];

User Id used for license.
The User ID which took out the license for the process.

LinesExecuted

Property LinesExecuted As %BigInt [ Deprecated, ReadOnly, SqlColumnNumber = 4 ];

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.

Location

Property Location As %String [ ReadOnly, SqlColumnNumber = 30 ];

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),"")

LoginRoles

Property LoginRoles As %String [ ReadOnly, SqlColumnNumber = 46 ];

Login roles.
Roles a process has when it initially logs in.

MemoryAllocated

Property MemoryAllocated As %Integer [ ReadOnly, SqlColumnNumber = 17 ];

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.

MemoryUsed

Property MemoryUsed As %Integer [ ReadOnly, SqlColumnNumber = 18 ];

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.

MemoryPeak

Property MemoryPeak As %Integer [ ReadOnly, SqlColumnNumber = 44 ];

Peak memory allocated in KB.
This property requires a mailbox message to be sent to the process being examined.

NameSpace

Property NameSpace As %String [ ReadOnly, SqlColumnNumber = 2 ];

Namespace process is executing in.

OpenDevices

Property OpenDevices As %String [ ReadOnly, SqlColumnNumber = 19 ];

List of open devices.
List of devices which the process has opened. Returned as a comma separated string.
If any device name in the list contained ",", users won't be able to parse the list. Users should use $LFS(OpenDevices,",",2) to convert the comma separated string to a $List() format string in order to get each device in the list.
This property requires a mailbox message to be sent to the process being examined.

OSUserName

Property OSUserName As %String [ ReadOnly, SqlColumnNumber = 31 ];

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. This field is truncated at 16 characters.

CPUTime

Property CPUTime As %BigInt [ ReadOnly, SqlColumnNumber = 51 ];

Sum of system and user CPU Time in ms for process (no mailbox message)

Pid

Property Pid As %Integer [ ReadOnly, SqlColumnNumber = 32 ];

Process ID.
Process ID ($J) given to the process by the O/S, decimal form on all platforms.

PrivateGlobalBlockCount

Property PrivateGlobalBlockCount As %Integer [ ReadOnly, SqlColumnNumber = 37 ];

Number of private global database blocks.
This property contains the # of database blocks currently allocated to store process private globals.

PrivateGlobalReferences

Property PrivateGlobalReferences As %BigInt [ ReadOnly, SqlColumnNumber = 49 ];

Number of Process Private Global References.
Total number of private global references the process has made.

PrivateGlobalUpdates

Property PrivateGlobalUpdates As %BigInt [ ReadOnly, SqlColumnNumber = 50 ];

Number of Process Private Global Updates.
Total number of private global updates (sets and kills) the process has made.

PidExternal

Property PidExternal As %String [ ReadOnly, SqlColumnNumber = 7 ];

Index on Pid field.
Uses NextProcess(Pid) to retrieve next process id. External Process PID. Decimal value for Windows, Unix and Mac, hex for VMS.

PrincipalDevice

Property PrincipalDevice As %String [ ReadOnly, SqlColumnNumber = 39 ];

Principal Device ($P).
This property requires a mailbox message to be sent to the process being examined.

Priority

Property Priority As %Integer [ ReadOnly, SqlColumnNumber = 33 ];

Priority.
Priority of the process at the O/S level.

Roles

Property Roles As %String [ ReadOnly, SqlColumnNumber = 45 ];

$Roles.
Roles a process currently has.

Routine

Property Routine As %String [ ReadOnly, SqlColumnNumber = 3 ];

Routine currently executing.
Name of the routine which the process is currently executing.

StartupClientIPAddress

Property StartupClientIPAddress As %String [ ReadOnly, SqlColumnNumber = 34 ];

Startup IP Address of client.
IP address of the client as detected on the TCP channel by the server process.

StartupClientNodeName

Property StartupClientNodeName As %String [ ReadOnly, SqlColumnNumber = 35 ];

Startup Node Name of client.
IP Node name of the client as detected on the TCP channel by the server process.

State

Property State As %String [ ReadOnly, SqlColumnNumber = 6 ];

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 - Global Set $Bit
BGET - Global $Bit
EVT - Waiting on event
SLCT - $System.Socket wait
SEM - $System.Semaphore wait
IPQ - Inter-process queue wait
DEQ - Dequeue wait (currently unusued)
VSET - Global Set vector element
VKLL - Global Kill vector element
RUN - Process is running in none of the aformentioned states

The following flags can be appended to the state:

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

Switch10

Property Switch10 As %Boolean [ ReadOnly, SqlColumnNumber = 36 ];

Process Owns switch 10.
This property is set to 1 if the process has set switch 10.

UserInfo

Property UserInfo As %String(MAXLEN = 16) [ SqlColumnNumber = 12 ];

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.

UserName

Property UserName As %String(MAXLEN = 160) [ ReadOnly, SqlColumnNumber = 8 ];

$Username of process.
$Username of the process as set by the processes authentication method.

Methods

ClientExecutableNameSet

Method ClientExecutableNameSet(Val) As %Status [ Internal ]

ClientIPAddressSet

Method ClientIPAddressSet(Val) As %Status [ Internal ]

ClientNodeNameSet

Method ClientNodeNameSet(Val) As %Status [ Internal ]

EscalatedRolesGet

Method EscalatedRolesGet() [ Internal ]

UserInfoSet

Method UserInfoSet(Val) As %Status [ Internal ]

AllowToOpen

ClassMethod AllowToOpen(Pid) As %Status [ Internal ]

Check to see if permissions allow us to open the process.
The %SYS.ProcessQuery class is available to all users in all namespaces. It is intended that any process can open an instance of this class and examine their own properties, but not any other process on the system, unless they own the %Admin_Manage:Use resource, or are in the %SYS namespace.

GetCurrentLineAndRoutine

ClassMethod GetCurrentLineAndRoutine(JobNumber) As %String [ Internal ]

Get the current line and routine for a process.
Parameters:
JobNumber - Job number of the process
Return Value:
On success, the method will return the current line and routine of the selected process in +number^routine format. on failure, or if unavailable, it will return ""

GetCurrentSrcLine

ClassMethod GetCurrentSrcLine(JobNumber) As %String [ Internal ]

Get the current source line for the process.
Parameters:
JobNumber - Job number of the process
Return Value:
On success, the method will return the current source line of the selected process.
On failure, or if source unavailable, it will return ""

GetLastGlobalReference

ClassMethod GetLastGlobalReference(JobNumber) As %String [ Internal ]

Get the last global reference for the process.
Parameters:
JobNumber - Job number of the process
Return Value:
On success, the method will return the last global reference the selected process.
On failure, it will return ""

GetView

ClassMethod GetView(Pid) As %String [ Internal ]

Query the process for some properties.
Parameters:
Pid - Pid (decimal) of the process
Return Value:
On success, the method will return the values of $v(-1,Pid)
On failure, or if source unavailable, it will return all fields as 0.

GetViewList

ClassMethod GetViewList(Pid) As %List [ Internal ]

Query the process for some properties.
Parameters:
Pid - Pid (decimal) of the process
Return Value:
On success, the method will return the $LIST from $v(-1,Pid,2)
On failure, or if source unavailable, it will return all fields as 0.

GetLoginRoutine

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.

GetCPUTime

ClassMethod GetCPUTime(pid As %Integer) As %String

Get CPU time used for current process (without method arguments)
or CPU time for the process specified by pid (with method arguments)

Parameters:
pid (optional) - JobNumber (integer +$J)
of the IRIS process you want to get information about

Return Value:
Returns two comma-delimited pieces, "system" CPU time and "user" CPU time Time is returned as milliseconds of CPU time.
0,0 is returned if the specified pid does not exist.

GetOSUsername

ClassMethod GetOSUsername() As %String

This method returns the OSUsername of the process as returned by the operating system. This method differs from the OSUsername property in that it is the actual username assigned to the process by the operating system.

GetAppFrameInfo

ClassMethod GetAppFrameInfo(pid As %Integer) As %List

Return the entire application metadata frame information for the current process or the specified process. Parameters:
Pid - Pid (decimal) of the process
Return Value:
The application frame information in $LIST form.

KillAllPrivateGlobals

ClassMethod KillAllPrivateGlobals() As %Status

Kill all process private globals for the calling process.

GetVariableList

ClassMethod GetVariableList(InternalStack As %Integer = 0, ByRef ListVar)

Get a list of all variables defined at the specified internal execution stack level. If no stack level is given, the current stack level is the default.
The list is returned as nodes of the listvar argument.
listvar will be set to the number of sublists.
listvar(1) will be set to the first sublist, listvar(2) to the second, etc.
Each sublist is a $List of variable entries.
Each variable entry is a $ListBuild(name,$Data(name)).
Private variables are identified with a tilde (~) as the first character in the name.
The names are not sorted, except private variables follow the public variables.
The return value of the method is the total number of variables in the sublists.

VariableValue

ClassMethod VariableValue(Variable As %String, InternalStack As %Integer = 0)

Get the value of a variable at the specified internal execution stack level. If no stack level is given, the current stack level is the default.
The variable reference may include subscripts.
To get the value of a private variable, add a tilde in front of the name, as in "~info".
If the variable is undefined an error will be thrown.

VariableDataFlags

ClassMethod VariableDataFlags(Variable As %String, InternalStack As %Integer = 0) As %Integer

Get the $Data() value of a variable at the specified internal execution stack level. If no stack level is given, the current stack level is the default.
The variable reference may include subscripts.
To get the value for a private variable, add a tilde in front of the name, as in "~info".

VariableQuery

ClassMethod VariableQuery(Variable As %String, InternalStack As %Integer = 0) As %String

Perform a $Query() operation on a variable reference at the specified internal execution stack level. If no stack level is given, the current stack level is the default.
The variable reference may include subscripts.
To operate on a private variable, add a tilde in front of the name, as in "~info".

GetInternalStackLevel

ClassMethod GetInternalStackLevel(stack As %Integer = 0, ByRef newlevels) As %Integer

Convert a $STACK value to the corresponding internal stack level that can be used for the VariableList query and Variable methods that have an InternalStack argument.
The default for stack is the current $STACK value.
When there are NEW commands in a level, each NEW command creates a new internal stack level without increasing $STACK. This method returns the highest internal stack level for the given $STACK. If there are other internal levels created by NEW commands within the given $STACK, they are returned in the newlevels argument as a $LIST of values. There may be different variables defined at each of those levels and the same variable may have different values at each level.

NextProcess

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))

Open

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.

StateLogicalToDisplay

ClassMethod StateLogicalToDisplay(State) As %String [ Internal ]

Translates an internal state flag to an external display.
See the State property for what can be returned here.

DecodeState

ClassMethod DecodeState(Code As %String, DaemonCode As %String = "", ResNameList As %List = "") As %List [ Internal ]

Takes an internal state code from $zu(61,4) and returns a $list with the following list elements.

• 1 - the base process State without any letter flags appended
• 2 - the letter flags to append for State
• 3 - an internal "wait reason" when the process is blocked in the IRIS kernel
• 4 - an internal psuedo-trace of calls within the IRIS kernel
• 5 - boolean true/false if the process state is one that is expected to use CPU The wait reason can take the following values, and is subject to change. Some but not all of these correspond to the "W" letter flag, and not all cases of the "W" have an internal reason reflected here. For example, waiting on a LOCK usually has a "W" but in not reflected here, as it is an expected application wait rather than a wait within the IRIS kernel.
• diskio: waiting for database physical block read
• inusebufwt: waiting due to block collision (^BLKCOL utility may help identify application cause)
• expand: waiting for database expansion
• ecpwait: waiting for an answer from the ECP server
• jrniowait: no space in journal buffer, waiting for journal I/O
• jrnsyncblk: waiting for journal data to be committed
• jrnlckwait: waiting to access journal buffer
• mirrorwait: waiting for active backup mirror member
• mirrortrouble: blocked due to mirror trouble state
• globwait: waiting because of an internal condition blocking global updates
• aiowait: waiting for asynchronous disk I/O to complete
• wdqwait: waiting for a write cycle to complete
  freebuf: global buffers are completely exhausted and waiting for database writes gfownwait: access to database is blocked resenqXYZ: waiting on an internal resource XYZ

%OnOpen

Method %OnOpen() As %Status [ Internal, Private ]

This callback method is invoked by the %Open method to provide notification that the object specified by oid is being opened.

If this method returns an error then the object will not be opened.

%SQLAcquireLock

ClassMethod %SQLAcquireLock(%rowid As %String, s As %Boolean = 0, ByRef unlockref As %String) [ Internal, ProcedureBlock = 0, ServerOnly = 1 ]

%SQLAcquireTableLock

ClassMethod %SQLAcquireTableLock(s As %Boolean = 0, ByRef SQLCODE As %Integer, to As %Integer = "") [ Internal, ProcedureBlock = 0, ServerOnly = 1 ]

%SQLReleaseLock

ClassMethod %SQLReleaseLock(%rowid As %String, s As %Boolean = 0, i As %Boolean = 0) [ Internal, ProcedureBlock = 0, ServerOnly = 1 ]

%SQLReleaseTableLock

ClassMethod %SQLReleaseTableLock(s As %Boolean = 0, i As %Boolean = 0) [ Internal, ProcedureBlock = 0, ServerOnly = 1 ]

CONTROLPANELExecute

ClassMethod CONTROLPANELExecute(ByRef qHandle As %Binary, JobNumber As %Integer = 1, Filter As %String = "") As %Status [ Internal ]

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. 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 unnecessary 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.

CONTROLPANELFetch

ClassMethod CONTROLPANELFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

CONTROLPANELClose

ClassMethod CONTROLPANELClose(ByRef qHandle As %Binary) As %Status [ Internal ]

JOBEXAMExecute

ClassMethod JOBEXAMExecute(ByRef qHandle As %Binary, JobNumber As %Integer = 1) As %Status [ Internal ]

Returns fields for the JOBEXAM display.
Note that this query does not use a $v(-1,$j) mailbox message to query processes. This avoids unnecessary overhead. This query may change in future versions.
Parameters:
JobNumber - Job number of where to start the query, default = 1 (first job)

JOBEXAMFetch

ClassMethod JOBEXAMFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

JOBEXAMClose

ClassMethod JOBEXAMClose(ByRef qHandle As %Binary) As %Status [ Internal ]

ListPidsExecute

ClassMethod ListPidsExecute(ByRef qHandle As %Binary, JobNumber As %Integer = 1) As %Status [ Internal ]

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 usage.
Parameters:
JobNumber - Job number of where to start the query, default = 1 (first job)

ListPidsFetch

ClassMethod ListPidsFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

ListPidsClose

ClassMethod ListPidsClose(ByRef qHandle As %Binary) As %Status [ Internal ]

SSExecute

ClassMethod SSExecute(ByRef qHandle As %Binary, JobNumber As %Integer = 1) As %Status [ Internal ]

Returns fields for the %SS display.
Note that this query does not use a $v(-1,$j) mailbox message to query processes. This avoids unnecessary overhead. This query may change in future versions.
Parameters:
JobNumber - Job number of where to start the query, default = 1 (first job)

SSFetch

ClassMethod SSFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ CodeMode = call, Internal ]

SSClose

ClassMethod SSClose(ByRef qHandle As %Binary) As %Status [ Internal ]

VariableByJobNumberExecute

ClassMethod VariableByJobNumberExecute(ByRef qHandle As %Binary, JobNumber As %Integer = 1, Variable As %String = "", Format As %Integer = 0, MaxRows As %Integer = 9999999, Filter As %String = "") As %Status [ Internal ]

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 formatting)
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
Filter - Filters the data returned (case insensitive). If the variable contains the filter, then return it. ""=no filter
This query may change in future versions.

VariableByJobNumberFetch

ClassMethod VariableByJobNumberFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

VariableByJobNumberClose

ClassMethod VariableByJobNumberClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = VariableByJobNumberExecute ]

VariableByPidExecute

ClassMethod VariableByPidExecute(ByRef qHandle As %Binary, Pid As %String, Variable As %String = "", Format As %Integer = 0, MaxRows As %Integer = 9999999, Filter As %String = "") As %Status [ Internal ]

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 formatting)
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
Filter - Filters the data returned (case insensitive). If the variable contains the filter, then return it. ""=no filter
Note that the fields returned here may change or be removed in future versions.

VariableByPidFetch

ClassMethod VariableByPidFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

VariableByPidClose

ClassMethod VariableByPidClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = VariableByPidExecute ]

VariableListExecute

ClassMethod VariableListExecute(ByRef qHandle As %Binary, InternalStack As %Integer = 0, Type As %Integer = 0) As %Status [ Internal ]

Returns the variables that are visible to the current process at the current or specified execution internal stack level. 'DataFlags' is the $DATA() value of the variable.

Parameters:
'InternalStack' is a value less than or equal to the current stack level, as reported by the %STACK utility. If no stack level is given, the current stack level is the default.
'Type' is the kind of query to run. The default is 0 which returns a sorted list of variables. Type 1 returns an unsorted list and may be quicker because it uses no global variables.

The query returns only plain variable names without subscripts. Private variables are distinguished from public variables by a tilde prefix. Thus the private variable 'info' will be presented as '~info'. All private variables are returned after all public variables.

VariableListFetch

ClassMethod VariableListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

VariableListClose

ClassMethod VariableListClose(ByRef qHandle As %Binary) As %Status [ Internal ]

PPGExecute

ClassMethod PPGExecute(ByRef qHandle As %Binary, filter As %String = "*", pid As %Integer = -1, options As %String = "") As %Status [ Internal ]

Select information about Process Private Globals.

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.

pid can be any valid process id, or -1 for the caller's process.

options can be one or more of the following characters
"N" Do not return subscripts of a PPG, just return the root name
"B" Return the number of blocks used by the PPG (needs the "N" option)
"b" Returns the number of bytes used by the PPG (needs the "N" option)

Example
set rs=##class(%ResultSet).%New("%SYS.ProcessQuery:PPG")
do rs.Execute("*",$J,"NB")
for {
q:'rs.Next()
w "PPG name "_rs.GetData(1)_" is using "_rs.GetData(3)_" disc blocks",!
}
This query requires the %Admin_Manage:Use permission to execute.

PPGClose

ClassMethod PPGClose(ByRef qHandle As %Binary) As %Status [ Internal ]

PPGFetch

ClassMethod PPGFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

PPGInfo

ClassMethod PPGInfo(pid As %Integer) As %String [ Internal ]

TopExecute

ClassMethod TopExecute(ByRef qHandle As %Binary, Sort, Number) As %Status [ Internal ]

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.

TopFetch

ClassMethod TopFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

TopClose

ClassMethod TopClose(ByRef qHandle As %Binary) As %Status [ Internal ]

TopGlobalExecute

ClassMethod TopGlobalExecute(ByRef qHandle As %Binary, Sort, Number, Seconds) As %Status [ Internal ]

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', 'GlobalBlocks', or 'PrivateGlobalBlockCount'.

Parameters:
Sort - sort by "REFS", "UPDATES", "READS", "BLOCKS", "PPG". 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 properties over that time period. Note that PrivateGlobalBlockCount is returned as the total number used, not a delta.

TopGlobalFetch

ClassMethod TopGlobalFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

TopGlobalClose

ClassMethod TopGlobalClose(ByRef qHandle As %Binary) As %Status [ Internal ]

EnableJournalInt

ClassMethod EnableJournalInt() As %Status [ Internal ]

Enable journaling within the process, with temporarily elevated role

DisableJournalInt

ClassMethod DisableJournalInt() As %Boolean [ Internal ]

Disable journaling within the process, with temporarily elevated role.
Returns 1 if journaling was active prior to this; 0 otherwise (i.e., no action taken)

ExamStackByPid

ClassMethod ExamStackByPid(Pid As %String, GetVariables As %Boolean = 0, Timeout As %Integer = 10) As %Status

Retrieve a snapshot of the execution stack and variables for a process in the same format as JOBEXAM.

Parameters:

Pid - Process ID ($J) of the process to examine

GetVariables - Flag specifies variable and/or object info should be returned

• 0 - do not dump local variable or object info
• 1 - dump all local variable info
• 2 - dump all active oref info
• 3 - dump local variable and object info

Timeout - How long to wait for the process to respond to the request

Return Value:
On success, the method will return an index of the ^mtemp global (greater than zero). If an error occurs a status code is returned.

Note that, like JOBEXAM, the request will time out if the process is not executing commands.

The data in the ^mtemp node can be displayed by calling Show^%STACK(index). It is the responsibility of the caller to Kill ^mtemp(index) when finished with the data.

The data is returned in these nodes of the ^mtemp(index) global:
("*STACK") = the number of stack levels
("*STACK",0,"V",SpecialVar) = the values of special variables such as $S and $ZE
("*STACK",level,"L") = the text line for this level, as displayed by %STACK or JOBEXAM
("*STACK",level,"S") = the source line for this level, with a tilde inserted in front of the current command
("*STACK",level,"I") = the internal data for this level

If variables are requested:
("*LEVEL",level,variable) = the base level of a 'variable' that is visible at this 'level'
("*NAMES",variable,base,level) - this is the same information as *LEVEL in a different format
("*STACK",base,"V",variable) - top of subtree containing information of 'variable' defined at 'base' level
The function call $$VGetn^%STACK(index,l,v) returns information about the value of variable 'v' at stack level 'l'. If the variable is a private local variable then argument 'v' must be string starting with a tilde character, "~", followed by the variable identifier text. The variable 'v' can include a parenthesized list of subscript literals. Note that lookup of a subscripted local variable requires that the examined process and the examining process are using the same local collation. It returns "" if the variable 'v' is undefined at that stack level; otherwise it returns $LISTBUILD(flags,value) where 'value' is the value of the variable and 'flags' is a sequence of flag letters. If flags["O" then the variable contains an oref and 'value' is the oref string representation.

If objects are requested:
("*CLASS",class) = number of active local objects in Class 'class'
("*CLASS",class,oref) = "" is defined if 'oref' value is a local object of class 'class'. The function call $$OGetn^%STACK(index,oref,property) returns $LISTBUILD(flags,value) if the object 'oref' has a property name 'property' and it returns "" if either the oref or the property does not exist. If the property is multidimensional then the property name can include a parenthesized list of subscript literals. Note that lookup of a subscripted multidim property requires that the examined process and the examining process are using the same local collation. The 'value' of the returned $LIST is usually the value of the property (see 'flags'.) The 'flags' of the returned $LIST is a sequence of flag letters.

• An empty flags string means 'value' is an ordinary ObjectScript value.
• The flag "U" means the property is not defined, which may indicate an internal error.
• The flag "J" means the object is a %DynamicAbstractObject and 'value' contains the oref.%FromJSON() JSON string as the result of any attempt to access a property.
• The flag "O" means 'value' is the string representation of an object reference.
• The flags "G" or "C" mean the property has a propertyGet method or is Calculated. Evaluating such a property can cause unwanted side effects so the returned 'value' is the internal value of the i%property name which might be undefined or might not contain useful information.

GetOpenDevices

ClassMethod GetOpenDevices(Pid As %Integer) As %List

Get a $LIST of devices that a process has open.

Parameters:
Pid - Process ID ($J) of the process to examine

Return Value:
On success, the method will return a $LIST of devices that are currently open by the process. The principal device is the first item in the list. The current device has an asterisk appended to the name.
If an error occurs an empty string is returned.