Specifies selection criteria for use with the F$PID function.
The F$CONTEXT function enables the F$PID function to obtain
information about processes from any node in an OpenVMS Cluster
system.
Format
F$CONTEXT(context-type, context-symbol, selection-item,
selection-value, value-qualifier)
1 – Return Value
A null string ("").
2 – Arguments
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.
NOTE
Do not use the NEQ selection value on a list of items
because it causes the condition to always be true.
For example:
$ EXAMPLE=f$context("PROCESS",CTX,"USERNAME","A*,B*","NEQ")
This equation is parsed as "if the user name is not equal
to A* or the user name is not equal to B*, then return the
process of the users that meet the criteria." Because the
operand is a logical or, the conditions will always be true
(any name will be found to be not equal to A* or B*; ALFRED
will not be equal to B*; BOB will not be equal to A*).
The following table shows valid selection-item keywords for the
PROCESS context type:
Selection Selection Value
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, On Alpha, valid authorized base
GTR, priority (0-63).
LEQ,
LSS,
EQL, NEQ
CANCEL Cancels the selection criteria for
this context.
CURPRIV Keyword ALL, Valid privilege name keyword
ANY, or list of keywords. For more
EQL, NEQ information, see the VSI OpenVMS
Guide to System Security.
GRP Integer GEQ, UIC group number.
GTR,
LEQ,
LSS,
EQL, NEQ
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, Subprocess count for entire job.
GTR,
LEQ,
LSS,
EQL, NEQ
JOBTYPE Keyword EQL, NEQ Valid job-type keyword. Valid
keywords are DETACHED, NETWORK,
BATCH, LOCAL, DIALUP, and REMOTE.
For more information, see the
OpenVMS User's Manual.
MASTER_ String EQL, NEQ PID of master process.
PID
MEM Integer GEQ, UIC member number.
GTR,
LEQ,
LSS,
EQL, NEQ
MODE Keyword EQL, NEQ Valid process mode keyword. Valid
keywords are OTHER, NETWORK,
BATCH, and INTERACTIVE. For more
information, see the OpenVMS
User's Manual.
NODE_ Integer EQL, NEQ Node's cluster ID number.
CSID
NODENAME String EQL, NEQ Node name or list of node names.
The asterisk (*) and the percent
sign (%) wildcard characters are
allowed. The default is your local
node. To request all nodes, use
the value "*".
OWNER String EQL, NEQ PID of immediate parent process.
PRCCNT Integer GEQ, Subprocess count of process.
GTR,
LEQ,
LSS,
EQL, NEQ
PRCNAM String EQL, NEQ Process name or list of process
names. The asterisk (*) and
the percent sign (%) wildcard
characters are allowed.
PRI Integer GEQ, Process priority level number
GTR, (0-63, on Alpha).
LEQ,
LSS,
EQL, NEQ
PRIB Integer GEQ, Base process priority level number
GTR, (0-63, on Alpha).
LEQ,
LSS,
EQL, NEQ
STATE Keyword EQL, NEQ Valid process state keyword.
For more information, see the
description of the $GETJPI service
in the VSI OpenVMS System Services
Reference Manual.
STS Keyword EQL, NEQ Valid process status keyword.
For more information, see the
description of the $GETJPI service
in the VSI OpenVMS System Services
Reference Manual.
TERMINAL String EQL, NEQ Terminal name or list of names.
The asterisk (*) and the percent
sign (%) wildcard characters are
allowed.
UIC String EQL, NEQ User identification code (UIC)
identifier (that is, of the form
"[group,member]").
USERNAME String EQL, NEQ User name or list of user names.
The asterisk (*) and the percent
sign (%) wildcard characters are
allowed.
selection-value
Specifies the value of the selection criteria. For example, to
process all the processes running on node MYVAX, specify "MYVAX"
with the "NODENAME" keyword. For example:
$ X = F$CONTEXT("PROCESS", ctx, "NODENAME", "MYVAX", "EQL")
Values that are lists are valid with some selection items. If you
specify more than one item, separate them with commas (,). The
following example specifies a list of the nodes MYVAX, HERVAX,
and HISVAX:
$ X=F$CONTEXT("PROCESS",ctx,"NODENAME","MYVAX,HERVAX,HISVAX","EQL")
You can use the asterisk (*) and the percent sign (%) wildcard
characters for some values. Using wildcard characters for
selection items is similar to using wildcard characters for file
names.
value-qualifier
Specifies qualifiers for selection values. You must qualify
selection values.
You can qualify a number, for example, by requesting that the
selection be based on one of the following process values:
o LSS - less than the value specified in the call to F$PID
o LEQ - less than or equal to the value specified in the call to
F$PID
o GTR - greater than the value specified in the call to F$PID
o GEQ - greater than or equal to the value specified in the call
to F$PID
o EQL - equal to the value specified in the call to F$PID
o NEQ - not equal to the value specified in the call to F$PID
You can qualify some lists with the ALL, ANY, EQL, or NEQ
keywords. Such lists are usually masks such as the process
privilege mask, which consists of the set of enabled privileges.
o ALL - requires that all items in the list be true for a
process
o ANY - requests that any item in the list be part of the
attributes of a process
o EQL - requires the values to match exactly (that is, values
not specified must not be true of the process)
o NEQ - requires that 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.
3 – Examples
1.$!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. After retrieving each
PID, F$GETJPI is called to return the name of the image running
in the process. Finally, the procedure displays the name of the
image.
In case of error or a Ctrl/Y operation, control is passed to
error and the context is closed if necessary. In this example,
note the check for the symbol type PROCESS_CONTEXT. If the
symbol has this type, selection criteria must be canceled by
a call to F$CONTEXT. If the symbol is not of the type PROCESS_
CONTEXT, either selection criteria have not been set up yet
in F$CONTEXT, or the symbol was used with F$PID until an error
occurred or until the end of the process list was reached.
2.f$context("process",ctx,"prcnam ","symbiont*,mcote*","eql")
f$context("process",ctx,"prcnam ","symbiont*,mcote* ","neq")
f$context("process",ctx,"prcnam ","mcote* ","neq")
f$context("process",ctx,"prcnam ","symbiont*","neq")
This example shows three sets of lexicals showing the
difference between the EQL and the NEQ selection values. The
first lexical function (with EQL) passes back all processes
with symbiont and mcote in the process name. The second and
third lexical functions (with NEQ) are equivalent in that they
both will pass back all processes (processes that do not have
symbiont in the process name, or processes that do not have
mcote in the process name.)