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)

Return Value

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 Item	Selection Value	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, NEQ	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. For more information, see the HP OpenVMS Guide to System Security.
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. For more information, see the OpenVMS User's Manual.
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. For more information, see the OpenVMS User's Manual.
NODE_CSID	Integer	EQL, NEQ	Node's cluster ID number.
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, 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. For more information, see the description of the $GETJPI service in the HP 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 HP 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:

• LSS --- less than the value specified in the call to F$PID
• LEQ --- less than or equal to the value specified in the call to F$PID
• GTR --- greater than the value specified in the call to F$PID
• GEQ --- greater than or equal to the value specified in the call to F$PID
• EQL --- equal to the value specified in the call to F$PID
• 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.

• ALL --- requires that all items in the list be true for a process
• ANY --- requests that any item in the list be part of the attributes of a process
• EQL --- requires the values to match exactly (that is, values not specified must not be true of the process)
• 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.

Description

Use the F$CONTEXT function to set up selection criteria for the F$PID function.

The F$CONTEXT function is called as many times as necessary to produce the criteria needed; however, each call can specify only one selection item. Lists of item values are allowed, where appropriate, and more than one context can be operated upon at a time.

After establishing the selection criteria with appropriate calls to F$CONTEXT, F$PID is called repeatedly to return all the process identification (PID) numbers that meet the criteria specified in the F$CONTEXT function. When there are no more such processes, the F$PID function returns a null string.

After the F$PID function is called, the context symbol is considered "frozen"; F$CONTEXT cannot be called again with the same context symbol until the associated context selection criteria have been deleted. If you attempt to set up additional selection criteria with the same context symbol, an error message is displayed; however, the context and selection criteria are not affected and calls to the F$PID function can continue.

The F$CONTEXT function uses process memory to store the selection criteria. This memory is deleted under two circumstances. Memory is deleted when the F$PID function is called and a null string ("") is returned---that is, when all processes that meet the selection criteria have been returned. Memory also is deleted if the CANCEL selection-item keyword is used in a call to F$CONTEXT with an established context. This type of call is appropriate for a Ctrl/Y operation or another condition handling routine.

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

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