VMS Help  —  Lexicals  F$CONTEXT
    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.)
Close Help