F$CONTEXT

From VSI OpenVMS Wiki
Jump to: navigation, search

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.