 |
HP OpenVMS DCL Dictionary
HP OpenVMS DCL Dictionary
F$STRING
Returns the string that is equivalent to the specified expression.
Format
F$STRING (expression)
Return Value
A character string equivalent to the specified expression.
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.
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.
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()
Return Value
A character string containing the current date and time. The returned
string has the following fixed, 23-character format:
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.
Arguments
None.
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.
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])
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.
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:
- LNM$SYSTEM_DIRECTORY
- 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:
| Item |
Return Type |
Information Returned |
|
ACCESS_MODE
|
String
|
One of the following access modes 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.
|
Description
The lexical function F$TRNLNM uses the $TRNLNM system service to
translate a logical name and return the equivalence name string, or the
requested attributes of the logical name specified. The translation is
not iterative; the equivalence string is not checked to determine
whether it is a logical name.
When you use the F$TRNLNM function, you can omit optional arguments
that can be used to the right of the last argument you specify.
However, you must include commas (,) as placeholders if you omit
optional arguments to the left of the last argument that you specify.
You can use the F$TRNLNM function in command procedures to save the
current equivalence of a logical name and later restore it. You can
also use it to test whether logical names have been assigned.
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.
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)
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 Table DCLI-12.
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.
Argument
symbol-name
Specifies the name of the symbol to be evaluated.
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.
F$UNIQUE (Alpha 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. (See CLOSE/DISPOSITION for an example.)
The F$UNIQUE function has no arguments, but must be followed by a blank
pair of parentheses.
Format
F$UNIQUE()
Return Value
A character string containing the unique string.
Arguments
None.
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.
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()
Return Value
A character string containing the current UIC, including brackets ([
]). The UIC is returned in the format [group-identifier,
member-identifier].
Arguments
None.
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.
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])
Return Value
The integer 0 if the procedure verification setting is off, or the
integer 1 if the procedure verification setting is on.
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.
Description
The lexical function 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.
Using the F$VERIFY function in command procedures allows you to test
the current procedure verification setting. For example, a command
procedure can save the current procedure verification setting before
changing it and then later restore the setting. In addition, you can
construct a procedure that does not display (or print) commands,
regardless of the initial state of verification.
When you use the F$VERIFY function, you can specify zero, one, or two
arguments. If you do not specify any arguments, neither of the
verification settings is changed. If you specify only the
procedure-value argument, both procedure and image
verification are turned on (if the value is 1) or off (if the value is
0).
If you specify both arguments, procedure and image verification are
turned on or off independently. If you specify the
image-value argument alone, only image verification is
turned on or off. If you specify the image-value
argument alone, you must precede the argument with a comma (,).
You can also use the F$ENVIRONMENT function with VERIFY_PROCEDURE or
VERIFY_IMAGE as the argument. With the F$ENVIRONMENT function, you can
determine either the procedure or image verification setting; the
F$VERIFY function determines only the procedure verification setting.
DCL performs the F$VERIFY function even if it appears after a comment
character, if it is enclosed in single quotation marks (` '). This is
the only processing that DCL performs within a comment.
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.
|
