Darya.zelenina: Created page with "'''F$CONTEXT()''' is a lexical function that specifies selection criteria for use with the F$PID() function which can obtain information about proces..."

2019-04-05T10:04:27Z

Created page with "'''F$CONTEXT()''' is a lexical function that specifies selection criteria for use with the F$PID() function which can obtain information about proces..."

New page

'''F$CONTEXT()''' is a [[Lexical functions|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.

{| class="wikitable"
!colspan="col"; | Item
!colspan="col"; | Value
!colspan="col"; | Qualifiers
!colspan="col"; | 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 [[Privileges|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|job]].
|-
| JOBTYPE
| Keyword
| EQL,NEQ
| Valid [[Job|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
| [[Identifiers|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:

{| class="wikitable"
! colspan="col"; | Qualifier
! colspan="col"; | 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
|-
! colspan="2;" | 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=
<nowiki>
$!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
</nowiki>
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.

[[Category:Lexical Functions]]

F$CONTEXT - Revision history

Darya.zelenina: Created page with "'''F$CONTEXT()''' is a lexical function that specifies selection criteria for use with the F$PID() function which can obtain information about proces..."