HELPLIB.HLB  —  Lexicals
    A set of functions that return information about character
    strings and attributes of the current process.

1  –  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.1  –  Return Value

    A null string ("").

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

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

2  –  F$CSID

    Returns an identification number from an OpenVMS Cluster system
    and updates the context symbol to point to the current position
    in the system's cluster node list.

    Format

      F$CSID(context-symbol)

2.1  –  Return Value

    A character string containing the system cluster identification
    number in the system's list of clustered nodes. If the current
    system is not a member of a cluster, the first return value is
    null. After the last system cluster identification number is
    returned, the F$CSID function returns a null string ("").

2.2  –  Arguments

 context-symbol

    Specifies a symbol that DCL uses to store a pointer into the
    system's list of clustered nodes. The F$CSID function uses this
    pointer to return a cluster identification number.

    Specify the context-symbol argument by using a symbol. The first
    time you use the F$CSID function, use a symbol that is either
    undefined or equated to the null string.

    If the context-symbol argument is undefined or equated to a null
    string, the F$CSID function returns the cluster identification
    number of the first system in the system's cluster node list.
    Subsequent calls to the F$CSID function will return the cluster
    identification number of the rest of the nodes in the cluster.

2.3  –  Example

  $ IF F$GETSYI("CLUSTER_MEMBER") .EQS. "FALSE" THEN GOTO NOT_CLUSTER
  $ CONTEXT = ""
  $START:
  $   id = F$CSID (CONTEXT)
  $   IF id .EQS. "" THEN EXIT
  $   nodename = F$GETSYI ("NODENAME",,id)
  $   WRITE SYS$OUTPUT nodename
  $   GOTO start
  $NOT_CLUSTER:
  $ WRITE SYS$OUTPUT "Not a member of a cluster."
  $ EXIT

      This command procedure uses the F$CSID function to display
      a list of cluster system names. The assignment statement
      declares the symbol CONTEXT, which is used as the context-
      symbol argument for the F$CSID function. Because CONTEXT is
      equated to a null string, the F$CSID function will return the
      first cluster identification number in the cluster node list.

      If the F$CSID function returns a null value, then the command
      procedure either is at the end of the list, or is attempting
      this operation on a nonclustered node. The call to F$GETSYI
      checks whether the current node is a member of a cluster. The
      command procedure will exit on this condition.

      If the F$CSID function does not return a null value, then the
      command procedure uses the identification number as the third
      argument to the F$GETSYI function to obtain the name of the
      system. The name is then displayed using the WRITE command.

3  –  F$CUNITS

    Converts a number from one specified unit of measure to another.

    Format

      F$CUNITS(number [,from-units, to-units])

3.1  –  Return Value

    A number representing the converted value.

3.2  –  Arguments

 number

    Specifies a 32-bit (or smaller) number to convert.

 from-units

    Specifies the unit of measure from which to convert. When only
    first argument is present, the default option for this field is
    BLOCKS. Supported options for this field are BLOCKS, B, KB, MB,
    GB, and TB.

 to-units

    Specifies the unit of measure to which to convert. When only
    first argument is present, or the second argument is BLOCKS,
    the default option for this field is BYTES and the result gets
    rounded off to appropriate "to-unit". Supported options for this
    field are BLOCKS, BYTES, B, KB, MB, GB, and TB. Keyword "BYTES"
    is supported only for BLOCKS to BYTES conversion.

3.3  –  Example

  $ WRITE SYS$OUTPUT F$CUNITS(1024)
  512KB

  $ WRITE SYS$OUTPUT F$CUNITS(1024, "BLOCKS")
  512KB

  $ WRITE SYS$OUTPUT F$CUNITS(1024, "BLOCKS", "BYTES")
  512KB

      The above examples convert 1024 blocks to the equivalent in
      bytes and auto scale the output. The result is 512 KB.

  $ WRITE SYS$OUTPUT F$CUNITS(1024, "BLOCKS", "B")
  524288B

      This example converts 1024 Blocks to non scaled bytes value.
      The result is 524288 Bytes.

  $ WRITE SYS$OUTPUT F$CUNITS (512,"B", "BLOCKS")
  1BLOCKS

      This example converts 512 Bytes to the equivalent in Blocks.
      The result is 1 Blocks.

  $ WRITE SYS$OUTPUT F$CUNITS (10,"KB","B")
  10240B

      This example converts 10 KB to the equivalent in Bytes. The
      result is 10240 Bytes.

  $  WRITE SYS$OUTPUT F$CUNITS (1024,"MB","GB")
  1GB

      This example converts 1024 MB to the equivalent in GB. The
      result is 1 GB.

  $ WRITE SYS$OUTPUT F$CUNITS(512, "MB", "BLOCKS")
  1048576BLOCKS

      This example converts 512 MB to the equivalent in BLOCKS. The
      result is 1048576 Blocks.

    "CONFLICT" warning message is displayed when keyword "BYTES" is
    used for other than "BLOCKS" to "BYTES" conversion. For example:

    $ WRITE SYS$OUTPUT F$CUNITS (512,"BYTES","BLOCKS")
    %DCL-W-CONFLICT, illegal combination of command elements - check documentation
    \BYTES\
    $ WRITE SYS$OUTPUT F$CUNITS (10,"KB","BYTES")
    %DCL-W-CONFLICT, illegal combination of command elements - check documentation
    \BYTES\

    The correct syntax to be used is as follows:

    $ WRITE SYS$OUTPUT F$CUNITS (512,"B", "BLOCKS")
    1BLOCKS
    $ WRITE SYS$OUTPUT F$CUNITS (10,"KB","B")
    10240B

4  –  F$CVSI

    Converts the specified bits in the specified character string to
    a signed number.

    Format

      F$CVSI(start-bit,number-of-bits,string)

4.1  –  Return Value

    The integer equivalent of the extracted bit field, converted as a
    signed value.

4.2  –  Arguments

 start-bit

    Specifies the offset of the first bit to be extracted. The
    low-order (rightmost) bit of a string is position number 0
    for determining the offset. Specify the offset as an integer
    expression.

    If you specify an expression with a negative value, or with a
    value that exceeds the number of bits in the string, then DCL
    displays the INVRANGE error message.

 number-of-bits

    Specifies the length of the bit string to be extracted, which
    must be less than or equal to the number of bits in the string.

    If you specify an expression with a negative value, or with a
    value that is invalid when added to the bit position offset, then
    DCL displays the INVRANGE error message.

 string

    Specifies the string from which the bits are taken. Specify the
    string as a character string expression.

4.3  –  Examples

    1.$ A[0,32] = %X2B
      $ SHOW SYMBOL A
        A = "+..."
      $ X = F$CVSI(0,4,A)
      $ SHOW SYMBOL X
        X = -5   Hex = FFFFFFFB  Octal = 37777777773

      This example uses an arithmetic overlay to assign the
      hexadecimal value 2B to all 32 bits of the symbol A. For more
      information on arithmetic overlays, see the description of the
      assignment statement (=).

      The symbol A has a string value after the overlay because it
      was previously undefined. (If a symbol is undefined, it has a
      string value as a result of an arithmetic overlay. If a symbol
      was previously defined, it retains the same data type after
      the overlay.) The hexadecimal value 2B corresponds to the ASCII
      value of the plus sign (+).

      Next, the F$CVSI function extracts the low-order 4 bits
      from the symbol A; the low-order 4 bits contain the binary
      representation of the hexadecimal value B. These bits are
      converted, as a signed value, to an integer. The converted
      value, -5, is assigned to the symbol X.

    2.$ SYM[0,32] = %X2A
      $ SHOW SYMBOL SYM
        SYM = "*..."
      $ Y = F$CVSI(0,33,SYM)
      %DCL-W-INVRANGE, field specification is out of bounds -
         check sign and size
      $ SHOW SYMBOL Y
      %DCL-W-UNDSYM, undefined symbol - check spelling

      In this example, the width argument specified with the F$CVSI
      function is too large. Therefore, DCL issues an error message
      and the symbol Y is not assigned a value.

5  –  F$CVTIME

    Converts an absolute or a combination time string to a string of
    the form yyyy-mm-dd hh:mm:ss.cc. The F$CVTIME function can also
    return information about an absolute, combination, or delta time
    string.

    Format

      F$CVTIME([input_time] [,output_time_format] [,output_field])

5.1  –  Return Value

    A character string containing the requested information.

5.2  –  Arguments

 input_time

    Specifies a string containing absolute, a delta, or a combination
    time, or TODAY, TOMORROW, or YESTERDAY. Specify the input time
    string as a character string expression.

    If the input_time argument is omitted or is specified as a null
    string (""), the current system date and time, in absolute
    format, is used. If parts of the date field are omitted, the
    missing values default to the current date. If parts of the time
    field are omitted, the missing values default to zero.

    For more information on specifying time values, see the OpenVMS
    User's Manual or the online help topic Date.

    If the input_time argument is a delta time, you must specify the
    output_time_format argument as DELTA.

 output_time_format

    Specifies the time format for the information you want returned.
    Specify the output_time_format argument as one of the following
    character string expressions:

    ABSOLUTE    The requested information should be returned
                in absolute time format, which is dd-mmm-yyyy
                hh:mm:ss.cc. Single-digit days are returned with
                no leading space or zero.

    COMPARISON  The requested information should be returned in the
    (default)   form yyyy-mm-dd hh:mm:ss.cc (used for comparing two
                times).

    DELTA       The requested information should be returned in delta
                format, which is dddd-hh:mm:ss.cc. If you specify
                DELTA as the output_time_format argument, then you
                must also provide a delta time specification for the
                input_time argument.

 output_field

    Specifies a character string expression containing one of the
    following (do not abbreviate): DATE, MONTH, DATETIME (default),
    SECOND, DAY, TIME, HOUR, WEEKDAY, HUNDREDTH, YEAR, MINUTE,
    DAYOFYEAR, HOUROFYEAR, MINUTEOFYEAR, SECONDOFYEAR.

    The information is returned in the time format specified by the
    output_time_format argument.

    If the input_time argument is a delta time and the output_time_
    format argument is DELTA, you cannot specify MONTH, WEEKDAY,
    YEAR, DAYOFYEAR, HOUROFYEAR, MINUTEOFYEAR, or SECONDOFYEAR.

    When the weekday is returned, the first letter is in uppercase,
    and the following letters are in lowercase.

5.3  –  Examples

    1.$ TIME = F$TIME()
      $ SHOW SYMBOL TIME
        TIME = "14-DEC-2002 10:56:23.10"
      $ TIME = F$CVTIME(TIME)
      $ SHOW SYMBOL TIME
        TIME = "2002-12-14 10:56:23.10"

      This example uses the F$TIME function to return the system
      time as a character string and to assign the time to the symbol
      TIME. Then the F$CVTIME function is used to convert the system
      time to an alternate time format. Note that you do not need to
      place quotation marks (" ")  around the argument TIME because
      it is a symbol. Symbols are automatically evaluated when they
      are used as arguments for lexical functions.

      You can use the resultant string to compare two dates (using
      .LTS. and .GTS. operators). For example, you can use F$CVTIME
      to convert two time strings and store the results in the
      symbols TIME_1 and TIME_2. You can compare the two values,
      and branch to a label, based on the following results:

          $ IF TIME_1 .LTS. TIME_2 THEN GOTO FIRST

    2.$ NEXT = F$CVTIME("TOMORROW",,"WEEKDAY")
      $ SHOW SYMBOL NEXT
       NEXT = "Tuesday"

      In this example, F$CVTIME returns the weekday that corresponds
      to the absolute time keyword "TOMORROW". You must enclose the
      arguments "TOMORROW" and "WEEKDAY" in quotation marks because
      they are character string expressions. Also, you must include a
      comma as a placeholder for the output_time_format argument that
      is omitted.

    3.$ SHOW TIME
        27-MAR-2002 09:50:31
      $ WRITE SYS$OUTPUT F$CVTIME(,,"DAYOFYEAR")
      86
      $ WRITE SYS$OUTPUT F$CVTIME(,,"HOUROFYEAR")
      2049
      $ WRITE SYS$OUTPUT F$CVTIME(,,"MINUTEOFYEAR")
      122991
      $ WRITE SYS$OUTPUT F$CVTIME(,,"SECONDOFYEAR")
      7379476

      In this example, F$CVTIME returns the values for the
      following keywords: DAYOFYEAR, HOUROFYEAR, MINUTEOFYEAR, and
      SECONDOFYEAR.

6  –  F$CVUI

    Extracts bit fields from character string data and converts the
    result to an unsigned number.

    Format

      F$CVUI(start-bit,number-of-bits,string)

6.1  –  Return Value

    The integer equivalent of the extracted bit field, converted as
    an unsigned value.

6.2  –  Arguments

 start-bit

    Specifies the offset of the first bit to be extracted. The
    low-order (rightmost) bit of a string is position number 0
    for determining the offset. Specify the offset as an integer
    expression.

    If you specify an expression with a negative value, or with a
    value that exceeds the number of bits in the string, DCL displays
    the INVRANGE error message.

 number-of-bits

    Specifies the length of the bit string to be extracted, which
    must be less than or equal to the number of bits in the string
    argument.

    If you specify an expression with a negative value, or with a
    value that is invalid when added to the bit position offset, DCL
    displays the INVRANGE error message.

 string

    Specifies the character string to be edited.

6.3  –  Example

  $ A[0,32] = %X2B
  $ SHOW SYMBOL A
    A = "+..."
  $ X = F$CVUI(0,4,A)
  $ SHOW SYMBOL X
    X = 11   Hex = 0000000B  Octal = 00000000013

      This example uses an arithmetic overlay to assign the
      hexadecimal value 2B to all 32 bits of the symbol A. The
      symbol A has a string value after the overlay because it was
      previously undefined. (If a symbol is undefined, it has a
      string value as a result of an arithmetic overlay. If a symbol
      was previously defined, it retains the same data type after
      the overlay.) The hexadecimal value 2B corresponds to the ASCII
      character "+".

      Next, the F$CVUI function extracts the low-order 4 bits
      from the symbol A; the low-order 4 bits contain the binary
      representation of the hexadecimal value B. These bits are
      converted, as a signed value, to an integer. The converted
      value, 11, is assigned to the symbol X.

7  –  F$DELTA_TIME

    Returns the time difference between a given start and end time.
    The end time must be the same as or later than the start time.

    Format

      F$DELTA_TIME(start-time,end-time,format)

7.1  –  Return Value

    A character string containing the difference between the start
    and end times. The returned string has the following fixed
    format:
    dddd hh:mm:ss.cc

7.2  –  Argument

 start-time

    Absolute time expression of the start time in the following
    format:

    dd-mmm-yyyy hh:mm:ss.cc

 end-time

    Absolute time expression of the end time in the following format:

    dd-mmm-yyyy hh:mm:ss.cc

 format

    Format for delta time return value. The keywords are as follows:

    o  ASCTIM: ASCII time format

    o  DCL: DCL delta time format This format can be used as an input
       to other DCL time-related lexicals and commands.

7.3  –  Example

  $ START=F$TIME()
  $ END=F$TIME()
  $ SHOW SYMBOL START
   START = "15-JUL-2003 16:26:35.77"
  $ SHOW SYMBOL END
   END = "15-JUL-2003 16:26:41.39"
  $ WRITE SYS$OUTPUT F$DELTA_TIME(START,END)
   0 00:00:05.62

      This example uses the F$TIME() lexical function to define a
      symbol for the start time and end time. It then uses F$DELTA_
      TIME to display the time difference between the start and end
      time.

      This example returns the delta between the start and end time
      in DCL and ASCII formats.

   (WRITE SYS$OUTPUT F$DELTA_TIME ("BOOT", "LOGIN")
     0 10:24:18.92
  $ WRITE SYS$OUTPUT F$DELTA_TIME ("BOOT", "LOGIN", "DCL")
  0-10:24:18.92
  $ WRITE SYS$OUTPUT F$DELTA_TIME ("BOOT", "LOGIN", "ASCTIM")
     0 10:24:18.92)

      This example returns the delta between the boot and login time
      in DCL and ASCII formats.

8  –  F$DEVICE

    Returns the device names of all devices on a system that meet the
    specified selection criteria.

    Note that the device names are returned in random order.

    Format

      F$DEVICE([search_devnam],[devclass],[devtype], [stream-id])

8.1  –  Return Value

    A character string containing the name of a device in the
    system's list of devices. After the last device name in the
    system's device list is returned, the F$DEVICE function returns a
    null string ("").

8.2  –  Arguments

 search_devnam

    Specifies the name of the device for which F$DEVICE is to search.
    The asterisk (*)  and the percent sign (%) wildcard characters
    are allowed in the search_devnam argument.

    Specify the search_devnam argument as a character string
    expression.

 devclass

    Specifies the device class for which F$DEVICE is to search.
    Specify the devclass argument as a character string expression
    that corresponds to a valid device class name.

    See the DVI$_DEVCLASS item in the $GETDVI system service for
    additional information.

 devtype

    Specifies the device type for which F$DEVICE is to search.
    Specify the devtype argument as a character string expression
    that corresponds to a valid type name.

    See the DVI$_DEVTYPE item in the $GETDVI system service for
    additional information.

                                   NOTE

       Specifying a device type without specifying a device class
       will result in an error.

 stream-id

    A positive integer representing the search stream identification
    number.

    The search stream identification number is used to maintain
    separate search contexts when you use the F$DEVICE function more
    than once and when you supply different search criteria. If you
    use the F$DEVICE function more than once in a command procedure
    and if you also use different search criteria, specify stream-id
    arguments to identify each search separately.

    If the search criteria are changed in a call before the device
    name list is exhausted, the context will be reinitialized and the
    search will restart.

    If you omit the stream-id argument, the F$DEVICE function assumes
    an implicit single search stream. That is, the F$DEVICE function
    starts searching at the beginning each time you specify different
    search criteria.

8.3  –  Example

  $ START:
  $     DEVICE_NAME = F$DEVICE("*0:","DISK","RA60")
  $     IF DEVICE_NAME .EQS. "" THEN EXIT
  $     SHOW SYMBOL DEVICE_NAME
  $     GOTO START

      This command procedure displays the device names of all the
      RA60s on a unit numbered 0.

      Because no stream-id argument is specified, F$DEVICE uses an
      implicit search stream. Each subsequent use of the F$DEVICE
      function uses the same search criteria to return the next
      device name. After the last device name is displayed, the
      F$DEVICE function returns a null string and the procedure
      exits.

9  –  F$DIRECTORY

    Returns the current default directory name string. The
    F$DIRECTORY function has no arguments, but must be followed by
    parentheses.

    Format

      F$DIRECTORY()

9.1  –  Return Value

    A character string for the current default directory name,
    including brackets ([]).  If you use the SET DEFAULT command
    and specify angle brackets (<>) in a directory specification,
    the F$DIRECTORY function returns angle brackets in the directory
    string.

9.2  –  Example

  $ SAVE_DIR = F$DIRECTORY()
  $ SET DEFAULT [CARLEN.TESTFILES]
     .
     .
     .
  $ SET DEFAULT 'SAVE_DIR'

      This example shows an excerpt from a command procedure that
      uses the F$DIRECTORY function to save the current default
      directory setting. The assignment statement equates the symbol
      SAVE_DIR to the current directory. Then the SET DEFAULT command
      establishes a new default directory. Later, the symbol SAVE_DIR
      is used in the SET DEFAULT command that restores the original
      default directory.

      Note that you can use the F$ENVIRONMENT function with the
      DEFAULT keyword to return the default disk and directory.
      You should use the F$ENVIRONMENT function rather than the
      F$DIRECTORY function in situations involving more than one
      disk.

10  –  F$EDIT

    Edits the character string based on the edits specified in the
    edit-list argument.

    Format

      F$EDIT(string, edit-list)

10.1  –  Return Value

    A character string containing the specified edits.

10.2  –  Arguments

 string

    Specifies a character string to be edited. Quoted sections of the
    string are not edited.

 edit-list

    Specifies a character string containing one or more of the
    following keywords that specify the types of edits to be made
    to the string:

    Edit          Action

    COLLAPSE      Removes all spaces or tabs.
    COMPRESS      Replaces multiple spaces or tabs with a single
                  space.
    LOWERCASE     Changes all uppercase characters to lowercase.
    TRIM          Removes leading and trailing spaces or tabs.
    UNCOMMENT     Removes comments.
    UPCASE        Changes all lowercase characters to uppercase.

    If you specify more than one keyword, separate them with commas
    (,).  Do not abbreviate these keywords.

    Edits are not applied to quoted sections of strings; therefore,
    if a string contains quotation marks (" "),  the characters
    within the quotation marks are not affected by the edits
    specified in the edit list.

                                   NOTE

       When UPCASE is specified with LOWERCASE in an edit-list,
       UPCASE takes precedence.

10.3  –  Examples

    1.$ LINE = "   THIS   LINE   CONTAINS A ""  QUOTED  "" WORD"
      $ SHOW SYMBOL LINE
        LINE =  "    THIS    LINE    CONTAINS A "  QUOTED  " WORD"
      $ NEW_LINE = F$EDIT(LINE, "COMPRESS, TRIM")
      $ SHOW SYMBOL NEW_LINE
        NEW_LINE = "THIS LINE CONTAINS A "  QUOTED  " WORD"

      This example uses the F$EDIT function to compress and trim a
      string by replacing multiple blanks with a single blank, and by
      removing leading and trailing blanks. The string LINE contains
      quotation marks around the word QUOTED. (To enter quotation
      marks into a character string, use double quotation marks in
      the assignment statement.)

      Note that the F$EDIT function does not compress the spaces in
      the quoted section of the string; therefore, the spaces are
      retained around the word QUOTED.

    2.$ LOOP:
      $      READ/END_OF_FILE = DONE INPUT_FILE RECORD
      $      RECORD = F$EDIT(RECORD, "TRIM, UPCASE")
      $      WRITE OUTPUT_FILE RECORD
      $      GOTO LOOP
         .
         .
         .

      This example sets up a loop to read records from a file, to
      edit them, and to write them to an output file. The edited
      records have leading and trailing blanks removed, and are
      converted to uppercase.

    3.$ UNCOMMENT_LINE = F$EDIT("$ DIR ! THIS IS THE COMMENT", "UNCOMMENT")
      $ SHOW SYMBOL UNCOMMENT_LINE
      $ UNCOMMENT_LINE = "$ DIR"

      This example uses the F$EDIT function to remove comments.

11  –  F$ELEMENT

    Extracts one element from a string of elements.

    Format

      F$ELEMENT(element-number, delimiter, string)

11.1  –  Return Value

    A character string containing the specified element.

11.2  –  Arguments

 element-number

    Specifies the number of the element to extract (numbering begins
    with zero). Specify the element-number argument as an integer
    expression. If the element-number argument exceeds the number of
    elements in the string, F$ELEMENT returns the delimiter.

 delimiter

    Specifies a character used to separate the elements in the
    string. Specify the delimiter as a character string expression.

 string

    Specifies a string containing a delimited list of elements.
    Specify the string as a character string expression.

11.3  –  Examples

    1.$ DAY_LIST = "MON/TUE/WED/THU/FRI/SAT/SUN"
      $ INQUIRE DAY "ENTER DAY (MON TUE WED THU FRI SAT SUN)"
      $ NUM = 0
      $ LOOP:
      $       LABEL = F$ELEMENT(NUM,"/",DAY_LIST)
      $       IF LABEL .EQS. "/" THEN GOTO END
      $       IF DAY .EQS. LABEL THEN GOTO 'LABEL'
      $       NUM = NUM +1
      $       GOTO LOOP
      $
      $ MON:
         .
         .
         .

      This example sets up a loop to test an input value against the
      elements in a list of values. If the value for DAY matches
      one of the elements in DAY_LIST, control is passed to the
      corresponding label. If the value returned by the F$ELEMENT
      function matches the delimiter, the value DAY was not present
      in the DAY_LIST, and control is passed to the label END.

    2.$ ! INDEX.COM
      $ !
      $ CHAPTERS = "0,1,2,3,4,5,6,A,B,C"
      $ NEXT = 0
      $ LOOP:
      $   NEXT = NEXT + 1
      $   NUM = F$ELEMENT(NEXT,",",CHAPTERS)
      $   IF (NUM .NES. ",")
      $   THEN
      $      RUN INDEX CHAP'NUM'
      $      GOTO LOOP
      $   ENDIF

      This example processes files named CHAP1, CHAP2, ... CHAP6,
      CHAPA, CHAPB, and CHAPC, in that order. (Zero is included in
      the CHAPTERS string to initialize the procedure logic.) NEXT
      is initialized to zero. The procedure enters the loop. In the
      first iteration, NEXT is incremented to 1 and the result of the
      F$ELEMENT call is the string "1". The procedure runs the index,
      chapter 1. In the second iteration, NEXT is incremented to 2
      and the result of the F$ELEMENT call is the string "1". The
      procedure runs the index, chapter 2. Processing continues until
      the result of the F$ELEMENT call is the delimiter specified in
      the call.

12  –  F$ENVIRONMENT

    Returns information about the current DCL command environment.

    Format

      F$ENVIRONMENT(item)

12.1  –  Return Value

    Information that corresponds to the specified item. The return
    value can be either an integer or a character string, depending
    on the specified item.

12.2  –  Argument

 item

    Specifies the type of information to be returned. Specify one of
    the following keywords (do not abbreviate these keywords):

                   Data
    Item           Type    Information Returned

    CAPTIVE        String  TRUE if you are logged in to a captive
                           account. The system manager can define
                           captive accounts in the user authorization
                           file (UAF) by using the Authorize utility
                           (AUTHORIZE).

    CONTROL        String  Control characters currently enabled
                           with SET CONTROL. Multiple characters
                           are separated by commas; if no control
                           characters are enabled, the null string
                           ("") is returned.

    DEFAULT        String  Current default device and directory name.
                           The returned string is the same as SHOW
                           DEFAULT output.

    DEPTH          Integer Current command procedure depth. The
                           command procedure depth is 0 when you
                           log in interactively and when you submit
                           a batch job. The command procedure depth
                           is 1 when you execute a command procedure
                           interactively or from within a batch job.
                           A nested command procedure has a depth of
                           1 greater than the depth of the command
                           procedure from which the nested procedure
                           is executed.

    DISIMAGE       String  TRUE if you are logged in to an account
                           that does not allow you to directly invoke
                           images (for example, RUN is not allowed).
                           The system manager can add or remove the
                           DISIMAGE attribute for accounts in the UAF
                           by using AUTHORIZE.

    INTERACTIVE    String  TRUE if the process is executing
                           interactively.

    KEY_STATE      String  Current locked keypad state. See the
                           description of the DEFINE/KEY command
                           for more information on keypad states.

    MAX_DEPTH      Integer Maximum allowable command procedure depth.

    MESSAGE        String  Current setting of SET MESSAGE qualifiers.
                           Each qualifier in the string is prefaced
                           by a slash (/);  therefore, the output from
                           F$ENVIRONMENT("MESSAGE") can be appended
                           to the SET MESSAGE command to form a valid
                           DCL command line.

    NOCONTROL      String  Control characters currently disabled with
                           SET NOCONTROL. Multiple characters are
                           separated by commas (,);  if no control
                           characters are disabled, the null string
                           is returned.

    ON_CONTROL_Y   String  If issued from a command procedure,
                           returns TRUE if ON_CONTROL_Y is set. ON_
                           CONTROL_Y always returns FALSE at DCL
                           command level.

    ON_SEVERITY    String  If issued from a command procedure,
                           returns the severity level at which the
                           action specified with the ON command is
                           performed. ON_SEVERITY returns NONE when
                           SET NOON is in effect or at DCL command
                           level.

    OUTPUT_RATE    String  Delta time string containing the default
                           output rate, which indicates how often
                           data is written to the batch job log
                           file while the batch job is executing.
                           OUTPUT_RATE returns a null string if used
                           interactively.

    PROCEDURE      String  File specification of the current command
                           procedure. If used interactively, the
                           terminal device name is returned.

    PROMPT         String  Current DCL prompt.

    PROMPT_        String  TRUE if a carriage return and line feed
    CONTROL                precede the prompt.

    PROTECTION     String  Current default file protection.
                           The string can be used with the SET
                           PROTECTION/DEFAULT command to form a valid
                           DCL command line.

    RESTRICTED     String  TRUE if you are logged in to a restricted
                           account. The system manager can define
                           restricted accounts in the UAF by using
                           AUTHORIZE.

    SYMBOL_SCOPE   String  [NO]LOCAL, [NO]GLOBAL to indicate the
                           current symbol scoping state.

    VERB_SCOPE     String  [NO]LOCAL, [NO]GLOBAL to indicate the
                           current symbol scoping state for verbs.
                           (For more information, see the description
                           of the SET SYMBOL command.)

    VERIFY_IMAGE   String  TRUE if image verification (SET
                           VERIFY=IMAGE) is in effect. If image
                           verification is in effect, then the
                           command procedure echoes input data read
                           by images.

    VERIFY_        String  Returns the prefix control string set by
    PREFIX                 means of the SET PREFIX command.

    VERIFY_        String  TRUE if procedure verification
    PROCEDURE              SET VERIFY=PROCEDURE is in effect. If
                           command verification is in effect, then
                           the command procedure echoes DCL command
                           lines.

12.3  –  Examples

    1.$ SAVE_MESSAGE = F$ENVIRONMENT("MESSAGE")
      $ SET MESSAGE/NOFACILITY/NOIDENTIFICATION
         .
         .
         .
      $ SET MESSAGE'SAVE_MESSAGE'

      This example uses the F$ENVIRONMENT function to save the
      current message setting before changing the setting. At the
      end of the command procedure, the original message setting is
      restored. The single quotation marks (` ')  surrounding the
      symbol SAVE_MESSAGE indicate that the value for the symbol
      should be substituted.

    2.$ MAX = F$ENVIRONMENT("MAX_DEPTH")
      $ SHOW SYMBOL MAX
        MAX = 32   Hex = 00000020  Octal = 00000000040

      This example uses the F$ENVIRONMENT function to determine the
      maximum depth allowable within command procedures.

    3.$ SAVE_PROT = F$ENVIRONMENT("PROTECTION")
      $ SET PROTECTION = (SYSTEM:RWED, OWNER:RWED, GROUP, WORLD)/DEFAULT
         .
         .
         .
      $ SET PROTECTION = ('SAVE_PROT')/DEFAULT

      This example uses the F$ENVIRONMENT function to save the
      current default protection before changing the protection.
      At the end of the command procedure, the original protection
      is restored. You must place single quotation marks around the
      symbol SAVE_PROT to request symbol substitution.

13  –  F$EXTRACT

    Extracts the specified characters from the specified string.

    Format

      F$EXTRACT(start,length,string)

13.1  –  Return Value

    A character string containing the characters delimited by the
    start and length arguments.

13.2  –  Arguments

 start

    Specifies the offset of the starting character of the string
    you want to extract. Specify the start argument as an integer
    expression that is greater than or equal to zero.

    The offset is the relative position of a character or a substring
    with respect to the beginning of the string. Offset positions
    begin with zero. The string always begins with the leftmost
    character.

    If you specify an offset that is greater than or equal to the
    length of the string, F$EXTRACT returns a null string ("").

 length

    Specifies the number of characters you want to extract; must be
    less than or equal to the size of the string. Specify the length
    as an integer expression that is greater than or equal to zero.

    If you specify a length that exceeds the number of characters
    from the offset to the end of the string, the F$EXTRACT function
    returns the characters from the offset through the end of the
    string.

 string

    Specifies the character string to be edited. Specify the string
    as a character string expression.

13.3  –  Examples

    1.$ NAME = "PAOLO TESTA"
      $ FIRST = F$EXTRACT(0,5,NAME)
      $ SHOW SYMBOL FIRST
        FIRST = "PAOLO"

      This portion of a command procedure uses the F$EXTRACT function
      to extract the first 5 characters from the character string
      assigned to the symbol NAME. The offset and length arguments
      are integers, and the string argument is a symbol. You do not
      need to use quotation marks (" ")  around integers or symbols
      when they are used as arguments for lexical functions.

    2.$ P1 = "MYFILE.DAT"
      $ FILENAME = F$EXTRACT(0,F$LOCATE(".",P1),P1)

      This portion of a command procedure shows how to locate a
      character within a string, and how to extract a substring
      ending at that location.

      The lexical function F$LOCATE gives the numeric value
      representing the offset position of a period in the character
      string value of P1. (The offset position of the period is equal
      to the length of the substring before the period.)

      This F$LOCATE function is used as an argument in the F$EXTRACT
      function to specify the number of characters to extract from
      the string. If a procedure is invoked with the parameter
      MYFILE.DAT, these statements result in the symbol FILENAME
      being given the value MYFILE.

      Note that the F$LOCATE function in the above example assumes
      that the file specification does not contain a node name or
      a directory specification containing a subdirectory name. To
      obtain the file name from a full file specification, use the
      F$PARSE function.

    3.$ IF F$EXTRACT(12,2,F$TIME()) .GES. "12" THEN GOTO AFTERNOON
      $ MORNING:
      $ WRITE SYS$OUTPUT "Good morning!"
      $ EXIT
      $ AFTERNOON:
      $ WRITE SYS$OUTPUT "Good afternoon!"
      $ EXIT

      This example shows a procedure that displays a different
      message, depending on whether the current time is morning or
      afternoon. It first obtains the current time of day by using
      the F$TIME function. The F$TIME function returns a character
      string, which is the string argument for the F$EXTRACT
      function. The F$TIME function is automatically evaluated when
      it is used as an argument, so you do not need to use quotation
      marks.

      Next, the F$EXTRACT function extracts the hours from the date
      and time string returned by F$TIME. The string returned by
      F$TIME always contains the hours field beginning at an offset
      of 12 characters from the start of the string.

      The F$EXTRACT function extracts 2 characters from the string,
      beginning at this offset, and compares the string value
      extracted with the string value 12. If the comparison is true,
      then the procedure writes "Good afternoon!". Otherwise, it
      writes "Good morning!".

      Note that you can also use the F$CVTIME function to extract
      the hour field from a time specification. This method is easier
      than the one shown in the above example.

14  –  F$FAO

    Converts character and numeric input to ASCII character strings.
    (FAO stands for formatted ASCII output.) By specifying formatting
    instructions, you can use the F$FAO function to convert integer
    values to character strings, to insert carriage returns and form
    feeds, to insert text, and so on.

    Format

      F$FAO(control-string[,argument[,...]])

14.1  –  Return Value

    A character string containing formatted ASCII output. This output
    string is created from the fixed text and FAO directives in the
    control string.

14.2  –  Arguments

 control-string

    Specifies the fixed text of the output string, consisting of
    text and any number of FAO directives. The control string may
    be any length. Specify the control string as a character string
    expression.

    The F$FAO function uses FAO directives to modify or insert ASCII
    data into the fixed text in the control string.

 argument[,...]

    Specifies from 1 to 15 arguments required by the FAO directives
    used in the control string. Specify the arguments as integer or
    character string expressions.

    FAO directives may require one or more arguments. The order
    of the arguments must correspond exactly with the order of the
    directives in the control string. In most cases, an error message
    is not displayed if you misplace an argument.

    If you specify an argument whose type (integer or string) does
    not match that of the corresponding directive, unpredictable
    results are returned. You can use the F$INTEGER and F$STRING
    lexical functions to convert arguments to the proper type.

    If there are not enough arguments listed, F$FAO continues reading
    past the end of an argument list. Therefore, always be sure to
    include enough arguments to satisfy the requirements of all the
    directives in a control string.

    If you specify an invalid parameter for any directive, you may
    see unexpected errors, which indicate that the command did not
    succeed. (These errors are passed through to you from the $FAO
    system service.)

14.3  –  Directives

    Specify an FAO directive using any one of the following formats:

    Format        Function

    !DD           One directive
    !n(DD)        A directive repeated a specified number of times
    !lengthDD     A directive that places its output in a field of a
                  specified length
    !n(lengthDD)  A directive that is repeated a specified number of
                  times and generates output fields of a specified
                  length

    The exclamation point (!)  indicates that the following character
    or characters are to be interpreted as an FAO directive. DD
    represents a 1- or 2-character uppercase code indicating
    the action that F$FAO is to perform. When specifying repeat
    counts, n is a decimal value specifying the number of times the
    directive is to be repeated. The length value is a decimal number
    that instructs F$FAO to generate an output field of "length"
    characters.

    Repeat counts and output lengths may also be specified by using
    a number sign (#)  in place of absolute numeric value. If you use
    a number sign, you must specify the numeric value as an integer
    expression in the corresponding place in the argument list.

    When a variable output field is specified with a repeat count,
    only one length parameter is required, because each output string
    has the specified length.

    Here is a summary of the FAO directives you can specify in a
    control string.

                                   NOTE

       Two types of directives that are supported by the $FAO
       system service are not supported by the DCL F$FAO lexical
       function. These types are:

       o  Quadword numeric directives, which are not supported
          in DCL because all DCL numeric values are stored and
          manipulated as longwords.

       o  String directives other than the !AS directive, which are
          not supported in DCL because all DCL strings are stored
          and manipulated by descriptor.

       For further information on the $FAO system service
       directive, see the VSI OpenVMS System Services Reference
       Manual.

              Argument
    Directive Type           Description

    Character string insertion:
    !AS       String         Inserts a character string as is.

    Zero-filled numeric conversion:
    !OB       Integer        Converts a byte to octal notation.
    !OW       Integer        Converts a word to octal notation.
    !OL       Integer        Converts a longword to octal notation.
    !XB       Integer        Converts a byte to hexadecimal notation.
    !XW       Integer        Converts a word to hexadecimal notation.
    !XL       Integer        Converts a longword to hexadecimal
                             notation.
    !ZB       Integer        Converts a byte to decimal notation.
    !ZW       Integer        Converts a word to decimal notation.
    !ZL       Integer        Converts a longword to decimal notation.

    Blank-filled numeric conversion:
    !UB       Integer        Converts a byte to decimal notation
                             without adjusting for negative numbers.
    !UW       Integer        Converts a word to decimal notation
                             without adjusting for negative numbers.
    !UL       Integer        Converts a longword to decimal notation
                             without adjusting for negative numbers.
    !SB       Integer        Converts a byte to decimal notation
                             with negative numbers converted
                             properly.
    !SW       Integer        Converts a word to decimal notation
                             with negative numbers converted
                             properly.
    !SL       Integer        Converts a longword to decimal notation
                             with negative numbers converted
                             properly.

    Special formatting:
    !/        None           Inserts a carriage return and a line
                             feed.
    !_        None           Inserts a tab.
    !^        None           Inserts a form feed.
    !!        None           Inserts an exclamation point (!).
    !%I       Integer        Converts a longword integer to a named
                             UIC in the format
                             [group-identifier,member-identifier].
    !%S       None           Inserts an "s" if the most recently
                             converted number is not 1. (Not
                             recommended for use with multilingual
                             products.)
    !%U       Integer        Converts a longword integer to a numeric
                             UIC in the format [g,m], where g is the
                             group number and m is the member number.
                             The directive inserts the brackets and
                             the comma.
    !n<...!>  None           Left-justifies and blank-fills all data
                             represented by the instructions . . . in
                             fields n characters wide.
    !n*c      None           Repeats the character represented
                             by c for n times.
    !n%C      String         Inserts a character string when the
                             most recently evaluated argument has
                             the value n. (Recommended for use with
                             multilingual products.)
    !%E       String         Inserts a character string when the
                             value of the most recently evaluated
                             argument does not match any preceding
                             !n%C directives. (Recommended for use
                             with multilingual products.)
    !%F       None           Marks the end of a plurals statement.
    !%T       Integer        Inserts the current time.
              equal to 0
    !%D       Integer        Inserts the current date/time.
              equal to 0

    Argument interpretation:
    !-        None           Reuses the last argument.
    !+        None           Skips the next argument.

14.4  –  Examples

    1.$ COUNT = 57
      $ REPORT = F$FAO("NUMBER OF FORMS = !SL",COUNT)
      $ SHOW SYMBOL REPORT
        REPORT = "NUMBER OF FORMS = 57"

      In this command procedure, the FAO directive !SL is used in
      a control string to convert the number equated to the symbol
      COUNT to a character string. The converted string is inserted
      into the control string.

      Note that COUNT is assigned an integer value of 57. The F$FAO
      function returns the ASCII string, "NUMBER OF FORMS = 57", and
      assigns the string to the symbol REPORT.

    2.$ A = "ERR"
      $ B = "IS"
      $ C = "HUM"
      $ D = "AN"
      $ PHRASE = F$FAO("TO !3(AS)",A,B,C+D)
      $ SHOW SYMBOL PHRASE
      $ PHRASE = "TO ERRISHUMAN"

      In this command procedure, the !AS directive is used to insert
      the values assigned to the symbols A, B, C, and D into the
      control string.

      Because the specified repeat count for the !AS directive is 3,
      F$FAO looks for three arguments. The arguments in this example
      include the symbol A ("ERR"), the symbol B ("IS"), and the
      expression C+D ("HUMAN"). Note that the values of these string
      arguments are concatenated to form the string "ERRISHUMAN".

    3.$ A = "ERR"
      $ B = "IS"
      $ C = "HUMAN"
      $ PHRASE = F$FAO("TO !#(#AS)",3,6,A,B,C)
      $ SHOW SYMBOL PHRASE
      $ PHRASE = "TO ERR   IS    HUMAN "

      In this command procedure, the F$FAO function is used with
      the !AS directive to format a character string. The first
      number sign (#)  represents the repeat count given by the
      first argument, 3. The second number sign represents the field
      size given by the second argument, 6. The next three arguments
      (A,B,C) provide the strings that are placed into the control
      string each time the !AS directive is repeated.

      Each argument string is output to a field having a length of
      6 characters. Because each string is less than 6 characters,
      each field is left-justified and padded with blank spaces. The
      resulting string is assigned to the symbol PHRASE.

    4.$ OFFSPRING = 1
      $ REPORT = F$FAO-
      ("There !0UL!1%Cis!%Eare!%F !-!UL !-!0UL!1%Cchild!%Echildren!%F here",OFFSPRING)
      $ SHOW SYMBOL REPORT
      $ REPORT ="There is 1 child here"

      In this command procedure, the !0UL directive evaluates the
      argument OFFSPRING but does not insert the value in the output
      string. The !n%C directive inserts the character string "is"
      into the output string because its value and the value of the
      argument OFFSPRING match. The directives !-!UL evaluate the
      argument a second time so that the correct character string can
      be inserted in the proper place in the output string. The !%F
      directive marks the end of each plurals statement. The F$FAO
      function returns the ASCII string "There is 1 child here" and
      assigns the string to the symbol REPORT.

15  –  F$FID_TO_NAME

    Valid for Alpha and Integrity server systems only.

    Translates a file identification to a file specification.

    Format

      F$FID_TO_NAME(device-name,file-id)

15.1  –  Return Value

    A character string containing the file specification.

15.2  –  Arguments

 device-name

    Specifies the device on which the file resides. You can specify a
    logical name for the device.

 file-id

    Specifies the file identification that is to be translated into
    the correlating file specification.

15.3  –  Example

  $ WRITE SYS$OUTPUT F$FID_TO_NAME("SYS$SYSDEVICE","(2901,33,0)")
  DISK$NODE1:[VMS$COMMON.SYSEXE]SHOW.EXE;1

      This example demonstrates that the file with identifier
      "2901,33,0" on the system disk is file SHOW.EXE. Note: You
      can omit the parentheses around the file identifier, provided
      it is enclosed by double quotation marks.

16  –  F$FILE_ATTRIBUTES

    Returns attribute information for a specified file.

    Format

      F$FILE_ATTRIBUTES(filespec,item)

16.1  –  Return Value

    Either an integer or a character string, depending on the item
    you request.

16.2  –  Arguments

 filespec

    Specifies the name of the file about which you are requesting
    information. You must specify the file name as a character string
    expression.

    You can specify only one file name. Wildcard characters are not
    allowed.

 item

    Indicates which attribute of the file is to be returned. The
    item argument must be specified as a character string expression,
    and can be any one of the OpenVMS RMS field names listed in the
    following table:

               Return
    Item       Type     Information Returned

    AI         String   TRUE if after-image (AI) journaling is
                        enabled; FALSE if disabled.

    ALQ        Integer  Allocation quantity.

    BDT        String   Backup date/time.

    BI         String   TRUE if before-image (BI) journaling is
                        enabled; FALSE if disabled.

    BKS        Integer  Bucket size.

    BLS        Integer  Block size.

    CBT        String   TRUE if contiguous-best-try; otherwise FALSE.

    CDT        String   Creation date/time.

    CTG        String   TRUE if contiguous; otherwise FALSE.

    DEQ        Integer  Default extension quantity.

    DID        String   Directory ID string.

    DIRECTORY  String   Returns TRUE or FALSE. Returns TRUE if it is
                        a directory.

    DVI        String   Device name string.

    EDT        String   Expiration date/time.

    EOF        Integer  Number of blocks used.

    ERASE      String   TRUE if a file's contents are erased before a
                        file is deleted; otherwise FALSE.

    FFB        Integer  First free byte.

    FID        String   File ID string.

    FILE_      String   Record count and data byte count in the form
    LENGTH_             (n,m), where n is the record count and m is
    HINT                the data byte count. An invalidated count is
                        specified by a -1 for n or m.

    FSZ        Integer  Fixed control area size.

    GBC        Integer  Global buffer count.

    GBC32      Integer  Enhanced longword version of global buffer
                        count with a per-file maximum size of about
                        2.1 billion for indexed files.

    GBCFLAGS   String   Per-file management flags for sizing of
                        global buffer cache. Returns PERCENT if
                        global buffer count is expresses as a
                        percent, DEFAULT if global buffer size is
                        determined at runtime by an algorithm using
                        two global buffer SYSGEN parameters (GB_
                        CACHEALLMAX and GB_DEFPERCENT); or NONE if no
                        per-file management flags are enabled for the
                        file.
    GRP        Integer  Owner group number.

    JOURNAL_   String   TRUE if the file is a journal; otherwise
    FILE                FALSE.

    KNOWN      String   Known file; returns TRUE or FALSE to
                        indicate whether file is installed with the
                        Install utility (INSTALL). However, returns
                        NOSUCHFILE if a file does not exist (for
                        example, the file has been installed but
                        subsequently deleted).

    LOCKED     String   TRUE if a file is deaccessed-locked;
                        otherwise FALSE.

    LRL        Integer  Longest record length.

    MBM        Integer  Owner member number.

    MOVE       String   TRUE if movefile operations are enabled;
                        otherwise FALSE.

    MRN        Integer  Maximum record number.

    MRS        Integer  Maximum record size.

    NOA        Integer  Number of areas.

    NOBACKUP   String   FALSE if the file is marked for backup; TRUE
                        if the file is marked NOBACKUP.

    NOK        Integer  Number of keys.

    ORG        String   File organization; returns SEQ, REL, IDX.

    PRESHELVED String   TRUE if the file is preshelved; otherwise
    (Alpha/Integrity    FALSE.
    servers
    only)

    PRO        String   File protection string.

    PVN        Integer  Prolog version number.

    RAT        String   Record attributes; returns CR, PRN, FTN, "".

    RCK        String   TRUE if read check; otherwise FALSE.

    RDT        String   Revision date/time.

    RFM        String   Record format string; returns the values VAR,
                        FIX, VFC, UDF, STM, STMLF, STMCR.

    RU         String   TRUE if recovery unit (RU) journaling is
                        enabled; returns TRUE or FALSE.

    RVN        Integer  Revision number.

    SHELVABLE  String   TRUE if the file is shelvable; otherwise
                        FALSE.

    SHELVED    String   TRUE if the file is shelved; otherwise FALSE.

    STORED_    String   ASCII string that represents stored
    SEMANTICS           semantics.

    UIC        String   Owner user identification code (UIC) string.

    VERLIMIT   Integer  Version limit number. The value 32767
                        indicates that no version limit was set.

    WCK        String   TRUE if write check; otherwise FALSE.

16.3  –  Examples

    1.$ FILE_ORG = F$FILE_ATTRIBUTES("QUEST.DAT","ORG")
      $ SHOW SYMBOL FILE_ORG
        FILE_ORG = "SEQ"

      This example uses the F$FILE_ATTRIBUTES function to assign the
      value of the file organization type to the symbol FILE_ORG. The
      F$FILE_ATTRIBUTES function returns the character string SEQ to
      show that QUEST.DAT is a sequential file.

      The QUEST.DAT and ORG arguments for the F$FILE_ATTRIBUTES
      function are string literals and must be enclosed in quotation
      marks (" ")  when used in expressions.

    2.$ RFM = F$FILE_ATTRIBUTES("KANSAS::USE$:[CARS]SALES.CMD","RFM")
      $ SHOW SYMBOL RFM
        RFM = "VAR"

      This example uses the F$FILE_ATTRIBUTES function to return
      information about a file on a remote node. The function returns
      the record format string VAR, indicating that records are
      variable length.

17  –  F$GETDVI

    Returns a specified item of information for a specified device.

    Format

      F$GETDVI(device-name,item[,pathname])

17.1  –  Return Value

    Either an integer or a character string, depending on the item
    you request.

17.2  –  Arguments

 device-name

    Specifies a physical device name or a logical name equated to
    a physical device name. Specify the device name as a character
    string expression.

    After the device-name argument is evaluated, the F$GETDVI
    function examines the first character of the name. If the
    first character is an underscore (_),  the name is considered
    a physical device name; otherwise, a single level of logical name
    translation is performed and the equivalence name, if any, is
    used.

 item

    Specifies the type of device information to be returned. The
    item must be specified as a character string expression. You
    can specify any one of the items listed below. For detailed
    descriptions of each item code, see the VSI OpenVMS DCL
    Dictionary.

    Items marked with a ** are valid for Integrity servers only.

    Items marked with a * are valid for Alpha and Integrity servers
    only.

    Items marked with a + are typically used with the pathname
    argument.

    ACCESSTIMES_RECORDED*            ACPPID                    ACPTYPE
    ALL                              ALLDEVNAM                 ALLOCLASS
    ALT_HOST_AVAIL                   ALT_HOST_NAME             ALT_HOST_TYPE
    AVAILABLE_PATH_COUNT*            AVL                       CCL
    CLUSTER                          CONCEALED                 CYLINDERS
    DEVBUFSIZ                        DEVCHAR                   DEVCHAR2
    DEVCLASS                         DEVDEPEND                 DEVDEPEND2
    DEVICE_MAX_IO_SIZE*              DEVICE_TYPE_NAME          DEVLOCKNAM
    DEVNAM                           DEVSTS                    DEVTYPE
    DFS_ACCESS                       DIR                       DMT
    DUA                              ELG                       ERASE_ON_DELETE*
    ERRCNT+ERROR_RESET_TIME*         EXISTS                    EXPSIZE*
    FC_HBA_FIRMWARE_REV              FC_NODE_NAME              FC_PORT_NAME
    FOD                              FOR                       FREEBLOCKS
    FULLDEVNAM                       GEN                       HARDLINKS_SUPPORTED*
    HOST_AVAIL                       HOST_COUNT                HOST_NAME
    HOST_TYPE                        IDV                       LAN_ALL_MULTICAST_MODE*
    LAN_AUTONEG_ENABLED*             LAN_DEFAULT_MAC_ADDRESS*  LAN_FULL_DUPLEX*
    LAN_JUMBO_FRAMES_ENABLED*        LAN_LINK_STATE_VALID      LAN_LINK_UP*
    LAN_MAC_ADDRESS*                 LAN_PROMISCUOUS_MODE*     LAN_PROTOCOL_NAME*
    LAN_PROTOCOL_TYPE*               LAN_SPEED*                LOCKID
    LOGVOLNAM                        MAILBOX_BUFFER_QUOTA*     MAILBOX_INITIAL_QUOTA*
    MAXBLOCK                         MAXFILES                  MBX
    MEDIA_ID                         MEDIA_NAME                MEDIA_TYPE
    MNT                              MOUNT_TIME*               MOUNTCNT
    MOUNTVER_ELIGIBLE*               MPDEV_AUTO_PATH_SW_CNT*   MPDEV_CURRENT_PATH*
    MPDEV_MAN_PATH_SW_CNT*           MT3_DENSITY               MT3_SUPPORTED
    MULTIPATH*                       MVSUPMSG*                 NET
    NEXTDEVNAM                       NOCACHE_ON_VOLUME*        NOHIGHWATER
    NOSHARE_MOUNTED*                 ODS2_SUBSET0*             ODS5*
    ODV                              OPCNT+                    OPR
    OWNUIC                           PATH_AVAILABLE*+          PATH_NOT_RESPONDING*+
    PATH_POLL_ENABLED*+              PATH_SWITCH_FROM_TIME*+   PATH_SWITCH_TO_TIME*+
    PATH_USER_DISABLED*+             PID                       PREFERRED_CPU
    PREFERRED_CPU_BITMAP*            PROT_SUBSYSTEM_ENABLED*   QLEN*
    RCK                              RCT                       REC
    RECSIZ                           REFCNT                    REMOTE_DEVICE
    RND                              ROOTDEVNAM                RTM
    SCSI_DEVICE_FIRMWARE_REV*        SDI                       SECTORS
    SERIALNUM                        SERVED_DEVICE             SET_HOST_TERMINAL
    SHDW_CATCHUP_COPYING             SHDW_COPIER_NODE*         SHDW_DEVICE_COUNT*
    SHDW_GENERATION*                 SHDW_MASTER               SHDW_MASTER_MBR*
    SHDW_MASTER_NAME                 SHDW_MBR_COPY_DONE*       SHDW_MBR_COUNT*
    SHDW_MBR_MERGE_DONE*             SHDW_MBR_READ_COST*       SHDW_MEMBER
    SHDW_MERGE_COPYING*              SHDW_MINIMERGE_ENABLE*    SHDW_NEXT_MBR_NAME
    SHDW_READ_SOURCE*                SHDW_SITE*                SHDW_TIMEOUT*
    SHR                              SPL                       SPLDEVNAM
    SQD                              SSD_LIFE_REMAINING**      SSD_USAGE_REMAINING**
    STS                              SWL                       TOTAL_PATH_COUNT*
    TRACKS                           TRANSCNT                  TRM
    TT_ACCPORNAM                     TT_ALTYPEAHD              TT_ANSICRT
    TT_APP_KEYPAD                    TT_AUTOBAUD               TT_AVO
    TT_BLOCK                         TT_BRDCSTMBX              TT_CHARSET
    TT_CRFILL                        TT_CS_HANGUL              TT_CS_HANYU
    TT_CS_HANZI                      TT_CS_KANA                TT_CS_KANJI
    TT_CS_THAI                       TT_DECCRT                 TT_DECCRT2
    TT_DECCRT3                       TT_DECCRT4                TT_DIALUP
    TT_DISCONNECT                    TT_DMA                    TT_DRCS
    TT_EDIT                          TT_EDITING                TT_EIGHTBIT
    TT_ESCAPE                        TT_FALLBACK               TT_HALFDUP
    TT_HANGUP                        TT_HOSTSYNC               TT_INSERT
    TT_LFFILL                        TT_LOCALECHO              TT_LOWER
    TT_MBXDSABL                      TT_MECHFORM               TT_MECHTAB
    TT_MODEM                         TT_MODHANGUP              TT_NOBRDCST
    TT_NOECHO                        TT_NOTYPEAHD              TT_OPER
    TT_PAGE                          TT_PASTHRU                TT_PHYDEVNAM
    TT_PRINTER                       TT_READSYNC               TT_REGIS
    TT_REMOTE                        TT_SCOPE                  TT_SECURE
    TT_SETSPEED                      TT_SIXEL                  TT_SYSPWD
    TT_TTSYNC                        TT_WRAP                   UNIT
    VOLCHAR*                         VOLCOUNT                  VOLNAM
    VOLNUMBER                        VOLSETMEM                 VOLSIZE*
    VOLUME_EXTEND_QUANTITY*          VOLUME_MOUNT_GROUP*       VOLUME_MOUNT_SYS*
    VOLUME_PENDING_WRITE_ERR*        VOLUME_RETAIN_MAX*        VOLUME_RETAIN_MIN*
    VOLUME_SPOOLED_DEV_CNT*          VOLUME_WINDOW*            VPROT
    WCK                              WRITETHRU_CACHE_ENABLED*  WWID*

   ** Integrity servers only
    * Alpha and Integrity servers only
    + Used with the pathname argument.

 pathname (Alpha/Integrity servers only)

    Specifies a path name for a multipath-capable device. Specify the
    path name as a character string expression.

    Item codes that use the pathname argument are identified by
    a + in the item code list. In general, item codes that return
    information that can vary by path do use the pathname argument.
    You can see the paths for a multipath device by using the SHOW
    DEVICE /FULL command, the SYS$DEVICE_PATH_SCAN system service, or
    the F$MULTIPATH lexical function.

    If the pathname argument is specified, it is validated against
    the existing paths for the specified device. If the path does not
    exist, the NOSUCHPATH error is returned - even if the specified
    item code does not make use of the pathname argument.

17.3  –  Examples

    1.$  ERR = F$GETDVI("_DQA0","ERRCNT")
      $ SHOW SYMBOL ERR
        ERR = 0  Hex = 00000000 Octal = 000000

      This example shows how to use the F$GETDVI function to return
      an error count for the device DQA0. You must place quotation
      marks (" ")  around the device name DQA0 and the item ERRCNT
      because they are string literals.

    2.$  LIBRARY/EXTRACT=$DCDEF/OUTPUT=$DCDEF.TXT SYS$LIBRARY:STARLET.MLB

      This example shows how to create a file, $DCDEF.TXT, containing
      a list of values for device types and device classes from
      the STARLET library. The device classes begin with 'DC$', and
      device types begin with 'DT$'.

      Note that most modern SCSI disks and tapes return the generic
      DEVTYPE code (DT$_GENERIC_DK or DT$_GENERIC_MK), therefore you
      should use the DEVICE_TYPE_NAME item:

        $ X=F$GETDVI("XDELTA$DKA0:","DEVICE_TYPE_NAME")
        $ SHOW SYMBOL X
          X = "RZ29B"

    3.$  WRITE SYS$OUTPUT F$GETDVI ( "$1$DGA30", "PATH_SWITCH_TO_TIME", -
      _$  "PGA0.5000-1FE1-0001=5782" )
      19-MAY-2006 14:47:41.77

      This example shows the use of the optional path name parameter
      for F$GETDVI. If a path is not specified, information for the
      multipath current path is returned. To determine the paths for
      a multipath device, use the F$MULTIPATH lexical function.

    4.$ SSD_USAGE_REMAINING = F$GETDVI("DKA100:","SSD_USAGE_REMAINING")
      $ SHOW SYMBOL SSD_USAGE_REMAINING
        SSD_USAGE_REMAINING = 100   Hex = 00000064  Octal = 00000000144
      $ SSD_LIFE_REMAINING = F$GETDVI("DKA100:","SSD_LIFE_REMAINING")
      $ SHOW SYMBOL SSD_LIFE_REMAINING
        SSD_LIFE_REMAINING = 610372 Hex = 00095044  Octal = 00002250104

      This example shows how to use the F$GETDVI function to return the
      wear out gas gauge data for the Solid State Drive (SSD) connected
      to a node in the Host Bus Adapters (HBA) mode and returns "-1" for
      other disks.

      SSD_USAGE_REMAINING - Reports in percentage the remaining life
                            of SSD available for use.

      SSD_LIFE_REMAINING  - Estimates the remaining life, in days, of
                            the SSD drive based on its percent usage
                            remaining.

      Note: The return value of SSD_USAGE_REMAINING "0" indicates that
      the device is worn out; it cannot accept any more writes and requires
      replacement. The estimated wear out information is based on the
      workload the device is running and the calculation is based on the
      endurance usage reported by VSI SSD drives.

18  –  F$GETENV

    Valid on Alpha systems only.

    Returns the value of the specified console environment variable.

    Format

      F$GETENV(itmlst)

18.1  –  Return Value

    Returns the value of the specified console environment variable.
    You can modify the console environment variables when the system
    is in console mode. This lexical function allows you to read the
    contents of these variables when the system is running.

18.2  –  Arguments

 itmlst

    The defined console environment variable names are:

    Auto_action, Boot_dev, Bootdef_dev, Booted_dev, Boot_file,
    Booted_file, Boot_osflags, Booted_osflags, Boot_reset, Dump_dev,
    Enable_audit, License, Char_set, Language, Tty_dev

18.3  –  Example

  $ dump_device = f$getenv("dump_dev")
  $ write sys$output "The dump device for this system is ", dump_
 device

      This function writes out the dump device for the system.

19  –  F$GETJPI

    Returns information about the specified process.

    Requires GROUP privilege to obtain information on other processes
    in the same group. Requires WORLD privilege to obtain information
    on any other processes in the system.

    Format

      F$GETJPI(pid,item)

19.1  –  Return Value

    Either an integer or a character string, depending on the item
    you request.

19.2  –  Arguments

 pid

    Specifies the process identification (PID) number of the process
    for which information is being reported. Specify the pid argument
    as a character string expression. You can omit the leading zeros.

    If you specify a null string (""),  the current PID number is
    used.

    You cannot use an asterisk (*)  or percent sign (%) wildcard
    character to specify the pid argument in the F$GETJPI function,
    as you can with the $GETJPI system service. To get a list of
    process identification numbers, use the F$PID function.

 item

    Indicates the type of process information to be returned. Specify
    the item argument as a character string expression. You can
    specify any one of the following items:

    ACCOUNT              APTCNT                 ASTACT
    ASTCNT               ASTEN                  ASTLM
    AUTHPRI              AUTHPRIV               BIOCNT
    BIOLM                BUFIO                  BYTCNT
    BYTLM                CASE_LOOKUP_IMAGE*     CASE_LOOKUP_PERM*
    CLASSIFICATION*      CLINAME                CPULIM
    CPUTIM               CREPRC_FLAGS           CURPRIV
    CURRENT_CAP_MASK*    DFPFC                  DFWSCNT
    DIOCNT               DIOLM                  DIRIO
    EFCS                 EFCU                   EFWM
    ENQCNT               ENQLM                  EXCVEC
    FAST_VP_SWITCH       FILCNT                 FILLM
    FINALEXC             FREP0VA                FREP1VA
    FREPTECNT            GPGCNT                 GRP
    HOME_RAD            IMAGECOUNT             IMAGE_AUTHPRIV*
    IMAGE_PERMPRIV*      IMAGE_WORKPRIV*        IMAGNAME
    IMAGPRIV             INSTALL_RIGHTS*        INSTALL_RIGHTS_SIZE*
    JOBPRCCNT            JOBTYPE                LAST_LOGIN_I
    LAST_LOGIN_N         LOGIN_FAILURES         LOGIN_FLAGS
    LOGINTIM             MASTER_PID             MAXDETACH
    MAXJOBS              MEM                    MODE
    MSGMASK              MULTITHREAD            NODENAME
    NODE_CSID            NODE_VERSION           OWNER
    PAGEFLTS             PAGFILCNT              PAGFILLOC
    PARSE_STYLE_PERM*    PARSE_STYLE_IMAGE*     PERMANENT_CAP_MASK*
    PERSONA_AUTHPRIV*    PERSONA_ID*            PERSONA_PERMPRIV*
    PERSONA_RIGHTS*      PERSONA_RIGHTS_SIZE*   PERSONA_WORKPRIV*
    PGFLQUOTA            PHDFLAGS               PID
    PPGCNT               PRCCNT                 PRCLM
    PRCNAM               PRI                    PRIB
    PROC_INDEX           PROCESS_RIGHTS         PROCPRIV
    RIGHTSLIST           RIGHTS_SIZE            SCHED_CLASS_NAME*
    SEARCH_SYMLINK_TEMP  SEARCH_SYMLINK_PERM
    SHRFILLM             SITESPEC               SLOW_VP_SWITCH
    STATE                STS                    STS2
    SUBSYSTEM_RIGHTS*    SUBSYSTEM_RIGHTS_SIZE* SWPFILLOC
    SYSTEM_RIGHTS        SYSTEM_RIGHTS_SIZE*    TABLENAME
    TERMINAL             TMBU                   TOKEN
    TQCNT                TQLM                   TT_ACCPORNAM
    TT_PHYDEVNAM         UAF_FLAGS              UIC
    USERNAME             VIRTPEAK               VOLUMES
    VP_CONSUMER          VP_CPUTIM              WSAUTH
    WSAUTHEXT            WSEXTENT               WSPEAK
    WSQUOTA              WSSIZE

    * Alpha only

19.3  –  Examples

    1.$ NAME = F$GETJPI("3B0018","USERNAME")
      $ SHOW SYMBOL NAME
        NAME = "JANE        "

      This example shows how to use the F$GETJPI function to return
      the user name for the process number 3B0018. The user name is
      assigned to the symbol NAME.

    2.$ X=F$ENVIRONMENT("MESSAGE")
      $ SHOW SYMBOL X
        X = "/FACILITY/SEVERITY/IDENTIFICATION/TEXT"
      $ X=F$GETJPI("0","MSGMASK")
      $ SHOW SYMBOL X
        X = 15   Hex = 0000000F  Octal = 00000000017
      $ SET MESSAGE /NOFACILITY
      $ X=F$ENVIRONMENT("MESSAGE")
      $ SHOW SYMBOL X
        X = "/NOFACILITY/SEVERITY/IDENTIFICATION/TEXT"
      $ X=F$GETJPI("0","MSGMASK")
      $ SHOW SYMBOL X
        X = 7   Hex = 00000007  Octal = 00000000007
      $ SET MESSAGE /FACILITY
      $ X=F$ENVIRONMENT("MESSAGE")
      $ SHOW SYMBOL X
        X = "/FACILITY/SEVERITY/IDENTIFICATION/TEXT"
      $ X=F$GETJPI("0","MSGMASK")
      $ SHOW SYMBOL X
        X = 15   Hex = 0000000F  Octal = 00000000017
      $

      This example shows the use of the F$GETJPI MSGMASK item.

20  –  F$GETQUI

    Returns information about queues, including batch and print jobs
    currently in the queues, form definitions, and characteristic
    definitions kept in the queue database.

    Also returns information about queue managers.

    For most operations, read (R) access is required.

    Format

      F$GETQUI(function,[item],[object-id],[flags])

20.1  –  Return Value

    Either an integer or a character string, depending on the item
    you request. For items that return a Boolean value, the string
    is TRUE or FALSE. If the $GETQUI system service returns an error
    code, F$GETQUI returns a null string ("").

20.2  –  Arguments

 function

    Specifies the action that the F$GETQUI lexical function is to
    perform. F$GETQUI supports all functions that can be specified
    with the $GETQUI system service. The following table lists these
    functions:

    Function              Description

    CANCEL_OPERATION      Terminates any wildcard operation that may
                          have been initiated by a previous call to
                          F$GETQUI.

    DISPLAY_              Returns information about a specific
    CHARACTERISTIC        characteristic definition or the next
                          characteristic definition in a wildcard
                          operation.

    DISPLAY_ENTRY         Returns information about a specific job
                          entry or the next job entry that matches
                          the selection criteria in a wildcard
                          operation. The DISPLAY_ENTRY function code
                          is similar to the DISPLAY_JOB function
                          code in that both return job information.
                          DISPLAY_JOB, however, requires that a
                          call be made to establish queue context;
                          DISPLAY_ENTRY does not require that queue
                          context be established. Only those entries
                          that match the user-name of the current
                          process will be processed.

    DISPLAY_FILE          Returns information about the next file
                          defined for the current job context. Before
                          you make a call to F$GETQUI to request
                          file information, you must make a call to
                          display queue and job information (with
                          the DISPLAY_QUEUE and DISPLAY_JOB function
                          codes) or to display entry information
                          (with the DISPLAY_ENTRY function code).

    DISPLAY_FORM          Returns information about a specific form
                          definition or the next form definition in a
                          wildcard operation.

    DISPLAY_JOB           Returns information about the next job
                          defined for the current queue context.
                          Before you make a call to F$GETQUI to
                          request job information, you must make a
                          call to display queue information (with
                          the DISPLAY_QUEUE function code). The
                          DISPLAY_JOB function code is similar to
                          the DISPLAY_ENTRY function code in that
                          both return job information. DISPLAY_JOB,
                          however, requires that a call be made to
                          establish queue context; DISPLAY_ENTRY
                          does not require that queue context be
                          established.

    DISPLAY_MANAGER       Returns information about a specific queue
                          manager or the next queue manager in a
                          wildcard operation.

    DISPLAY_QUEUE         Returns information about a specific queue
                          definition or the next queue definition in
                          a wildcard operation.

    TRANSLATE_QUEUE       Translates a logical name for a queue to
                          the equivalence name for the queue.

    Some function arguments cannot be specified with the item-
    code, the object-id, or the flags argument. The following table
    lists each function argument and corresponding format line to
    show whether the item-code, object-id, and flags arguments
    are required, optional, or not applicable for that specific
    function. In the following format lines, brackets ([ ])  denote
    an optional argument. An omitted argument means the argument is
    not applicable for that function. Note that two commas (,,)  must
    be used as placeholders to denote an omitted (whether optional or
    not applicable) argument.

    Function         Format Line

    CANCEL_          F$GETQUI("CANCEL_OPERATION") or F$GETQUI("  ")
    OPERATION

    DISPLAY_         F$GETQUI("DISPLAY_CHARACTERISTIC",
    CHARACTERISTIC   [item],object-id,[flags])

    DISPLAY_ENTRY    F$GETQUI("DISPLAY_ENTRY",[item], [object-
                     id],[flags])

    DISPLAY_FILE     F$GETQUI("DISPLAY_FILE",[item],,[flags])

    DISPLAY_FORM     F$GETQUI("DISPLAY_FORM",[item], object-
                     id,[flags])

    DISPLAY_JOB      F$GETQUI("DISPLAY_JOB",[item],,[flags])

    DISPLAY_MANAGER  F$GETQUI("DISPLAY_MANAGER",[item],object-
                     id,[flags])

    DISPLAY_QUEUE    F$GETQUI("DISPLAY_QUEUE",[item],object-
                     id,[flags])

    TRANSLATE_QUEUE  F$GETQUI("TRANSLATE_QUEUE",[item],object-id)

 item

    Corresponds to a $GETQUI system service output item code. The
    item argument specifies the kind of information you want returned
    about a particular queue, job, file, form, or characteristic.

    These are the item codes:

    ACCOUNT_NAME                AFTER_TIME               ASSIGNED_QUEUE_NAME
    AUTOSTART_ON                BASE_PRIORITY            CHARACTERISTICS
    CHARACTERISTIC_NAME         CHARACTERISTIC_NUMBER    CHECKPOINT_DATA
    CLI                         COMPLETED_BLOCKS         CONDITION_VECTOR
    CPU_DEFAULT                 CPU_LIMIT                DEFAULT_FORM_NAME
    DEFAULT_FORM_STOCK          DEVICE_NAME              ENTRY_NUMBER
    EXECUTING_JOB_COUNT         FILE_BURST               FILE_CHECKPOINTED
    FILE_COPIES                 FILE_COPIES_DONE         FILE_COUNT
    FILE_DELETE                 FILE_DEVICE              FILE_DID
    FILE_DOUBLE_SPACE           FILE_EXECUTING           FILE_FLAG
    FILE_FLAGS                  FILE_IDENTIFICATION      FILE_PAGE_HEADER
    FILE_PAGINATE               FILE_PASSALL             FILE_SETUP_MODULES
    FILE_SPECIFICATION          FILE_STATUS              FILE_TRAILER
    FIRST_PAGE                  FORM_DESCRIPTION         FORM_FLAGS
    FORM_LENGTH                 FORM_MARGIN_BOTTOM       FORM_MARGIN_LEFT
    FORM_MARGIN_RIGHT           FORM_MARGIN_TOP          FORM_NAME
    FORM_NUMBER                 FORM_SETUP_MODULES       FORM_SHEET_FEED
    FORM_STOCK                  FORM_TRUNCATE            FORM_WIDTH
    FORM_WRAP                   GENERIC_TARGET           HOLDING_JOB_COUNT
    INTERVENING_BLOCKS          INTERVENING_JOBS         JOB_ABORTING
    JOB_COMPLETION_QUEUE        JOB_COMPLETION_TIME      JOB_COPIES
    JOB_COPIES_DONE             JOB_CPU_LIMIT            JOB_ERROR_RETENTION
    JOB_EXECUTING               JOB_FILE_BURST           JOB_FILE_BURST_ONE
    JOB_FILE_FLAG               JOB_FILE_FLAG_ONE        JOB_FILE_PAGINATE
    JOB_FILE_TRAILER            JOB_FILE_TRAILER_ONE     JOB_FLAGS
    JOB_HOLDING                 JOB_INACCESSIBLE         JOB_LIMIT
    JOB_LOG_DELETE              JOB_LOG_NULL             JOB_LOG_SPOOL
    JOB_LOWERCASE               JOB_NAME                 JOB_NOTIFY
    JOB_PENDING                 JOB_PID                  JOB_REFUSED
    JOB_RESET_MODULES           JOB_RESTART              JOB_RETAINED
    JOB_RETENTION               JOB_RETENTION_TIME       JOB_SIZE
    JOB_SIZE_MAXIMUM            JOB_SIZE_MINIMUM         JOB_STALLED
    JOB_STARTING                JOB_STATUS               JOB_SUSPENDED
    JOB_TIMED_RELEASE           JOB_WSDEFAULT            JOB_WSEXTENT
    JOB_WSQUOTA                 LAST_PAGE                LIBRARY_SPECIFICATION
    LOG_QUEUE                   LOG_SPECIFICATION        MANAGER_NAME
    MANAGER_NODE                MANAGER_STATUS           NOTE
    OPERATOR_REQUEST            OWNER_UIC                PAGE_SETUP_MODULES
    PARAMETER_1 to PARAMETER_8  ENDING_JOB_BLOCK_COUNT   PENDING_JOB_COUNT
    PENDING_JOB_REASON          PEND_CHAR_MISMATCH       PEND_JOB_SIZE_MAX
    PEND_JOB_SIZE_MIN           PEND_LOWERCASE_MISMATCH  PEND_NO_ACCESS
    PEND_QUEUE_BUSY             PEND_QUEUE_STATE         PEND_STOCK_MISMATCH
    PRIORITY                    PROCESSOR                PROTECTION
    QUEUE_ACL_SPECIFIED         QUEUE_ALIGNING           QUEUE_AUTOSTART
    QUEUE_AUTOSTART_INACTIVE    QUEUE_AVAILABLE          QUEUE_BATCH
    QUEUE_BUSY                  QUEUE_CLOSED             QUEUE_CPU_DEFAULT
    QUEUE_CPU_LIMIT             QUEUE_DESCRIPTION        QUEUE_DIRECTORY
    QUEUE_FILE_BURST            QUEUE_FILE_BURST_ONE     QUEUE_FILE_FLAG
    QUEUE_FILE_FLAG_ONE         QUEUE_FILE_PAGINATE      QUEUE_FILE_TRAILER
    QUEUE_FILE_TRAILER_ONE      QUEUE_FLAGS              QUEUE_GENERIC
    QUEUE_GENERIC_SELECTION     QUEUE_IDLE               QUEUE_JOB_BURST
    QUEUE_JOB_FLAG              QUEUE_JOB_SIZE_SCHED     QUEUE_JOB_TRAILER
    QUEUE_LOWERCASE             QUEUE_NAME               QUEUE_PAUSED
    QUEUE_PAUSING               QUEUE_PRINTER            QUEUE_RECORD_BLOCKING
    QUEUE_REMOTE                QUEUE_RESETTING          QUEUE_RESUMING
    QUEUE_RETAIN_ALL            QUEUE_RETAIN_ERROR       QUEUE_SERVER
    QUEUE_STALLED               QUEUE_STARTING           QUEUE_STATUS
    QUEUE_STOP_PENDING          QUEUE_STOPPED            QUEUE_STOPPING
    QUEUE_SWAP                  QUEUE_TERMINAL           QUEUE_UNAVAILABLE
    QUEUE_WSDEFAULT             QUEUE_WSEXTENT           QUEUE_WSQUOTA
    RAD                        REQUEUE_QUEUE_NAME       RESTART_QUEUE_NAME
    RETAINED_JOB_COUNT          SCSNODE_NAME             SECURITY_INACCESSIBLE
    SUBMISSION_TIME             TIMED_RELEASE_JOB_COUNT  UIC
    USERNAME                    WSDEFAULT                WSEXTENT
    WSQUOTA

 object-id

    Corresponds to the $GETQUI system service QUI$SEARCH_NAME, QUI$_
    SEARCH_NUMBER, and QUI$_SEARCH_JOB_NAME input item codes. The
    object-id argument specifies either the name or the number of
    an object (for example, a specific queue name, job name, or
    form number) about which F$GETQUI is to return information. The
    asterisk (*) and the percent sign (%) wildcard characters are
    allowed for the following functions:

       DISPLAY_CHARACTERISTIC
       DISPLAY_ENTRY
       DISPLAY_FORM
       DISPLAY_MANAGER
       DISPLAY_QUEUE

    By specifying an asterisk (*)  or percent sign (%) wildcard
    character as the object-id argument on successive calls, you
    can get status information about one or more jobs in a specific
    queue or about files within jobs in a specific queue. When a name
    is used with wildcard characters, each call returns information
    for the next object (queue, form, and so on) in the list. A null
    string ("")  is returned when the end of the list is reached. A
    wildcard can represent only object names, not object numbers.

 flags

    Specifies a list of keywords, separated by commas, that
    corresponds to the flags defined for the $GETQUI system service
    QUI$_SEARCH_FLAGS input item code. (These flags are used to
    define the scope of the object search specified in the call to
    the $GETQUI system service.) Note that keywords in the following
    table can be used only with certain function codes.

                     Valid Function
    Keyword          Code                Description

    ALL_JOBS         DISPLAY_JOB         Requests that F$GETQUI
                                         search all jobs included
                                         in the established queue
                                         context. If you do not
                                         specify this flag, F$GETQUI
                                         returns information only
                                         about jobs that have the
                                         same user name as the
                                         caller.

    BATCH            DISPLAY_QUEUE       Selects batch queues.
                     DISPLAY_ENTRY

    EXECUTING_JOBS   DISPLAY_ENTRY       Selects executing jobs.
                     DISPLAY_JOB

    FREEZE_CONTEXT   DISPLAY_            When in wildcard mode,
                     CHARACTERISTIC      prevents advance of wildcard
                     DISPLAY_ENTRY       context to the next object.
                     DISPLAY_FILE        If you do not specify
                     DISPLAY_FORM        this flag, the context is
                     DISPLAY_JOB         advanced to the next object.
                     DISPLAY_MANAGER
                     DISPLAY_QUEUE

    GENERIC          DISPLAY_ENTRY       Selects generic queues for
                     DISPLAY_QUEUE       searching.

    HOLDING_JOBS     DISPLAY_ENTRY       Selects jobs on
                     DISPLAY_JOB         unconditional hold.

    PENDING_JOBS     DISPLAY_ENTRY       Selects pending jobs.
                     DISPLAY_JOB

    PRINTER          DISPLAY_QUEUE       Selects printer queues.
                     DISPLAY_ENTRY

    RETAINED_JOBS    DISPLAY_ENTRY       Selects jobs being retained.
                     DISPLAY_JOB

    SERVER           DISPLAY_QUEUE       Selects server queues.
                     DISPLAY_ENTRY

    SYMBIONT         DISPLAY_QUEUE       Selects all output queues.
                     DISPLAY_ENTRY       Equivalent to specifying
                                         "PRINTER,SERVER,TERMINAL".

    TERMINAL         DISPLAY_QUEUE       Selects terminal queues.
                     DISPLAY_ENTRY

    THIS_JOB         DISPLAY_ENTRY       Selects all job file
                     DISPLAY_FILE        information about the
                     DISPLAY_JOB         calling batch job (entry),
                     DISPLAY_QUEUE       the command file being
                                         executed, or the queue
                                         associated with the calling
                                         batch job.

    TIMED_RELEASE_   DISPLAY_ENTRY       Selects jobs on hold until a
    JOBS             DISPLAY_JOB         specified time.

    WILDCARD         DISPLAY_            Establishes and saves a
                     CHARACTERISTIC      context. Because the context
                     DISPLAY_ENTRY       is saved, the next operation
                     DISPLAY_FORM        can be performed based on
                     DISPLAY_MANAGER     that context.
                     DISPLAY_QUEUE

20.3  –  Examples

    1.$  BLOCKS = F$GETQUI("DISPLAY_ENTRY" ,"JOB_SIZE", 1347)

      In this example, the F$GETQUI lexical function is used to
      obtain the size in blocks of print job 1347. The value returned
      reflects the total number of blocks occupied by the files
      associated with the job.

    2.$ IF F$GETQUI("DISPLAY_QUEUE", "QUEUE_STOPPED", "VAX1_BATCH") .EQS.
      "TRUE" THEN GOTO 500

      In this example, the F$GETQUI lexical function is used to
      return a value of TRUE or FALSE depending on whether the queue
      VAX1_BATCH is in a stopped state. If VAX1_BATCH is not in the
      system, F$GETQUI returns a null string ("").

    3.! This command procedure shows all queues and the jobs in them.
      $  TEMP = F$GETQUI("")
      $  QLOOP:
      $  QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*")
      $  IF QNAME .EQS. "" THEN EXIT
      $  WRITE SYS$OUTPUT ""
      $  WRITE SYS$OUTPUT "QUEUE: ", QNAME
      $  JLOOP:
      $  NOACCESS = F$GETQUI("DISPLAY_JOB","JOB_INACCESSIBLE",,"ALL_JOBS")
      $  IF NOACCESS .EQS. "TRUE" THEN GOTO JLOOP
      $  IF NOACCESS .EQS. "" THEN GOTO QLOOP
      $  JNAME = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"FREEZE_CONTEXT")
      $  WRITE SYS$OUTPUT "    JOB:  ", JNAME
      $  GOTO JLOOP

      This sample command procedure displays all the queues in the
      system and all the jobs to which the user has read access
      in the system. In the outer loop a wildcard display queue
      operation is performed. No call is made to establish the right
      to obtain information about the queue, because all users have
      implicit read access to queue attributes. Because a wildcard
      queue name is specified ("*"), wildcard queue context is
      maintained across calls to F$GETQUI.

      In the inner loop, to obtain information about all jobs, we
      enter nested wildcard mode from wildcard display queue mode.
      In this loop, a call is made to establish the right to obtain
      information about these jobs because users do not have implicit
      read access to jobs. The FREEZE_CONTEXT keyword is used in
      the request for a job name to prevent the advance of the
      wildcard context to the next object. After the job name has
      been retrieved and displayed, the procedure loops back up for
      the next job. The context is advanced because the procedure has
      not used the FREEZE_CONTEXT keyword. The wildcard queue context
      is dissolved when the list of matching queues is exhausted.
      Finally, F$GETQUI returns a null string ("")  to denote that no
      more objects match the specified search criteria.

    4.$ THIS_NODE = F$EDIT(F$GETSYI("SCSNODE"),"COLLAPSE")
      $ TEMP = F$GETQUI("CANCEL_OPERATION")
      $ SET NOON
      $LOOP:
      $ QUEUE = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*","WILDCARD")
      $ IF QUEUE .EQS. "" THEN GOTO ENDLOOP
      $ IF THIS_NODE .EQS.-
      F$GETQUI("DISPLAY_QUEUE","SCSNODE_NAME","*","WILDCARD,FREEZE_CONTEXT")
      $ THEN
      $    IF .NOT.-
        F$GETQUI("DISPLAY_QUEUE","QUEUE_AUTOSTART","*","WILDCARD,FREEZE_CONTEXT")-
        THEN START/QUEUE 'QUEUE'
      $ ENDIF
      $ GOTO LOOP
      $ENDLOOP:
      $ SET ON

      This command procedure looks at all queues associated with the
      local cluster node and starts any queue that is not marked as
      autostart.

      The procedure starts by obtaining the nodename of the local
      system and clearing the F$GETQUI context. In addition, error
      handling is turned off for the loop so that, if a queue had
      been started previously, the resulting error from the START
      QUEUE command does not abort the command procedure.

      Inside the loop, the F$GETQUI function gets the next queue name
      in the queue list. If the result is empty, then it has reached
      the end of the list and it exits the loop.

      The next IF statement checks to see if the queue runs on the
      local node. If it does, then the next statement checks to see
      if the queue is marked as an autostart queue. If that is false,
      then the queue is started with the start command. The loop is
      then repeated.

      The final command of the procedure restores DCL error handling
      to the previous setting.

    5.$  IF p1.EQS."" THEN INQUIRE p1 "Queue name"
      $ TEMP = F$GETQUI("")
      $ QLOOP:
      $   QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME",p1,"WILDCARD")
      $   IF QNAME .EQS. "" THEN EXIT
      $   WRITE SYS$OUTPUT ""
      $   WRITE SYS$OUTPUT "QUEUE: ", QNAME
      $   JLOOP:
      $     RETAINED = F$GETQUI("DISPLAY_JOB","JOB_RETAINED",,"ALL_JOBS")
      $     IF RETAINED .EQS. "" THEN GOTO QLOOP
      $     Entry = F$GETQUI("DISPLAY_JOB","ENTRY_NUMBER",,"FREEZE_CONTEXT,ALL_JOBS")
      $     WRITE SYS$OUTPUT "    Entry: ''Entry' Retained: ''RETAINED'"
      $     IF RETAINED.EQS."TRUE" THEN DELETE/ENTRY='Entry'
      $   GOTO JLOOP

      This command procedure deletes all retained entries from a
      nominated queue or queues. Wildcards are allowed.

    6.$ WRITE SYS$OUTPUT F$GETQUI("DISPLAY_QUEUE","RAD","BATCHQ1")
       -1

      This example returns the value of the RAD. A value of "-1"
      indicates no RAD value is attributed to the queue.

21  –  F$GETSYI

    Returns status and identification information about the local
    system (or about a node in the local mixed-architecture OpenVMS
    Cluster system, if your system is part of an OpenVMS Cluster).

    Format

      F$GETSYI(item [,node-name] [,cluster-id])

21.1  –  Return Value

    Either an integer or a character string, depending on the item
    you request.

21.2  –  Arguments

 item

    Indicates the type of information to be reported about the local
    node (or about another node in your OpenVMS Cluster, if your
    system is part of an OpenVMS Cluster). Specify the item as a
    character string expression. Here are the items you can specify
    to get information about either your local node or another node
    in your OpenVMS Cluster system. If you do not specify the node
    argument, the information is returned for the local node.
   * Alpha and Integrity servers only ** VAX only + Integrity servers only

    ACTIVE_CPU_BITMAP*   ACTIVECPU_CNT        ARCHFLAG
    ARCH_NAME            ARCH_TYPE            AVAIL_CPU_BITMAP*
    AVAILCPU_CNT         BOOT_DEVICE*         BOOTTIME
    CELLULAR_PLATFORM+   CHARACTER_EMULATED   CLUSTER_EVOTES
    CLUSTER_FSYSID       CLUSTER_FTIME        CLUSTER_MEMBER
    CLUSTER_NODES        CLUSTER_QUORUM       CLUSTER_VOTES
    COMMUNITY_ID*        CONSOLE_VERSION*     CONTIG_GBLPAGES
    CPU**                CPU_AUTOSTART*       CPU_FAILOVER*
    CPUCAP_MASK*         CPUTYPE*             CWLOGICALS
    DECIMAL_EMULATED     DECNET_FULLNAME      DECNET_VERSION
    D_FLOAT_EMULATED     ERLBUFFERPAG_S2*     ERLBUFFERPAGES
    ERRORLOGBUFF_S2*     ERRORLOGBUFFERS      F_FLOAT_EMULATED
    FREE_GBLPAGES        FREE_GBLSECTS        FREE_PAGES
    G_FLOAT_EMULATED     GALAXY_ID*           GALAXY_MEMBER*
    GALAXY_PLATFORM*     GALAXY_SHMEMSIZE*    GH_RSRVPGCNT*
    GLX_FORMATION*       GLX_MAX_MEMBERS*     GLX_MBR_MEMBER*
    GLX_MBR_NAME*        GLX_TERMINATION*     HP_ACTIVE_CPU_CNT*
    HP_ACTIVE_SP_CNT*    HP_CONFIG_SBB_CNT*   HP_CONFIG_SP_CNT*
    HP_ID+               HP_NAME+             HW_MODEL
    HW_NAME              ITB_ENTRIES*         MAX_CPUS*
    MEMSIZE              MODIFIED_PAGES       MULTITHREAD
    NODENAME             NODE_AREA            NODE_CSID
    NODE_EVOTES          NODE_HWTYPE          NODE_HWVERS
    NODE_NUMBER          NODE_QUORUM          NODE_SWINCARN
    NODE_SWTYPE          NODE_SWVERS          NODE_SYSTEMID
    NODE_VOTES           NPAGED_FREE*         NPAGED_INUSE*
    NPAGED_LARGEST*      NPAGED_TOTAL*        PAGED_FREE*
    PAGED_INUSE*         PAGED_LARGEST*       PAGED_TOTAL*
    PAGEFILE_FREE        PAGEFILE_PAGE        PAGE_SIZE
    PALCODE_VERSION*     PARTITION_ID*        POTENTIAL_CPU_BITMAP*
    POTENTIALCPU_CNT*    POWERED_CPU_BITMAP*  POWEREDCPU_CNT*
    PRESENT_CPU_BITMAP*  PRESENTCPU_CNT*      PRIMARY_CPUID*
    QUANTUM              RAD_CPUS             RAD_MAX_RADS
    RAD_MEMSIZE          RAD_SHMEMSIZE        REAL_CPUTYPE*
    SCS_EXISTS           SCSNODE*             SID
    SWAPFILE_FREE        SWAPFILE_PAGE        SYSTEM_RIGHTS
    SYSTEM_UUID          +SYSTYPE*            TOTAL_PAGES
    USED_GBLPAGCNT       USED_GBLPAGMAX       USED_PAGES
    VECTOR_EMULATOR      VERSION              VP_MASK
    VP_NUMBER

    * Alpha and Integrity servers only    ** VAX only    + Integrity servers only

    You can also specify any of the system parameters listed in the
    VSI OpenVMS System Management Utilities Reference Manual.

 node-name

    Specifies the node in your OpenVMS Cluster system for which
    information is to be returned. Specify the node as a character
    string expression. You cannot use the asterisk (*)  and the
    percent sign (%)  wildcard characters to specify the node-name
    argument.

 cluster-id

    Specifies the cluster node identification number for which the
    information is to be returned.

    To get information for all the nodes in a cluster, use the F$CSID
    lexical function to obtain each cluster system identification
    number, and use the cluster-id argument of F$GETSYI to gather
    information about each node.

21.3  –  Examples

    1.$ SYSID = F$GETSYI("SID")
      $ SHOW SYMBOL SYSID
        SYSID = 19923201  Hex = 01300101 Octal = 000401

      This example shows how to use the F$GETSYI function to return
      the information in the system identification register. Use
      quotation marks (" ")  around the argument SID because it is a
      string literal. The value returned by F$GETSYI is assigned to
      the symbol SYSID. Because a node is not specified, information
      about your current node is returned.

    2.$ MEM = F$GETSYI("CLUSTER_MEMBER", "LONDON")
      $ SHOW SYMBOL MEM
        MEM = "TRUE"

      This example uses the F$GETSYI function to determine whether
      the node LONDON is a member of the local cluster. The return
      value TRUE indicates that the remote node LONDON is a member of
      the cluster.

    3.$ LIM = F$GETSYI("IJOBLIM")
      $ SHOW SYMBOL LIM
        LIM = 16   Hex = 00000010  Octal = 00000000020

      This example uses the system parameter IJOBLIM as an argument
      for the F$GETSYI function. This argument returns the batch job
      limit for the current system.

    4.$  DECNETVERS = F$GETSYI("DECNET_VERSION")
      $ SHOW SYMBOL DECNETVERS
        DECNETVERS = "00050D01"
      $ DECNETPHASE = F$INTEGER(F$EXTRACT(2,2,DECNETVERS))
      $ SHOW SYMBOL DECNETPHASE
        DECNETPHASE = 5   Hex = 00000005  Octal = 00000000005

      This example shows how to use F$GETSYI to return the DECnet
      version, using the DECNET_VERSION item.

    5.$ RADCPU = F$GETSYI("RAD_CPUS")
      $ SHOW SYMBOL RADCPU
        0,0,0,1,1,4,1,5

      This example uses the system parameter RAD_CPUS as an argument
      for the F$GETSYI function. This argument returns a list of
      RAD,CPU pairs, separated by commas. In this example, the first
      RAD,CPU pair is 0,0, the second pair is 0,1, and so forth.

      RAD is supported on AlphaServer GS series systems and starting
      from OpenVMS Version 8.4, support is extended to NUMA capable
      Integrity servers.

    6.$ HP_ID = F$GETSYI("HP_ID")
      $ SHOW SYMBOL HP_ID
        HP_ID = 1   Hex = 00000001  Octal = 00000000001

      This example uses the system parameter HP_ID as an argument
      for the F$GETSYI function. This argument returns the hard
      partition ID. It is supported only on Integrity servers that
      support hard partitioning.

    7.$ HP_NAME = F$GETSYI("HP_NAME")
      $ SHOW SYMBOL HP_NAME
        HP_NAME = "part1"

      This example uses the system parameter HP_NAME as an argument
      for the F$GETSYI function. This argument returns the hard
      partition name as a string. It is supported only on Integrity
      servers that support hard partitioning.

22  –  F$IDENTIFIER

    Converts an alphanumeric identifier to its integer equivalent,
    or converts an integer identifier to its alphanumeric equivalent.
    An identifier is a name or number that identifies a category of
    users. The system uses identifiers to determine a user's access
    to a resource.

    Format

      F$IDENTIFIER(identifier,conversion-type)

22.1  –  Return Value

    An integer value if you are converting an identifier from a name
    to an integer. The F$IDENTIFIER function returns a string if
    you are converting an identifier from an integer to a name. If
    you specify an identifier that is not valid, the F$IDENTIFIER
    function returns a null string ("")  (if you are converting from
    number to name) or a zero (if you are converting from name to
    number).

22.2  –  Arguments

 identifier

    Specifies the identifier to be converted. Specify the identifier
    as an integer expression if you are converting an integer to a
    name. Specify the identifier as a character string expression if
    you are converting a name to an integer.

    Any identifier holding the Name Hidden attribute will cause
    the F$IDENTIFIER to return an error when you do not hold the
    identifier in question or do not have access to the rights
    database. For further information on the attribute, see the VSI
    OpenVMS Guide to System Security.

 conversion-type

    Indicates the type of conversion to be performed. If the
    identifier argument is alphanumeric, specify the conversion-type
    argument as a character string containing "NAME_TO_NUMBER". If
    the identifier argument is numeric, specify the conversion-type
    argument as a character string containing "NUMBER_TO_NAME".

22.3  –  Examples

    1.$ UIC_INT= F$IDENTIFIER("SLOANE","NAME_TO_NUMBER")
      $ SHOW SYMBOL UIC_INT
        UIC_INT = 15728665   Hex = 00F00019  Octal = 00074000031
      $ UIC = F$FAO("!%U",UIC_INT)
      $ SHOW SYMBOL UIC
        UIC = [360,031]

      This example uses the F$IDENTIFIER to convert the member
      identifier from the UIC [MANAGERS,SLOANE] to an integer. The
      F$IDENTIFIER function shows that the member identifier SLOANE
      is equivalent to the integer 15728665. Note that you must
      specify the identifier SLOANE using uppercase letters.

      To convert this octal number to a standard numeric user
      identification code (UIC), use the F$FAO function with the
      !%U directive. (This directive converts a longword to a UIC in
      named format.) In this example, the member identifier SLOANE is
      equivalent to the numeric UIC [360,031].

    2.$ UIC_INT = (%O31 + (%X10000 * %O360))
      $ UIC_NAME = F$IDENTIFIER(UIC_INT,"NUMBER_TO_NAME")
      $ SHOW SYMBOL UIC_NAME
        UIC_NAME = "ODONNELL"

      This example obtains the alphanumeric identifier associated
      with the numeric UIC [360,031]. First, you must obtain the
      longword integer that corresponds to the UIC [360,031]. To
      do this, place the member number into the low-order word.
      Place the group number into the high-order word. Next, use the
      F$IDENTIFIER function to return the named identifier associated
      with the integer.

23  –  F$INTEGER

    Returns the integer equivalent of the result of the specified
    expression.

    Format

      F$INTEGER(expression)

23.1  –  Return Value

    An integer value that is equivalent to the specified expression.

23.2  –  Argument

 expression

    Specifies the expression to be evaluated. Specify either an
    integer or a character string expression.

    If you specify an integer expression, the F$INTEGER function
    evaluates the expression and returns the result. If you specify
    a string expression, the F$INTEGER function evaluates the
    expression, converts the resulting string to an integer, and
    returns the result.

    After evaluating a string expression, the F$INTEGER function
    converts the result to an integer in the following way. If
    the resulting string contains characters that form a valid
    integer, the F$INTEGER function returns the integer value. If
    the string contains characters that do not form a valid integer,
    the F$INTEGER function returns the integer 1 if the string begins
    with T, t, Y, or y. The function returns the integer 0 if the
    string begins with any other character.

23.3  –  Example

  $ A = "23"
  $ B = F$INTEGER("-9" + A)
  $ SHOW SYMBOL B
    B = -923 Hex=FFFFFC65 Octal=176145

      This example shows how to use the F$INTEGER function to equate
      a symbol to the integer value returned by the function. In the
      example, the F$INTEGER function returns the integer equivalent
      of the string expression ("-9" + A). First, the F$INTEGER
      function evaluates the string expression by concatenating
      the string literal "-9" with the string literal "23". Note
      that the value of the symbol A is substituted automatically
      in a string expression. Also note that the plus sign (+) is a
      string concatenation operator because both arguments are string
      literals.

      After the string expression is evaluated, the F$INTEGER
      function converts the resulting character string ("-923") to
      an integer, and returns the value -923. This integer value is
      assigned to the symbol B.

24  –  F$LENGTH

    Returns the length of the specified character string.

    Format

      F$LENGTH(string)

24.1  –  Return Value

    An integer value for the length of the string.

24.2  –  Argument

 string

    Specifies the character string whose length is being determined.
    Specify the string argument as a character string expression.

24.3  –  Example

  $ MESSAGE = F$MESSAGE(%X1C)
  $ SHOW SYMBOL MESSAGE
    MESSAGE = "%SYSTEM-F-EXQUOTA, exceeded quota"
  $ STRING_LENGTH = F$LENGTH(MESSAGE)
  $ SHOW SYMBOL STRING_LENGTH
    STRING_LENGTH = 33   Hex = 00000021  Octal = 000041

      The first assignment statement uses the F$MESSAGE function
      to return the message that corresponds to the hexadecimal
      value 1C. The message is returned as a character string and
      is assigned to the symbol MESSAGE.

      The F$LENGTH function is then used to return the length of
      the character string assigned to the symbol MESSAGE. You
      do not need to use quotation marks (" ")  when you use the
      symbol MESSAGE as an argument for the F$LENGTH function.
      (Quotation marks are not used around symbols in character
      string expressions.)

      The F$LENGTH function returns the length of the character
      string and assigns it to the symbol STRING_LENGTH. At the end
      of the example, the symbol STRING_LENGTH has a value equal
      to the number of characters in the value of the symbol named
      MESSAGE, that is, 33.

25  –  F$LICENSE

    Valid for Alpha and Integrity server systems only.

    Checks whether the specified license is loaded on the system.

    Format

      F$LICENSE(license-name[,producer-name])

25.1  –  Return Value

    A character string stating TRUE or FALSE.

25.2  –  Arguments

 license-name

    Specifies the name of the license for which you want to check the
    status.

 producer-name

    Specifies the name of the company that produced the license. By
    default, DEC is assumed to be the producer on Alpha systems and
    VSI is assumed to be the producer on Integrity server systems. To
    find an exception, specify a different producer name.

25.3  –  Examples

    1.$ SHOW LICENSE VMSCLUSTER*
      Active licenses on node NODE1:

      ------- Product ID -------- ---- Rating ----- -- Version --
      Product            Producer Units Avail Activ Version Release  Termination
      VMSCLUSTER         DEC          0  0     100    0.0  (none)    14-MAY-2005
      VMSCLUSTER-CLIENT  DEC          0  0     100    0.0  (none)    14-MAY-2005

      $ WRITE SYS$OUTPUT F$LICENSE("VMSCLUSTER")
      TRUE
      $ WRITE SYS$OUTPUT F$LICENSE("NONEXISTENT_PAK")
      FALSE

      In this example, the F$LICENSE function returns TRUE, which
      verifies that the VMSCLUSTER license is loaded on the system.
      In contrast, the status of hypothetical license NONEXISTENT_PAK
      is shown to be FALSE, indicating that it is not loaded on the
      system.

    2.$ WRITE SYS$OUTPUT F$LICENSE("ABC")
      FALSE
      $ WRITE SYS$OUTPUT F$LICENSE("ABC","XYZ")
      TRUE

      In the first instance, no license for product ABC is found from
      the default producer (DEC or VSI). In the second instance, an
      ABC PAK is found for producer XYZ.

26  –  F$LOCATE

    Locates a specified portion of a character string and returns as
    an integer the offset of the first character. (An offset is the
    position of a character or a substring relative to the beginning
    of the string. The first character in a string is always offset
    position 0 from the beginning of the string.)

    If the substring is not found, F$LOCATE returns the length (the
    offset of the last character in the character string plus one) of
    the searched string.

    Format

      F$LOCATE(substring,string)

26.1  –  Return Value

    An integer value representing the offset of the substring
    argument. An offset is the position of a character or a substring
    relative to the beginning of the string. The first character in
    a string is always offset position 0 from the beginning of the
    string (which always begins at the leftmost character).
    If the substring is not found, the F$LOCATE function returns
    an offset of the last character in the character string plus 1.
    (This equals the length of the string.)

26.2  –  Arguments

 substring

    Specifies the character string that you want to locate within the
    string specified in the string argument.

 string

    Specifies the character string to be edited by F$LOCATE.

26.3  –  Examples

    1.$ FILE_SPEC = "MYFILE.DAT;1"
      $ NAME_LENGTH = F$LOCATE(".",FILE_SPEC)

      The F$LOCATE function in this example returns the position of
      the period (.)  in the string with respect to the beginning of
      the string. The period is in offset position 6, so the value
      6 is assigned to the symbol NAME_LENGTH. Note that NAME_LENGTH
      also equals the length of the file name portion of the file
      specification MYFILE.DAT, that is, 6.

      The substring argument, the period, is specified as a string
      literal and is therefore enclosed in quotation marks (" ").
      The string argument FILE_SPEC is a symbol, so it should not be
      placed within quotation marks. It is automatically replaced by
      its current value during the processing of the function.

    2.$ INQUIRE TIME "Enter time"
      $ IF F$LOCATE(":",TIME) .EQ. F$LENGTH(TIME) THEN -
        GOTO NO_COLON

      This section of a command procedure compares the results of the
      F$LOCATE and F$LENGTH functions to see if they are equal. This
      technique is commonly used to determine whether a character or
      substring is contained in a string.

      In the example, the INQUIRE command prompts for a time value
      and assigns the user-supplied time to the symbol TIME. The IF
      command checks for the presence of a colon (:)  in the string
      entered in response to the prompt. If the value returned by
      the F$LOCATE function equals the value returned by the F$LENGTH
      function, the colon is not present. You use the .EQ. operator
      (rather than .EQS.) because the F$LOCATE and F$LENGTH functions
      return integer values.

      Note that quotation marks are used around the substring
      argument, the colon, because it is a string literal; however,
      the symbol TIME does not require quotation marks because it is
      automatically evaluated as a string expression.

27  –  F$MATCH_WILD

    Performs a wildcard matching between a candidate and a pattern
    string. TRUE is returned if the strings match.

    Format

      F$MATCH_WILD(candidate, pattern)

27.1  –  Arguments

 candidate

    A string to which the pattern string is compared.

 pattern

    A string on which a wildcard match is performed comparing the
    pattern to the candidate string.

27.2  –  Example

  $ write sys$output f$match_wild ("This is a candidate","*c%%d*")
  TRUE
  $

      This command performs a wildcard match between the candidate
      candidate and pattern *c%%d* and found that the strings match.

  $ write sys$output f$match_wild ("This is a candidate text", "*candi*)
  TRUE
  $

      This command checks to see if the pattern candi appears in the
      candidate.

28  –  F$MESSAGE

    Returns as a character string the facility, severity,
    identification, and text associated with the specified system
    status code.

    Format

      F$MESSAGE(status-code[,message-component-list])

28.1  –  Return Value

    A character string containing the system message that corresponds
    to the argument you specify.

    Note that, although each message in the system message file has
    a numeric value or range of values associated with it, there
    are many possible numeric values that do not have corresponding
    messages. If you specify an argument that has no corresponding
    message, the F$MESSAGE function returns a string containing the
    NOMSG error message.

    For more information on system error messages, see the OpenVMS
    System Messages: Companion Guide for Help Message Users.

28.2  –  Arguments

 status-code

    Specifies the status code for which you are requesting error
    message text. You must specify the status code as an integer
    expression.

 message-component-list

    Specifies the system message component for which information is
    to be returned. If this parameter is null or unspecified, then
    all system message components are returned.

    The following table describes the valid system message component
    keywords:

    Component
    Keyword        Information Returned

    FACILITY       Facility name
    SEVERITY       Severity level indicator
    IDENT          Abbreviation of message text
    TEXT           Explanation of message

    Note that when the FACILITY, SEVERITY, and IDENT code keywords
    are specified (individually or in combination), the resulting
    message code is prefaced with the percent (%)  character. The
    individual parts of the message code are separated by hyphens
    when multiple code keywords are specified.

    When only the TEXT keyword is specified, the resulting text
    is not prefaced with any character. When the TEXT keyword is
    specified with the FACILITY, SEVERITY, or IDENT code keyword,
    the message code is separated from the text by a combination of a
    comma and a blank (,  ).

28.3  –  Example

  $ ERROR_TEXT = F$MESSAGE(%X1C)
  $ SHOW SYMBOL ERROR_TEXT
    ERROR_TEXT = "%SYSTEM-F-EXQUOTA, exceeded quota"

      This example shows how to use the F$MESSAGE function to
      determine the message associated with the status code %X1C.
      The F$MESSAGE function returns the message string, which is
      assigned to the symbol ERROR_TEXT.

  $ SUBMIT IMPORTANT.COM
  $ SYNCHRONIZE /entry='$ENTRY'
  $ IF $STATUS THEN EXIT
  $!
  $ JOB_STATUS = $STATUS
  $!
  $ IF "%JOBDELETE" .EQS. F$MESSAGE (JOB_STATUS, "IDENT")
  $ THEN
         .
             .
             .
  $ ELSE
  $    IF "%JOBABORT" .EQS. F$MESSAGE (JOB_STATUS, "IDENT")
  $    THEN
          .
              .
              .
  $    ELSE
  $       .
              .
              .
  $    ENDIF
  $ ENDIF
    .
    .
    .

      This command procedure submits a batch job and waits for it to
      complete. Upon successful completion, the procedure exits. If
      the job completes unsuccessfully, more processing is done based
      on the termination status of the batch job.

      The first command submits the command procedure IMPORTANT.COM.
      In the second command, the SYNCHRONIZE command tells the
      procedure to wait for the job to finish. The third command
      determines if the job completed successfully and, if so, the
      procedure exits. The next command saves the status in a symbol.

      The first IF statement uses F$MESSAGE to determine whether
      the job was deleted before execution. If so, it does some
      processing, possibly to resubmit the job or to inform a user
      via MAIL.

      The next IF statement uses F$MESSAGE to determine whether the
      job was deleted during execution. As a result, some cleanup or
      human intervention may be required, which would be done in the
      THEN block.

      If neither IF statement was true, then some other unsuccessful
      status was returned. Other processing, which would be done in
      the block following the ELSE statement, might be required.

29  –  F$MODE

    Returns a character string showing the mode in which a process
    is executing. The F$MODE function has no arguments, but must be
    followed by parentheses.

    Format

      F$MODE()

29.1  –  Return Value

    The character string INTERACTIVE for interactive processes.
    If the process is noninteractive, the character string BATCH,
    NETWORK, or OTHER is returned. Note that the return string always
    contains uppercase letters.

29.2  –  Example

  $ IF F$MODE() .NES. "INTERACTIVE" THEN GOTO NON_INT_DEF
  $ INTDEF:         ! Commands for interactive terminal sessions
     .
     .
     .
  $ EXIT
  $ NON_INT_DEF:         !Commands for noninteractive processes
     .
     .
     .

      This example shows the beginning of a login.com file that has
      two sets of initialization commands: one for interactive mode
      and one for noninteractive mode (including batch and network
      jobs). The IF command compares the character string returned
      by F$MODE with the character string INTERACTIVE; if they are
      not equal, control branches to the label NON_INT_DEF. If the
      character strings are equal, the statements following the
      label INTDEF are executed and the procedure exits before the
      statements at NON_INT_DEF.

30  –  F$MULTIPATH

    Valid on Alpha and Integrity server systems only.

    Returns a specified item of information for a specific multipath-
    capable device.

    Format

      F$MULTIPATH(device-name,item,context-symbol)

30.1  –  Return Value

    A character string containing the requested information.

30.2  –  Arguments

 device-name

    Specifies a physical device name or a logical name equated to
    a physical device name. Specify the device name as a character
    string expression.

    After the device-name argument is evaluated, the F$MULTIPATH
    function examines the first character of the name. If the
    first character is an underscore (_), the name is considered a
    physical device name; otherwise, a single level of logical name
    translation is performed and the equivalence name, if any, is
    used.

 item

    Specifies the type of device information to be returned. The
    item argument must be specified as a character string expression.
    Currently, the only valid item is MP_PATHNAME, which returns a
    string with the path name for the specified multipath-capable
    device.

 context-symbol

    Prior to the first use of F$MULTIPATH with MP_PATHNAME, the
    context symbol must be initialized to a value of 0. The
    F$MULTIPATH function is responsible for maintaining the value
    of the context symbol.

                                 CAUTION

       Do not modify the context symbol value after it has been
       initialized to 0; doing so could result in unpredictable
       behavior of F$MULTIPATH.

30.3  –  Example

  $       XYZ = 0
  $
  $LOOP:
  $       PATH = F$MULTIPATH( "$1$DGA12", "MP_PATHNAME", XYZ )
  $       IF PATH .EQS. "" THEN GOTO EXIT
  $       WRITE SYS$OUTPUT "PATH NAME = ''PATH'"
  $       GOTO LOOP
  $
  $EXIT:
  $       EXIT

      This example shows the use of F$MULTIPATH with the MP_
      PATHNAME item code. Note that the context symbol XYZ has been
      initialized to 0 outside of the loop. The output from this
      command procedure is shown below. When all paths for a given
      multipath device have been returned, the end of the list is
      signaled by the return of a blank path name.

        path name = PGA0.5000-1FE1-0001-5782
        path name = PGA0.5000-1FE1-0001-5783
        path name = PGA0.5000-1FE1-0001-5781
        path name = PGA0.5000-1FE1-0001-5784
        path name = MSCP

31  –  F$PARSE

    Parses a file specification and returns either the expanded file
    specification or the particular file specification field that you
    request.

    Format

      F$PARSE(filespec [,default-spec] [,related-spec] [,field]

             [,parse-type])

31.1  –  Return Value

    A character string containing the expanded file specification
    or the field you specify. If you do not provide a complete file
    specification for the filespec argument, the F$PARSE function
    supplies defaults in the return string.

    In most cases, the F$PARSE function returns a null string ("")
    if an error is detected during the parse. For example, a null
    string is returned if the file specification has incorrect
    syntax or if a disk or directory does not exist, making the file
    specification logically incorrect. However, when you specify a
    field name or the SYNTAX_ONLY parse type, F$PARSE returns the
    appropriate information.

31.2  –  Arguments

 filespec

    Specifies a character string containing the file specification to
    be parsed.

    The file specification can contain the asterisk (*)  and the
    percent sign (%) wildcard characters. If you use a wildcard
    character, the file specification returned by the F$PARSE
    function contains the wildcard.

 default-spec

    Specifies a character string containing the default file
    specification.

    The fields in the default file specification are substituted in
    the output string if a particular field in the filespec argument
    is missing. You can make further substitutions in the filespec
    argument by using the related-spec argument.

 related-spec

    Specifies a character string containing the related file
    specification.

    The fields in the related file specification are substituted in
    the output string if a particular field is missing from both the
    filespec and default-spec arguments.

 field

    Specifies a character string containing the name of a field
    in a file specification. Specifying the field argument causes
    the F$PARSE function to return a specific portion of a file
    specification.

    Specify one of the following field names (do not abbreviate):

    NODE       Node name
    DEVICE     Device name
    DIRECTORY  Directory name
    NAME       File name
    TYPE       File type
    VERSION    File version number

 parse-type

    Specifies the type of parsing to be performed. By default,
    the F$PARSE function verifies that the directory in the file
    specification exists on the device in the file specification;
    however, the existence of the directory is not verified if you
    provide a field argument. Note that the device and directory can
    be explicitly given in one of the arguments, or can be provided
    by default.

    Also, by default the F$PARSE function translates logical names if
    they are provided in any of the arguments. The F$PARSE function
    stops iterative translation when it encounters a logical name
    with the CONCEALED attribute.

    You can change how the F$PARSE function parses a file
    specification by using one of the following keywords:

    NO_CONCEAL  Ignores the "conceal" attribute in the translation
                of a logical name as part of the file specification;
                that is, logical name translation does not end when a
                concealed logical name is encountered.
    SYNTAX_     The syntax of the file specification is checked
    ONLY        without verifying that the specified directory exists
                on the specified device.

31.3  –  Examples

    1.$ SET DEF DISK2:[FIRST]
      $ SPEC = F$PARSE("JAMES.MAR","[ROOT]",,,"SYNTAX_ONLY")
      $ SHOW SYMBOL SPEC
        SPEC = "DISK2:[ROOT]JAMES.MAR;"

      In this example, the F$PARSE function returns the expanded
      file specification for the file JAMES.MAR. The example uses
      the SYNTAX_ONLY keyword to request that F$PARSE check the
      syntax, but should not verify that the [ROOT] directory exists
      on DISK2.

      The default device and directory are DISK2:[FIRST]. Because the
      directory name [ROOT] is specified as the default-spec argument
      in the assignment statement, it is used as the directory name
      in the output string. Note that the default device returned
      in the output string is DISK2, and the default version number
      for the file is null. You must place quotation marks (" ")
      around the arguments JAMES.MAR and ROOT because they are string
      literals.

      If you had not specified syntax-only parsing, and [ROOT] were
      not on DISK2, a null string would have been returned.

    2.$ SET DEFAULT DB1:[VARGO]
      $ SPEC = F$PARSE("INFO.COM",,,"DIRECTORY")
      $ SHOW SYMBOL SPEC
        SPEC = "[VARGO]"

      In this example the F$PARSE function returns the directory
      name of the file INFO.COM. Note that because the default-spec
      and related-spec arguments are omitted from the argument list,
      commas (,)  must be inserted in their place.

    3.$ SPEC= F$PARSE("DENVER::DB1:[PROD]RUN.DAT",,,"TYPE")
      $ SHOW SYMBOL SPEC
        SPEC = ".DAT"

      In this example, the F$PARSE function is used to parse a file
      specification containing a node name. The F$PARSE function
      returns the file type .DAT for the file RUN.DAT at the remote
      node DENVER.

32  –  F$PID

    Returns a process identification (PID) number and updates the
    context symbol to point to the current position in the system's
    process list.

    Format

      F$PID(context-symbol)

32.1  –  Return Value

    A character string containing the PID of a process in the
    system's list of processes.

32.2  –  Argument

 context-symbol

    Specifies a symbol that DCL uses to store a pointer into the
    system's list of processes. The F$PID function uses this pointer
    to return a PID.

    Specify the context symbol by using a symbol. The first time you
    use the F$PID function in a command procedure, you should use
    a symbol that is either undefined or equated to the null string
    ("") or a context symbol that has been created by the F$CONTEXT
    function.

    If the context symbol is undefined or equated to a null string,
    the F$PID function returns the first PID in the system's process
    list that it has the privilege to access. That is, if you have
    GROUP privilege and if the context symbol is null or undefined,
    the F$PID function returns the PID of the first process in your
    group. If you have WORLD privilege, the F$PID function returns
    the PID of the first process in the list. If you have neither
    GROUP nor WORLD privilege, the F$PID returns the first process
    that you own. Subsequent calls to F$PID return the rest of the
    processes on the system you are accessing.

    If the context symbol has been created by the F$CONTEXT function,
    the F$PID function returns the first process name in the
    system's process list that fits the criteria specified in the
    F$CONTEXT calls. Subsequent calls to F$PID return only the PIDs
    of those processes that meet the selection criteria set up by
    the F$CONTEXT function and that are accessible to your current
    privileges.

32.3  –  Example

  $ CONTEXT = ""
  $ START:
  $     PID = F$PID(CONTEXT)
  $     IF PID .EQS. "" THEN EXIT
  $     SHOW SYMBOL PID
  $     GOTO START

      This command procedure uses the F$PID function to display a
      list of PIDs. The assignment statement declares the symbol
      CONTEXT, which is used as the context-symbol argument for the
      F$PID function. Because CONTEXT is equated to a null string,
      the F$PID function returns the first PID in the process list
      that it has the privilege to access.

      The PIDs displayed by this command procedure depend on the
      privilege of your process. When run with GROUP privilege, the
      PIDs of users in your group are displayed. When run with WORLD
      privilege, the PIDs of all users on the system are displayed.
      Without GROUP or WORLD privilege, only those processes that you
      own are displayed.

33  –  F$PRIVILEGE

    Returns a string value of either TRUE or FALSE, depending on
    whether your current process privileges match those specified
    in the argument. You can specify either the positive or negative
    version of a privilege.

    Format

      F$PRIVILEGE(priv-states)

33.1  –  Return Value

    A character string containing the value TRUE or FALSE. The
    F$PRIVILEGE function returns the string FALSE if any one of the
    privileges in the priv-states argument list is false.

33.2  –  Arguments

 priv-states

    Specifies a character string containing a privilege, or a list
    of privileges separated by commas (,).  For a list of process
    privileges, see the VSI OpenVMS Guide to System Security. Specify
    any one of the process privileges except [NO]ALL.

33.3  –  Example

  $ PROCPRIV = F$PRIVILEGE("OPER,GROUP,TMPMBX,NONETMBX")
  $ SHOW SYMBOL PROCPRIV
    PROCPRIV = "FALSE"

      The F$PRIVILEGE function is used to test whether the process
      has OPER, GROUP, and TMPMBX privileges and if you do not have
      NETMBX privileges.

      The process in this example has OPER (operator), GROUP, TMPMBX
      (temporary mailbox), and NETMBX (network mailbox) privileges.
      Therefore, a value of FALSE is returned because the process has
      NETMBX privilege, but NONETMBX was specified in the priv-states
      list. Although the Boolean result for the other three keywords
      is true, the entire expression is declared false because the
      result for NONETMBX was false.

34  –  F$PROCESS

    Obtains the current process name string. The F$PROCESS function
    has no arguments, but must be followed by parentheses.

    Format

      F$PROCESS()

34.1  –  Return Value

    A character string containing the current process name.

34.2  –  Example

  $ NAME = F$PROCESS()
  $ SHOW SYMBOL NAME
    NAME = "MARTIN"

      In this example, the F$PROCESS function returns the current
      process name and assigns it to the symbol NAME.

35  –  F$READLINK

    Returns the target file name which is indicated by the
    specified symbolic link, or NULL if the input is not a
    symbolic link.

    Format

      F$READLINK(filespec)

35.1  –  Return Value

    Either the text contents of a symbolic link or NULL if
    the input is not a symbolic link.

35.2  –  Arguments

 filespec

    Specifies the name of the symbolic link file. You must specify
    the file name as a character string expression.

35.3  –  Examples

  1.$ CREATE FILE.TXT
    HELLO EXIT
    $
    $ CREATE/SYMLINK="FILE.TXT" L.LNK
    $ X=F$READLINK("L.LNK")
    $ SH SYM X
      X = "FILE.TXT"
    $

    This example uses the F$READLINK function to return the
    target file name for a specified symbolic link.

  2.$ CREATE FILE.TXT
    HELLO EXIT
    $
    $ CREATE/SYMLINK="FILE.TXT" L.LNK
    $ CREATE/SYMLINK="L.LNK" LINK_TO_LINK.LNK
    $ X= F$READLINK("LINK_TO_LINK.LNK")
    $ SH SYM X
    X = "L.LNK"

    This example shows how F$READLINK functions when the target
    is a symbolic link file.

36  –  F$SEARCH

    Searches a directory file and returns the full file specification
    for a file you specify.

    Format

      F$SEARCH(filespec[,stream-id])

36.1  –  Return Value

    A character string containing the expanded file specification for
    the filespec argument. If the F$SEARCH function does not find the
    file in the directory, the function returns a null string ("").

36.2  –  Arguments

 filespec

    Specifies a character string containing the file specification
    to be searched for. If the device or directory names are omitted,
    the defaults from your current default disk and directory are
    used. The F$SEARCH function does not supply defaults for a file
    name or type. If the version is omitted, the specification for
    the file with the highest version number is returned. If the
    filespec argument contains the asterisk (*)  or the percent
    sign (%)  wildcard characters, each time F$SEARCH is called, the
    next file specification that agrees with the filespec argument
    is returned. A null string is returned after the last file
    specification that agrees with the filespec argument.

 stream-id

    Specifies a positive integer representing the search stream
    identification number.

    The search stream identification number is used to maintain
    separate search contexts when you use the F$SEARCH function
    more than once and when you supply different filespec arguments.
    If you use the F$SEARCH function more than once in a command
    procedure and if you also use different filespec arguments,
    specify stream-id arguments to identify each search separately.

    If you omit the stream-id argument, the F$SEARCH function starts
    searching at the beginning of the directory file each time you
    specify a different filespec argument.

36.3  –  Examples

    1.$ START:
      $     FILE = F$SEARCH("SYS$SYSTEM:*.EXE")
      $     IF FILE .EQS. "" THEN EXIT
      $     SHOW SYMBOL FILE
      $     GOTO START

      This command procedure displays the file specifications of the
      latest version of all .EXE files in the SYS$SYSTEM directory.
      (Only the latest version is returned because an asterisk (*)
      wildcard character is not used as the version number.) The
      filespec argument SYS$SYSTEM:*.EXE is surrounded by quotation
      marks (" ")  because it is a character string expression.

      Because no stream-id argument is specified, the F$SEARCH
      function uses a single search stream. Each subsequent F$SEARCH
      call uses the same filespec argument to return the next file
      specification of an .EXE file from SYS$SYSTEM:. After the
      latest version of each .EXE file has been displayed, the
      F$SEARCH function returns a null string ("")  and the procedure
      exits.

    2.$ START:
      $    COM = F$SEARCH ("*.COM;*",1)
      $    DAT = F$SEARCH ("*.DAT;*",2)
      $    SHOW SYMBOL COM
      $    SHOW SYMBOL DAT
      $    IF (COM.EQS. "") .AND. (DAT.EQS. "") THEN EXIT
      $    GOTO START

      This command procedure searches the default disk and directory
      for both .COM and .DAT files. Note that the stream-id argument
      is specified for each F$SEARCH call so that the context for
      each search is maintained.

      The first F$SEARCH call starts searching from the top of the
      directory file for a file with a type .COM. When it finds a
      .COM file, a pointer is set to maintain the search context.
      When the F$SEARCH function is used the second time, it again
      starts searching from the top of the directory file for a
      file with a type .DAT. When the procedure loops back to the
      label START, the stream-id argument allows F$SEARCH to start
      searching in the correct place in the directory file. After
      all versions of .COM and .DAT files are returned, the procedure
      exits.

    3.$ FILESPEC = F$SEARCH("TRNTO""SMITH SALLY""::DKA1:[PROD]*.DAT")
      $ SHOW SYMBOL FILESPEC
        FILESPEC = "TRNTO"smith password"::DKA1:[PROD]CARS.DAT"

      This example uses the F$SEARCH function to return a file
      specification for a file at a remote node. The access control
      string is enclosed in quotation marks because it is part of
      a character string expression when it is an argument for the
      F$SEARCH function. To include quotation marks in a character
      string expression, you must use two sets of quotation marks.

      Note that, when the F$SEARCH function returns a node name
      containing an access control string, it substitutes the word
      "password" for the actual user password.

37  –  F$SETPRV

    Enables or disables specified user privileges. The F$SETPRV
    function returns a list of keywords indicating user privileges;
    this list shows the status of the specified privileges before
    F$SETPRV was executed.

    Your process must be authorized to set the specified privilege.

    For detailed information on privilege restrictions, see the
    description of the $SETPRV system service in the VSI OpenVMS
    System Services Reference Manual.

    Format

      F$SETPRV(priv-states)

37.1  –  Return Value

    A character string containing keywords for the current process
    privileges before they were changed by the F$SETPRV function.

37.2  –  Argument

 priv-states

    Specifies a character string defining a privilege, or a list of
    privileges separated by commas (,).

    For a list of process privileges, see the OpenVMS User's Manual.

37.3  –  Examples

    1.$ OLDPRIV = F$SETPRV("OPER,NOTMPMBX")
      $ SHOW SYMBOL OLDPRIV
        OLDPRIV = "NOOPER,TMPMBX"

      In this example, the process is authorized to change the OPER
      (operator) and TMPMBX (temporary mailbox) privileges. The
      F$SETPRV function enables the OPER privilege and disables the
      TMPMBX privilege. In addition, the F$SETPRV function returns
      the keywords NOOPER and TMPMBX, showing the state of these
      privileges before they were changed.

      You must place quotation marks (" ")  around the list of
      privilege keywords because it is a string literal.

    2.$ SHOW PROCESS/PRIVILEGE

      05-JUN-2001 15:55:09.60   RTA1:              User: HELRIEGEL

      Process privileges:

      Process rights identifiers:
       INTERACTIVE
       LOCAL

      $ NEWPRIVS = F$SETPRV("ALL, NOOPER")
      $ SHOW SYMBOL NEWPRIVS
        NEWPRIVS = "NOCMKRNL,NOCMEXEC,NOSYSNAM,NOGRPNAM,NOALLSPOOL,
            NOIMPERSONATE,NODIAGNOSE,NOLOG_IO,NOGROUP,NOACNT,NOPRMCEB,
            NOPRMMBX,NOPSWAPM,NOALTPRI,NOSETPRV,NOTMPMBX,NOWORLD,NOMOUNT,
            NOOPER,NOEXQUOTA,NONETMBX,NOVOLPRO,NOPHY_IO,NOBUGCHK,NOPRMGBL,
            NOSYSGBL,NOPFNMAP,NOSHMEM,NOSYSPRV,NOBYPASS,NOSYSLCK,NOSHARE,
            NOUPGRADE,NODOWNGRADE,NOGRPPRV,NOREADALL,NOSECURITY,OPER"
      $ SHOW PROCESS/PRIVILEGE

      05-JUN-2001 10:21:18.32   User: INAZU      Process ID: 00000F24
                                Node: TOKNOW     Process name: "_FTA23:"

      Authorized privileges:
       NETMBX    SETPRV    SYSPRV    TMPMBX

      Process privileges:
       ACNT                 may suppress accounting messages
       ALLSPOOL             may allocate spooled device
       ALTPRI               may set any priority value
       AUDIT                may direct audit to system security audit log
       BUGCHK               may make bug check log entries
       BYPASS               may bypass all object access controls
       CMEXEC               may change mode to exec
       CMKRNL               may change mode to kernel
       DIAGNOSE             may diagnose devices
       DOWNGRADE            may downgrade object secrecy
       EXQUOTA              may exceed disk quota
       GROUP                may affect other processes in same group
       GRPNAM               may insert in group logical name table
       GRPPRV               may access group objects via system protection
       IMPERSONATE          may impersonate another user
       IMPORT               may set classification for unlabeled object
       LOG_IO               may do logical i/o
       MOUNT                may execute mount acp function
       NETMBX               may create network device
       OPER                 may perform operator functions
       PFNMAP               may map to specific physical pages
       PHY_IO               may do physical i/o
       PRMCEB               may create permanent common event clusters
       PRMGBL               may create permanent global sections
       PRMMBX               may create permanent mailbox
       PSWAPM               may change process swap mode
       READALL              may read anything as the owner
       SECURITY             may perform security administration functions
       SETPRV               may set any privilege bit
       SHARE                may assign channels to non-shared devices
       SHMEM                may create/delete objects in shared memory
       SYSGBL               may create systemwide global sections
       SYSLCK               may lock systemwide resources
       SYSNAM               may insert in system logical name table
       SYSPRV               may access objects via system protection
       TMPMBX               may create temporary mailbox
       UPGRADE              may upgrade object integrity
       VOLPRO               may override volume protection
       WORLD                may affect other processes in the world

      Process rights:
       INTERACTIVE
       LOCAL

      System rights:
       SYS$NODE_TOKNOW

      $ NEWPRIVS = F$SETPRV(NEWPRIVS)
      $ SHOW PROCESS/PRIVILEGE

      05-JUN-2001 16:05:07.23   RTA1:              User: JERROM

      Process privileges:
       OPER                 operator privilege

      Process rights identifiers:
       INTERACTIVE
       LOCAL

      In this example, the DCL command SHOW PROCESS/PRIVILEGE is
      used to determine the current process privileges. Note that the
      process has no privileges enabled.

      The F$SETPRV function is then used to process the ALL keyword
      and enable all privileges recording the previous state of each
      privilege in the symbol NEWPRIVS. Next, F$SETPRV processes
      the NOOPER keyword and disables the OPER (operator) privilege,
      recording the previous state of OPER in NEWPRIVS. Note that the
      OPER privilege appears in the returned string twice: first as
      NOOPER and then as OPER.

      Entering the command SHOW PROCESS/PRIVILEGE now shows that the
      current process has all privileges enabled except OPER.

      If the returned string is used as the parameter to F$SETPRV,
      the process has the OPER privilege enabled. This occurs because
      the OPER command was present twice in the symbol NEWPRIVS.
      As a result, F$SETPRV looked at the first keyword NOOPER and
      disabled the privilege. Finally, after processing several other
      keywords in the NEWPRIVS string, the OPER keyword is presented,
      allowing F$SETPRV to enable the OPER privilege.

      If you are using the ALL or NOALL keywords to save your
      current privilege environment, VSI recommends that you perform
      the following procedure to modify the process for a command
      procedure:

        $ CURRENT_PRIVS = F$SETPRV("ALL")
        $ TEMP = F$SETPRV("NOOPER")

      If you use this procedure, you can then specify the following
      command statement at the end of your command procedure so that
      the original privilege environment is restored:

        $ TEMP = F$SETPRV(CURRENT_PRIVS)

    3.$ SAVPRIV = F$SETPRV("NOGROUP")
      $ SHOW SYMBOL SAVPRIV
        SAVPRIV = "GROUP"
      $ TEST = F$PRIVILEGE("GROUP")
      $ SHOW SYMBOL TEST
        TEST = "TRUE"

      In this example, the process is not authorized to change the
      GROUP privilege; however, the F$SETPRV function still returns
      the current setting for the GROUP privilege.

      The F$PRIVILEGE function is used to see whether the process has
      GROUP privilege. The return string, TRUE, indicates that the
      process has GROUP privilege, even though the F$SETPRV function
      attempted to disable the privilege.

38  –  F$STRING

    Returns the string that is equivalent to the specified
    expression.

    Format

      F$STRING(expression)

38.1  –  Return Value

    A character string equivalent to the specified expression.

38.2  –  Argument

 expression

    The integer or string expression to be evaluated.

    If you specify an integer expression, the F$STRING function
    evaluates the expression, converts the resulting integer to
    a string, and returns the result. If you specify a string
    expression, the F$STRING function evaluates the expression and
    returns the result.

    When converting an integer to a string, the F$STRING function
    uses decimal representation and omits leading zeros. When
    converting a negative integer, the F$STRING function places a
    minus sign at the beginning string representation of the integer.

38.3  –  Example

  $ A = 5
  $ B = F$STRING(-2 + A)
  $ SHOW SYMBOL B
    B = "3"

      The F$STRING function in this example converts the result of
      the integer expression (-2 + A) to the numeric string, "3".
      First, the F$STRING function evaluates the expression (-2
      + A). Note that 5, the value of symbol A, is automatically
      substituted when the integer expression is evaluated.

      After the integer expression is evaluated, the F$STRING
      function converts the resulting integer, 3, to the string "3".
      This string is assigned to the symbol B.

39  –  F$SYMLINK_ATTRIBUTES

    Returns attribute information for a specified symbolic link
    file.

    Note that F$SYMLINK_ATTRIBUTES returns information for a
    specified symbolic link file, and not the target of
    the symbolic link. For information about the target file of
    a symbolic link, use F$FILE_ATTRIBUTES.

    Format

      F$SYMLINK_ATTRIBUTES(filespec,item)

39.1  –  Return Value

    Either an integer or a character string, depending on the item
    you request.

39.2  –  Arguments

 filespec

    Specifies the name of the symlink file for which you
    are requesting information. You must specify the file name
    as a character string expression.

    Only one file name can be specified at a time and wildcard
    characters are not allowed.

 item

    Indicates the attribute of the symlink file that must be
    returned. The item argument must be specified as a character
    string expression, and can be any one of the OpenVMS RMS
    field names listed in the following table:

               Return
    Item       Type     Information Returned

    AI         String   TRUE if after-image (AI) journaling is
                        enabled; FALSE if disabled.

    ALQ        Integer  Allocation quantity.

    BDT        String   Backup date/time.

    BI         String   TRUE if before-image (BI) journaling is
                        enabled; FALSE if disabled.

    BKS        Integer  Bucket size.

    BLS        Integer  Block size.

    CBT        String   TRUE if contiguous-best-try; otherwise FALSE.

    CDT        String   Creation date/time.

    CTG        String   TRUE if contiguous; otherwise FALSE.

    DEQ        Integer  Default extension quantity.

    DID        String   Directory ID string.

    DIRECTORY  String   Returns TRUE or FALSE. Returns TRUE if it is
                        a directory.

    DVI        String   Device name string.

    EDT        String   Expiration date/time.

    EOF        Integer  Number of blocks used.

    ERASE      String   TRUE if a file's contents are erased before a
                        file is deleted; otherwise FALSE.

    FFB        Integer  First free byte.

    FID        String   File ID string.

    FILE_      String   Record count and data byte count in the form
    LENGTH_             (n,m), where n is the record count and m is
    HINT                the data byte count. An invalidated count is
                        specified by a -1 for n or m.

    FSZ        Integer  Fixed control area size.

    GBC        Integer  Global buffer count.

    GBC32      Integer  Enhanced longword version of global buffer
                        count with a per-file maximum size of about
                        2.1 billion for indexed files.

    GBCFLAGS   String   Per-file management flags for sizing of
                        global buffer cache. Returns PERCENT if
                        global buffer count is expresses as a
                        percent, DEFAULT if global buffer size is
                        determined at runtime by an algorithm using
                        two global buffer SYSGEN parameters (GB_
                        CACHEALLMAX and GB_DEFPERCENT); or NONE if no
                        per-file management flags are enabled for the
                        file.
    GRP        Integer  Owner group number.

    JOURNAL_   String   TRUE if the file is a journal; otherwise
    FILE                FALSE.

    KNOWN      String   Known file; returns TRUE or FALSE to
                        indicate whether file is installed with the
                        Install utility (INSTALL). However, returns
                        NOSUCHFILE if a file does not exist (for
                        example, the file has been installed but
                        subsequently deleted).

    LOCKED     String   TRUE if a file is deaccessed-locked;
                        otherwise FALSE.

    LRL        Integer  Longest record length.

    MBM        Integer  Owner member number.

    MOVE       String   TRUE if movefile operations are enabled;
                        otherwise FALSE.

    MRN        Integer  This is not applicable.

    MRS        Integer  Maximum record size.

    NOA        Integer  This is not applicable.

    NOBACKUP   String   FALSE if the file is marked for backup; TRUE
                        if the file is marked NOBACKUP.

    NOK        Integer  This is not applicable.

    ORG        String   File organization; returns SEQ, REL, IDX.

    PRESHELVED String   TRUE if the file is preshelved; otherwise
    (Alpha/Integrity    FALSE.
    servers
    only)

    PRO        String   File protection string.

    PVN        Integer  This is not applicable.

    RAT        String   Record attributes; returns CR, PRN, FTN, "".

    RCK        String   TRUE if read check; otherwise FALSE.

    RDT        String   Revision date/time.

    RFM        String   Record format string; returns the values VAR,
                        FIX, VFC, UDF, STM, STMLF, STMCR.

    RU         String   TRUE if recovery unit (RU) journaling is
                        enabled; returns TRUE or FALSE.

    RVN        Integer  Revision number.

    SHELVABLE  String   TRUE if the file is shelvable; otherwise
                        FALSE.

    SHELVED    String   TRUE if the file is shelved; otherwise FALSE.

    STORED_    String   ASCII string that represents stored
    SEMANTICS           semantics.

    UIC        String   Owner user identification code (UIC) string.

    VERLIMIT   Integer  Version limit number. The value 32767
                        indicates that no version limit was set.

    WCK        String   TRUE if write check; otherwise FALSE.

39.3  –  Example

   $ DIR/LINK/FILE
     Directory SYS$SYSDEVICE:[EXAMPLES]

     TARGET.TXT;1                (5601,12,0)
     FOO.LNK;1 -> TARGET.TXT     (5600,12,0)
     Total of 2 files.

     $ FID_FILE = F$FILE_ATTRIBUTES("FOO.LNK","FID")
     $ FID_SYM  = F$SYMLINK_ATTRIBUTES("FOO.LNK","FID")

     $ SHOW SYMBOL FID_FILE
     FID_FILE = "(5601,12,0)"

     $ SHOW SYMBOL FID_SYM
     FID_SYM = "(5600,12,0)"

     This example uses the F$SYMLINK_ATTRIBUTES function to
     return information about the symbolic link file FOO.LNK.

40  –  F$TIME

    Returns the current date and time in absolute time format.

    The F$TIME function has no arguments, but must be followed by
    parentheses.

    Format

      F$TIME()

40.1  –  Return Value

    A character string containing the current date and time. The
    returned string has the following fixed, 23-character format:

    dd-mmm-yyyy hh:mm:ss.cc

    When the current day of the month is any of the values 1 to 9,
    the first character in the returned string is a blank character.
    The time portion of the string is always in character position
    13, at an offset of 12 characters from the beginning of the
    string.

    Note that you must use the assignment operator (=)  to preserve
    the blank character in the returned string. If you use the string
    assignment operator (:=),  the leading blank is dropped.

40.2  –  Example

  $ OPEN/WRITE OUTFILE DATA.DAT
  $ TIME_STAMP = F$TIME()
  $ WRITE OUTFILE TIME_STAMP

      This example shows how to use the F$TIME function to time-stamp
      a file that you create from a command procedure. OUTFILE is
      the logical name for the file DATA.DAT, which is opened for
      writing. The F$TIME function returns the current date and time
      string, and assigns this string to the symbol TIME_STAMP. The
      WRITE command writes the date and time string to OUTFILE.

41  –  F$TRNLNM

    Translates a logical name and returns the equivalence name string
    or the requested attributes of the logical name specified.

    Format

      F$TRNLNM(logical-name [,table] [,index] [,mode] [,case]

              [,item])

41.1  –  Return Value

    The equivalence name or attribute of the specified logical
    name. The return value can be a character string or an integer,
    depending on the arguments you specify with the F$TRNLNM
    function. If no match is found, a null string ("")  is returned.

41.2  –  Arguments

 logical-name

    Specifies a character string containing the logical name to be
    translated.

 table

    Specifies a character string containing the logical name table
    or tables that the F$TRNLNM function should search to translate
    the logical name. The table argument must be a logical name that
    translates to a logical name table or to a list of table names.

    A logical name for a logical name table must be defined in one of
    the following logical name tables:

    o  LNM$SYSTEM_DIRECTORY

    o  LNM$PROCESS_DIRECTORY

                                   NOTE

       If you subsequently create a table using the CREATE/NAME_
       TABLE command and want to make your private table accessible
       for F$TRNLNM, you must redefine one of the table logical
       names to include your private table. To see all the tables
       that are normally searched by F$TRNLNM, issue the following
       command:

       $ SHOW LOGICAL/STRUCTURE LNM$DCL_LOGICAL

       For more information, see the CREATE/NAME_TABLE amd SHOW
       LOGICAL commands.

    If you do not specify a table, the default value is LNM$DCL_
    LOGICAL. That is, the F$TRNLNM function searches the tables whose
    names are equated to the logical name LNM$DCL_LOGICAL. Unless
    LNM$DCL_LOGICAL has been redefined for your process, the F$TRNLNM
    function searches the process, job, group, and system logical
    name tables, in that order, and returns the equivalence name for
    the first match found.

 index

    Specifies the number of the equivalence name to be returned if
    the logical name has more than one translation. The index refers
    to the equivalence strings in the order the names were listed
    when the logical name was defined.

    The index begins with zero; that is, the first name in a list of
    equivalence names is referenced by the index zero.

    If you do not specify the index argument, the default is zero.

 mode

    Specifies a character string containing one of the following
    access modes for the translation: USER (default), SUPERVISOR,
    EXECUTIVE, or KERNEL.

    The F$TRNLNM function starts by searching for a logical name
    created with the access mode specified in the mode argument. If
    it does not find a match, the F$TRNLNM function searches for the
    name created with each inner access mode and returns the first
    match found. For example, two logical names can have the same
    name, but one name can be created with user access mode and the
    other name with executive access mode. If the mode argument is
    USER, the F$TRNLNM function returns the equivalence string for
    the user-mode, not the executive-mode, logical name.

 case

    Specifies the type of translation to be performed. The case
    argument controls both the case of the translation and whether
    the translation is to be interlocked or noninterlocked.

    You can specify the case argument as any combination of CASE_
    BLIND (default), CASE_SENSITIVE, NONINTERLOCKED (default), and
    INTERLOCKED.

    If the translation is case blind, the F$TRNLNM searches the
    logical name table for the first occurrence of the logical name,
    regardless of the case, and returns the translation. If no match
    is found for either case, the function returns a null string
    ("").

    If the translation is case sensitive, the F$TRNLNM function
    searches only for a logical name with characters of the same
    case as the logical-name argument. If no exact match is found,
    the F$TRNLNM function returns a null string ("").

    If the translation is interlocked, the F$TRNLNM function does
    not take effect until all clusterwide logical name modifications
    in progress complete. Then, if a match is found, the result of
    the translation is returned. If no match is found, the F$TRNLNM
    function returns a null string ("").

    If the translation is noninterlocked, the F$TRNLNM function
    takes effect immediately. If a match is found, the result of
    the translation is returned. If no match is found, the F$TRNLNM
    function returns a null string ("").

 item

    Specifies a character string containing the type of information
    that F$TRNLNM should return about the specified logical name.
    Specify one of the following items:

                Return
    Item        Type      Information Returned

    ACCESS_     String    One of the following access modes
    MODE                  associated with the logical name: USER,
                          SUPERVISOR, EXECUTIVE, KERNEL.

    CLUSTERWIDE String    TRUE or FALSE to indicate whether the
                          logical name is in a clusterwide name
                          table.

    CONCEALED   String    TRUE or FALSE to indicate whether the
                          CONCEALED attribute was specified with
                          the /TRANSLATION_ATTRIBUTES qualifier when
                          the logical name was created. The CONCEALED
                          attribute is used to create a concealed
                          logical name.

    CONFINE     String    TRUE or FALSE to indicate whether the
                          logical name is confined. If the logical
                          name is confined (TRUE), then the name is
                          not copied to subprocesses. If the logical
                          name is not confined (FALSE), then the name
                          is copied to subprocesses.

    CRELOG      String    TRUE or FALSE to indicate whether the
                          logical name was created with the $CRELOG
                          system service or with the $CRELNM system
                          service, using the CRELOG attribute.

                          If the logical name was created with the
                          $CRELOG system service or with the $CRELNM
                          system service, using the CRELOG attribute,
                          then TRUE is returned. Otherwise, FALSE is
                          returned.

    LENGTH      Integer   Length of the equivalence name associated
                          with the specified logical name. If the
                          logical name has more than one equivalence
                          name, the F$TRNLNM function returns the
                          length of the name specified by the index
                          argument.

    MAX_INDEX   Integer   The largest index defined for the logical
                          name. The index shows how many equivalence
                          names are associated with a logical name.
                          The index is zero based; that is, the index
                          zero refers to the first name in a list of
                          equivalence names.

    NO_ALIAS    String    TRUE or FALSE to indicate whether the
                          logical name has the NO_ALIAS attribute.
                          The NO_ALIAS attribute means that a logical
                          name must be unique within outer access
                          mode.

    TABLE       String    TRUE or FALSE to indicate whether the
                          logical name is the name of a logical name
                          table.

    TABLE_NAME  String    Name of the table where the logical name
                          was found.

    TERMINAL    String    TRUE or FALSE to indicate whether the
                          TERMINAL attribute was specified with the
                          /TRANSLATION_ATTRIBUTES qualifier when the
                          logical name was created. The TERMINAL
                          attribute indicates that the logical
                          name is not a candidate for iterative
                          translation.

    VALUE       String    Default. The equivalence name associated
                          with the specified logical name. If the
                          logical name has more than one equivalence
                          name, the F$TRNLNM function returns the
                          name specified by the index argument.

41.3  –  Examples

    1.$ SAVE_DIR = F$TRNLNM("SYS$DISK")+F$DIRECTORY()
         .
         .
         .
      $ SET DEFAULT 'SAVE_DIR'

      The assignment statement concatenates the values returned
      by the F$DIRECTORY and F$TRNLNM functions, and assigns the
      resulting string to the symbol SAVE_DIR. The symbol SAVE_DIR
      consists of a full device and directory name string.

      The argument SYS$DISK is enclosed in quotation marks ("")
      because it is a character string. (The command interpreter
      treats all arguments that begin with alphabetic characters
      as symbols or lexical functions, unless the arguments are
      enclosed in quotation marks.) None of the optional arguments
      is specified, so the F$TRNLNM function uses the defaults.

      At the end of the command procedure, the original default
      directory is reset. When you reset the directory, you must
      place single quotation marks (` ')  around the symbol SAVE_DIR
      to force symbol substitution.

    2.$ DEFINE/TABLE=LNM$GROUP TERMINAL 'F$TRNLNM("SYS$OUTPUT")'

      This example shows a line from a command procedure that (1)
      uses the F$TRNLNM function to determine the name of the current
      output device and (2)  creates a group logical name table entry
      based on the equivalence string.

      You must enclose the argument SYS$OUTPUT in quotation marks
      because it is a character string.

      Also, in this example you must enclose the F$TRNLNM function
      in single quotation marks to force the lexical function to be
      evaluated; otherwise, the DEFINE command does not automatically
      evaluate the lexical function.

    3.$ RESULT= -
      _$ F$TRNLNM("INFILE","LNM$PROCESS",0,"SUPERVISOR",,"NO_ALIAS")
      $ SHOW SYMBOL RESULT
        RESULT = "FALSE"

      In this example, the F$TRNLNM function searches the process
      logical name table for the logical name INFILE. The function
      starts the search by looking for the logical name INFILE
      created in supervisor mode. If no match is found, the function
      looks for INFILE created in executive mode.

      When a match is found, the F$TRNLNM function determines whether
      the name INFILE was created with the NO_ALIAS attribute. In
      this case, the NO_ALIAS attribute is not specified.

    4.$ foo=f$trnlnm("FOO","LNM$SYSCLUSTER",,,"INTERLOCKED",)

      In this example, logical name FOO is translated in the
      LNM$SYSCLUSTER table in an interlocked manner; that is, all
      clusterwide logical name modifications in progress on this
      and other nodes are completed before the translation occurs.
      This ensures that the translation is based on the most recent
      definition of FOO.

      Because the case translation is not specified, the translation
      is by default CASE_BLIND.

    5.$ foo=f$trnlnm("FOO","LNM$SYSCLUSTER",,,"INTERLOCKED,CASE_SENSITIVE",)

      This example specifies both case sensitive and interlocked
      translation.

42  –  F$TYPE

    Returns the data type of a symbol. The string INTEGER is returned
    if the symbol is equated to an integer, or if the symbol is
    equated to a string whose characters form a valid integer.

    The string STRING is returned if the symbol is equated to a
    character string whose characters do not form a valid integer.

    If the symbol is undefined, a null string ("")  is returned.

    Format

      F$TYPE(symbol-name)

42.1  –  Return Value

    The string INTEGER is returned if the symbol is equated to an
    integer, or if the symbol is equated to a string whose characters
    form a valid integer.

    If the symbol has been produced by a call to the F$CONTEXT
    function with a context type of PROCESS or by a call to the
    F$PID function, the string returned is PROCESS_CONTEXT. A symbol
    retains this type until F$CONTEXT is called with the symbol and
    the CANCEL keyword, or until a null string ("")  is returned by a
    call to F$PID.

    Similarly, the return value is the string CLUSTER_SYSTEM_CONTEXT
    for symbols created by the F$CSID function.

    If the symbol is a context symbol, then the return value will be
    one of the types shown in the following table.

    Symbol Type          Lexical Creating Symbol

    PROCESS_CONTEXT      F$PID or F$CONTEXT (with PROCESS context
                         type)

    CLUSTER_SYSTEM_      F$CSID
    CONTEXT

    The string STRING is returned if the symbol is equated to a
    character string whose characters do not form a valid integer
    or whose type is not a context.

    If the symbol is undefined, a null string is returned.

42.2  –  Argument

 symbol-name

    Specifies the name of the symbol to be evaluated.

42.3  –  Examples

    1.$ NUM = "52"
      $ TYPE = F$TYPE(NUM)
      $ SHOW SYMBOL TYPE
        TYPE = "INTEGER"

      This example uses the F$TYPE function to determine the data
      type of the symbol NUM. NUM is equated to the character
      string "52". Because the characters in the string form a valid
      integer, the F$TYPE function returns the string INTEGER.

    2.$ NUM = 52
      $ TYPE = F$TYPE(NUM)
      $ SHOW SYMBOL TYPE
        TYPE = "INTEGER"

      In this example, the symbol NUM is equated to the integer 52.
      The F$TYPE function shows that the symbol has an integer data
      type.

    3.$ CHAR = "FIVE"
      $ TYPE = F$TYPE(CHAR)
      $ SHOW SYMBOL TYPE
        TYPE = "STRING"

      In this example, the symbol CHAR is equated to the character
      string FIVE. Because the characters in this string do not form
      a valid integer, the F$TYPE function shows that the symbol has
      a string value.

    4.$ x = F$CONTEXT("PROCESS",CTX,"USERNAME","SMITH")
      $ TYPE = F$TYPE(CTX)
      $ SHOW SYMBOL TYPE
        TYPE = "PROCESS_CONTEXT"
      $ x = F$CONTEXT("PROCESS",CTX,"CANCEL")
      $ TYPE = F$TYPE(CTX)
      $ SHOW SYMBOL TYPE
        TYPE = ""

      In this example, the F$TYPE function returns the string
      PROCESS_CONTEXT because the symbol has been produced by a call
      to the F$CONTEXT function with a context type of PROCESS. The
      symbol returns this type until F$CONTEXT is called with the
      symbol and the selection-item argument value CANCEL.

43  –  F$UNIQUE

    Valid on Alpha and Integrity server systems only.

    Generates a string that is suitable to be a file name and is
    guaranteed to be unique across the cluster. Unique file names can
    be useful when creating temporary files.  The string returned
    is alphanumeric and may be used as a file name, logical name,
    or DCL symbol name or value with no reserved character issues.

    The F$UNIQUE function has no arguments, but must be followed by a
    blank pair of parentheses.

    Format

      F$UNIQUE()

43.1  –  Return Value

    A character string containing the unique string.

43.2  –  Examples

    1.$ WRITE SYS$OUTPUT F$UNIQUE()
      414853555241159711D7DF797CCF573F
      $
      $ WRITE SYS$OUTPUT F$UNIQUE()
      414853555241509811D7DF797E3F2777
      $

      This example shows how a unique string is returned on
      subsequent WRITE commands.

    2.$ OPEN/WRITE TEMP_FILE 'F$UNIQUE()
      $ DIRECTORY

      Directory WORK1:[TEST]

      594B53554C421C9C11D75463D61F58B7.DAT;1

      Total of 1 file.
      $
      $ CLOSE/DISPOSITION=DELETE TEMP_FILE
      $ DIRECTORY
      %DIRECT-W-NOFILES, no files found
      $

      The first command creates a temporary file and gives it a
      unique name, which is displayed by the subsequent DIRECTORY
      command. After the file is later closed and deleted, it no
      longer shows up in the directory.

44  –  F$USER

    Returns the current user identification code (UIC) in named
    format as a character string. The F$USER function has no
    arguments, but must be followed by parentheses.

    Format

      F$USER()

44.1  –  Return Value

    A character string containing the current UIC, including brackets
    ([ ]).  The UIC is returned in the format [group-identifier,
    member-identifier].

44.2  –  Example

  $ UIC = F$USER()
  $ SHOW SYMBOL UIC
    UIC = "[GROUP6,JENNIFER]"

      In this example, the F$USER function returns the current user
      identification code and assigns it to the symbol UIC.

45  –  F$VERIFY

    Returns an integer value indicating whether the procedure
    verification setting is currently on or off. If used with
    arguments, the F$VERIFY function can turn the procedure and image
    verification settings on or off. You must include the parentheses
    after the F$VERIFY function whether or not you specify arguments.

    Format

      F$VERIFY([procedure-value] [,image-value])

45.1  –  Return Value

    The integer 0 if the procedure verification setting is off, or
    the integer 1 if the procedure verification setting is on.

45.2  –  Arguments

 procedure-value

    Specifies an integer expression with a value of 1 to turn
    procedure verification on, or a value of 0 to turn procedure
    verification off.

    When procedure verification is on, each DCL command line in the
    command procedure is displayed on the output device. Procedure
    verification allows you to verify that each command is executing
    correctly.

    If you use the procedure-value argument, the function first
    returns the current procedure verification setting. Then the
    command interpreter turns the procedure verification on or off,
    as specified by the argument.

 image-value

    Specifies an integer expression with a value of 1 to turn image
    verification on, or a value of 0 to turn image verification off.

    When image verification is on, data lines in the command
    procedure are displayed on the output device.

45.3  –  Examples

    1.$ SAVE_PROC_VERIFY = F$ENVIRONMENT("VERIFY_PROCEDURE")
      $ SAVE_IMAGE_VERIFY = F$ENVIRONMENT("VERIFY_IMAGE")
      $ SET NOVERIFY
         .
         .
         .
      $ TEMP = F$VERIFY(SAVE_PROC_VERIFY, SAVE_IMAGE_VERIFY)

      This example shows an excerpt from a command procedure. The
      first assignment statement assigns the current procedure
      verification setting to the symbol SAVE_PROC_VERIFY. The second
      assignment statement assigns the current image verification
      setting to the symbol SAVE_IMAGE_VERIFY.

      Then, the SET NOVERIFY command disables procedure and image
      verification. Later, the F$VERIFY function resets the
      verification settings, using the original values (equated to
      the symbols SAVE_PROC_VERIFY and SAVE_IMAGE_VERIFY). The symbol
      TEMP contains the procedure verification before it is changed
      with the F$VERIFY function. (In this example, the value of TEMP
      is not used.)

    2.$ VERIFY = F$VERIFY(0)
         .
         .
         .
       $ IF VERIFY .EQ. 1 THEN SET VERIFY

      This example shows an excerpt from a command procedure that
      uses the F$VERIFY function to save the current procedure
      verification setting and to turn both procedure and image
      verification off. At the end of the command procedure, if
      procedure verification was originally on, both the procedure
      and image verification are turned on.
Close Help