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.