===== DCL Lexical Functions =====

DCL Lexical Functions are a group of //built-in functions//, part of DCL itself, which return information (data) about DCL values, your (interactive or batch) process, and/or the VMS system environment itself.

There are 45 Lexical Functions (as of VMS v8.4 and prior), and each is conventionally named with the characters ''F$'' as prefix to the function's descriptive name; e.g., ''F$SEARCH'', ''F$GETJPI'', ''F$EDIT'', etc.

You can use these Lexical Functions in command files (scripts, the typical use), or even interactively on the command line itself to experiment and see what each one does.  Lexical Functions are an essential DCL coders' resource, and allow your command files to be written to be general purpose and powerful.

==== Getting Help on Lexical Functions ====

If you try to look for DCL help on any of these Lexical Functions like this:

<code>
$ HELP F$EDIT
</code>

...you'll be disappointed with an warning message like this:

<code>
  Sorry, no documentation on F$EDIT

  Additional information available:

  :=         =          @          ABS        ACCOUNTING ACL_Editor ...
  ALLOCATE   ANALYZE    APPEND     ASSIGN     ATTACH  ...

Topic?
</code>

The trick is to know that you need to get ''HELP'' on the ''Lexicals'' topic itself, so:

<code>
$ HELP LEX F$EDIT
   (...displays the help-text for the F$EDIT lexical function...)
</code>

...or just:
<code>
$ HELP LEXICALS

Lexicals

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

  Additional information available:

  F$CONTEXT  F$CSID    F$CUNITS    F$CVSI   F$CVTIME ...
  (...displays the complete list of lexical functions...)
</code>

The HELP Lexicals entry lists the Lexical Functions alphabetically, which may not be particularly helpful in learning them.  See the wiki article [[Catalog of DCL Lexical Functions]] for a category/functional list of these Lexicals.

==== Experimenting With and Learning Lexical Functions ====

It's easy to play with and learn most of the Lexical Functions on the DCL command line (a few are truly designed for best-use in command files).

First, for brevity, let's create a shorthand command alias (symbol) for the longer/hard-to-type command "''WRITE SYS$OUTPUT''" (and put the following global symbol definition in your own ''SYS$LOGIN:LOGIN.COM'' file, if you like):

<code>
$ wso == "WRITE sys$output"   ! you might prefer another alias name, like "say" or "out"...
$ ! Now we can just do this:
$ wso "This is a test!"
This is a test!
$
</code>

Now you can do things like this:
<code>
$ wso F$TIME()
20-NOV-2018 15:33:43.06
$
</code>

...or:
<code>
$ string = "test"
$ wso F$LOCATE( string, "This is a test..." )
10
$ ! The substring "test" is found at location/position 10 in the larger string.
$ ! Position 0 is the first character of that string.
</code>

<code>
$ wso 
$ wso F$TRNLNM( "SYS$DISK" )
DSA2:
$ wso F$DIRECTORY()
[LRICKER]
$ wso F$SEARCH( "LOGIN*.COM" )
DSA2:[LRICKER]LOGIN.COM;10
$
</code>

<code>
$ wso F$MODE()
INTERACTIVE
$
</code>

<code>
$ wso  F$TRNLNM( "SYS$SYSDEVICE", "LNM$SYSTEM_TABLE" )
$32$DKA0:
$
</code>

<code>
$ fname = "SYS$LOGIN:LOGIN.COM"
$ wso F$PARSE( fname, , , "NAME", "SYNTAX_ONLY") + F$PARSE( fname, , , "TYPE", "SYNTAX_ONLY" )
LOGIN.COM
$
</code>

<code>
$ start = F$TIME()
$ ! ...wait a bit...
$ !    ...dum-de-dum...
$
$ wso F$DELTA_TIME( start, F$TIME(), "DCL")
0-00:00:21.07
$ ! Twenty-one seconds later!...
</code>

===== 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")''.