F$CONTEXT

F$CONTEXT() is a lexical function that specifies selection criteria for use with the F$PID() function which can obtain information about processes from any node in an OpenVMS Cluster.

Syntax

F$CONTEXT(context-type, context-symbol, selection-item, selection-value, value-qualifier)

context-type:

Specifies the type of context to be built. At present, the only context type available is PROCESS, which is used in constructing selection criteria for F$PID. Privileges are not required to see processes for the same UIC. To see processes for another UIC in the same UIC group, you need the GROUP privilege, and to see processes systemwide, you need the WORLD privilege.

context-symbol:

Specifies a symbol that DCL uses to refer to the context memory being constructed by the F$CONTEXT function. The function F$PID uses this context symbol to process the appropriate list of process identification (PID) numbers. Specify the context symbol by using a symbol. The first time you use the F$CONTEXT function in a command procedure, use a symbol that is either undefined or equated to the null string. The symbol created will be a local symbol of type "PROCESS_CONTEXT". When the context is no longer valid-that is, when all PIDs have been retrieved by calls to the F$PID function or an error occurs during one of these calls-the symbol no longer has a type of "PROCESS_CONTEXT". Then you can use the F$TYPE function in the command procedure to find out if it is necessary to cancel the context. After setting up the selection criteria, use this context symbol when calling F$PID.

selection-item:

Specifies a keyword that tells F$CONTEXT which selection criterion to use. Use only one selection-item keyword per call to F$CONTEXT.

Item	Value	Qualifiers	Comments
ACCOUNT	String	EQL,NEQ	Valid account name or list of names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
AUTHPRI	Integer	GEQ,GTR,LEQ,LSS,EQL,NEW	On Alpha, valid authorized base priority (0-63).
CANCEL			Cancels the selection criteria for this context.
CURPRIV	Keyword	ALL,ANY,EQL,NEQ	Valid privilege name keyword or list of keywords.
GRP	Integer	GEQ,GTR,LEQ,LSS,EQL,NEQ	UIC group number
HW_MODEL	Integer	EQL,NEQ	Valid hardware model number
HW_NAME	String	EQL,NEQ	Valid hardware name or a list of keywords. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
JOBPRCCNT	Integer	GEQ,GTR,LEQ,LSS,EQL,NEQ	Subprocess count for entire job.
JOBTYPE	Keyword	EQL,NEQ	Valid job-type keyword. Valid keywords are DETACHED, NETWORK, BATCH, LOCAL, DIALUP, and REMOTE.
MASTER_PID	String	EQL,NEQ	PID of master process.
MEM	Integer	GEQ,GTR,LEQ,LSS,EQL,NEQ	UIC member number.
MODE	Keyword	EQL,NEQ	Valid process mode keyword. Valid keywords are OTHER, NETWORK, BATCH, and INTERACTIVE.
NODE_CSID	Integer	EQL,NEQ	Node's cluster ID number
NODENAME	String	EQL,NEQ	Node name or list of node names.
OWNER	String	EQL,NEQ	PID of immediate parent process.
PRCCNT	Integer	GEQ,GTR,LEQ,LSS,EQL,NEQ	Subprocess count of process.
PRCNAM	String	EQL,NEQ	Process name or list of process names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
PRI	Integer	GEQ,GTR,LEQ,LSS,EQL,NEQ	Process priority level number (0-63, on Alpha)
PRIB	Integer	GEQ,GTR,LEQ,LSS,EQL,NEQ	Base process priority level number (0-63, on Alpha)
STATE	Keyword	EQL,NEQ	Valid process state keyword. See F$GETJPI() for details.
STS	Keyword	EQL,NEQ	Valid process status keyword. See F$GETJPI() for details.
TERMINAL	String	EQL,NEQ	Terminal name or list of names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
UIC	String	EQL,NEQ	UIC identifier
USERNAME	String	EQL,NEQ	User name or list of user names

selection-value:

Specifies the value of the selection criteria in the table above.

value-qualifier:

Specifies qualifiers for selection values:

Qualifier	Description
LSS	less than the selection-value
LEQ	less than or equal to the selection-value
GTR	greater than the selection-value
GEQ	greater than or equal to the selection-value
EQL	equal to the selection-value
NEQ	not equal to the selection-value
Mask value qualifiers
ALL	all items in the list must be true for the process
ANY	any items in the list must be true for the process
EQL	the values must match exactly
NEQ	the value must not match

When using multiple selection values with a particular selection qualifier, a match on any one of the selection criteria is considered valid (as if an OR operand was in place); the selection values are not cumulative criteria (as if an AND operand was in place).

The difference between ALL and EQL is that the values specified with ALL must exist, but other unspecified values can exist also. EQL requires that all values specified must exist, and all others may not. For example, to request those processes whose current privileges include TMPMBX (temporary mailbox) and OPER (operator), but may include other privileges, specify the ALL keyword. To request those processes whose current privileges are TMPMBX and OPER exclusively, specify the EQL keyword.

Examples

$!Establish an error and Ctrl/Y handler
$!
$ ON ERROR THEN GOTO error
$ ON CONTROL_Y THEN GOTO error
$!
$ ctx = ""
$ temp = F$CONTEXT ("PROCESS", ctx, "NODENAME", "*","EQL")
$ temp = F$CONTEXT ("PROCESS", ctx, "USERNAME", "M*,SYSTEM","EQL")
$ temp = F$CONTEXT ("PROCESS", ctx, "CURPRIV", "SYSPRV,OPER", "ALL")
$!
$!Loop over all processes that meet the selection criteria.
$!Print the PID and the name of the image for each process.
$!
$loop:
$ pid = F$PID(ctx)
$ IF pid .EQS. ""
$ THEN
$     GOTO endloop
$ ELSE
$     image = F$GETJPI(pid,"IMAGNAME")
$     SHOW SYMBOL pid
$     WRITE SYS$OUTPUT image
$     GOTO loop
$ ENDIF
$!The loop over the processes has ended.
$!
$endloop:
$!
$ EXIT
$!
$!Error handler. Clean up the context's memory with
$!the CANCEL selection item keyword.
$!
$error:
$ IF F$TYPE(ctx) .eqs. "PROCESS_CONTEXT" THEN -
_$ temp = F$CONTEXT ("PROCESS", ctx, "CANCEL")
$!
$ EXIT
 

In this example, F$CONTEXT is called three times to set up selection criteria:

• The first call requests that the search take place on all nodes in the cluster.
• The second call requests that only the processes whose user name either starts with an "M" or is "SYSTEM" be processed.
• The third call restricts the selection to those processes whose current privileges include both SYSPRV (system privilege) and OPER (operator) and can have other privileges set.

The command lines between the labels "loop" and "endloop" continually call F$PID to obtain the processes that meet the criteria set up in the F$CONTEXT calls.