===== Catalog of DCL Lexical Functions =====

The DCL ''HELP'' facility entries for ''Lexicals'' (all the F$* Lexical Functions) is organized alphabetically, not by function or category.  Here's another way of listing these Lexicals, this time by category (roughly, by function).

==== String ====

  F$INTEGER( arg )
    Converts its argument to an actual 32-bit integer, if possible.
    The argument can be a string of characters which represents an
    integer value, or an integer expression.

  F$EDIT( string, edit-values )
    Edits (alters) a string of characters according to a list of
    edit values: COMPRESS, COLLAPSE, TRIM, UPCASE, LOWERCASE, UNCOMMENT.

  F$ELEMENT( elem-number, delim-char, string )
    Extracts an element (character-delimited or -separated substring)
    from a string of characters.

  F$EXTRACT( start-pos, length, string )
    Extracts a substring by start-position and length from a string.

  F$FAO( control-string, arg [ , arg ...] )
    "Formatted ASCII Output", provides advanced output string formatting
    (comparable to the C-lib sprintf function).

  F$LENGTH( string )
    Returns the length (as an integer) of a string of characters.

  F$LOCATE( substring, string )
    Returns the position (as an integer) of a substring within a character
    string, or the length of the string if substring not found.

  F$PARSE( filespec [ , default-spec ] [ , related-spec ]
           [ , field ] [ , parse-type ] )
    Parses a file specification, returning either the expanded full file
    specification or a particular filespec component requested.  Uses
    the RMS $PARSE system service.

==== Integer====

  F$STRING( arg )
    Converts its argument to a string of characters, if possible.
    The argument can be integer value or an integer expression.

  F$CVSI( start-bit-offset, size-in-bits, string )
    Extracts bit fields from character string data and converts
    the result to an integer as a signed value.

  F$CVUI( start-bit-offset, size-in-bits, string  )
    Extracts bit fields from character string data and converts
    the result to an integer as an unsigned value.

==== Date & Time ====

  F$TIME()
    Takes no argument; returns the current system date and time as a string.

  F$CVTIME( input-time [ , output-time-format ] [ , output-field ] )
    Reformats datetime strings into absolute, delta or combination
    formats, and retrieves field-information from a datetime value.

  F$DELTA_TIME( start-time, end-time, format )
    Returns the time difference (an interval) between a given start
    time and an end time.

==== Process Info ====

  F$GETJPI( pid, item )
    Returns a specified item of information about the current process
    including identification, status and accounting information; with
    privilege, can return same information for another process on the
    system.  Uses the system service $GETJPI.

  F$DIRECTORY()
    Takes no argument; returns the current default directory name (string)
    for the process.

  F$ENVIRONMENT( item )
    Returns information about the current process's DCL command environment.

  F$IDENTIFIER( identifier, conversion-type )
    Converts a rights-list identifier in named format to its integer equivalent,
    or vice versa.

  F$MESSAGE( status-code [ , message-component-list ] )
    Returns the message text associated with a specified system status code value.

  F$MODE()
    Takes no argument; returns the process's execution mode, one of:
    "INTERACTIVE", "BATCH", "NETWORK" or "OTHER".

  F$PRIVILEGE( priv-list )
    Returns a TRUE if the current process privileges match (include) the privileges
    listed in the argument; returns FALSE otherwise.

  F$PROCESS()
    Takes no argument; returns the current process name string.

  F$SETPRV( priv-list )
    Sets (enables) the specified privileges in the current process, and returns
    a list of keywords indicating the previous state of the privileges.

  F$TRNLNM( logical-name [ , table ] [ , index ] [ , mode ] [ , case ] [ , item ] )
    Translates a logical name and returns the equivalence name string and/or the
    requested attributes of the logical name.

  F$USER()
    Takes no argument; returns the current process's user identification code (UIC).

==== File System Info ====

  F$SEARCH( filespec [ , stream-id ] )
    Searches for a specified file, returning the full file specification
    if the file exists, or an empty string "" otherwise.  Can search for
    files based on wildcards and through multiple directories and levels.

  F$FILE_ATTRIBUTES( filespec, item )
    Returns file attribute (metadata) information for a specified file.

  F$MATCH_WILD( candidate, pattern )
    Performs a wildcard matching between a candidate and a pattern string.

  F$CUNITS( integer, [, from-units, to-units ] )
    Converts a number from one specified unit of measure
    to another (e.g., "BLOCKS" to "BYTES", and visa versa)

  F$UNIQUE()
    Takes no argument; generates a string that is suitable to be a file name
    and is guaranteed to be unique across the cluster.

  F$FID_TO_NAME( dev-name, file-id )
    Alpha/Integrity only.  Returns the full file specification of the
    file corresponding to a unique file identification (FID).

  F$READLINK( filespec )
    Returns the target file name which is indicated (linked to) by the
    specified symbolic link, or an empty string "" if the input is not
    a symbolic link.

  F$SYMLINK_ATTRIBUTES( filespec, item )
    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 link's target file, use F$FILE_ATTRIBUTES.

  F$GETENV( env-var-name )
    Alpha only.  Returns values of specified Alpha console
    environment variables.

====Device Info ====

  F$GETDVI( dev-name, item [ , path-name ] )
    Returns a specified item of information about a specific device
    (disk, tape, terminal, network device, etc.).  Uses the system
    service $GETDVI.

  F$DEVICE( [ search-devname ] [ , dev-class ] [ , dev-type ] [ , stream-id ] )
    Returns the device names of all devices (disks, tapes, terminals,
    network devices, etc.) that match the selection criteria.

  F$MULTIPATH( dev-name, item, ctxt-symbol )
    Alpha/Integrity only.  Returns specific item of information about
    a specific multipath-capable device.

==== System Info ====

  F$GETSYI( item [ , node-name ] [ , cluster-id ] )
    Returns a specified item of information about the local system
    environment, or about a node (system) in the local VMScluster.
    Uses the system service $GETSYI.

  F$GETQUI( function [ , item ] [ , object-id ] [ , flags ] )
    Returns a specified item of information about queues, batch
    or print jobs currently queued, forms and characteristics
    definitions for queues.  Uses the system service $GETQUI.

  F$LICENSE( license-name [ , producer-name ] )
    Alpha/Integrity only.  Checks whether the specified license is
    loaded on the system.

  F$PID( ctxt-symbol )
    For each invocation, returns the next process identification number
    in sequence.  See F$CONTEXT below.

  F$CONTEXT( ctxt-type, ctxt-symbol, sel-item, sel-value, value-qual )

    Specifies process selection criteria for use with F$PID (see above).

  F$CSID( ctxt-symbol )
    Returns an OpenVMS Cluster identification number and
    updates the context symbol to point to the current
    position in the systems cluster node list.

==== Miscellaneous ====

  F$TYPE( symbol-name )
    Returns the type of data of a specified DCL symbol, one of:
    "STRING", "INTEGER", or "" if the symbol is undefined.

  F$VERIFY( [ procedure-value ] [ , image-value ] )
    Returns the integer 1 (TRUE) if command procedure verification is set on;
    returns the integer 0 (FALSE) if command procedure verification is set off.
    Also sets or toggles a new verification state based on its argument.

===== See Also... =====

For examples of other DCL Lexical Functions in use, see:

  * [[Symbol Substitution#String Substitution Examples]] for two uses of ''F$GETDVI''.

  * [[Command File Parameters#But My Script Needs More Than 8 Parameters]] for use of ''F$ELEMENT'' and ''F$EDIT''.

  * [[Global and Local Symbol Assignment#Demonstrating Command Procedure Depth]] for an example of using ''F$ENVIRONMENT("DEPTH")''.