VSI OpenVMS / VMS DCL Lexicals Functions

Document Number: AA-PV5KK-TK Publication Date: month 2018

This manual provides detailed reference information and examples for VSI OpenVMS DCL commands and lexical functions.

VMS Software, Inc., (VSI) Bolton, Massachusetts, USA

Legal Notice

Confidential computer software. Valid license from VSI required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software,
Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for VSI products and services are set forth in the express warranty statements
accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. VSI shall not be liable for technical or editorial errors
or omissions contained herein.

HPE, HPE Integrity, HPE Alpha, and HPE Proliant are trademarks or registered trademarks of Hewlett Packard Enterprise.

Intel, Itanium and IA64 are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Java, the coffee cup logo, and all Java based marks are trademarks or registered trademarks of Oracle Corporation in the United States or other countries.

Kerberos is a trademark of the Massachusetts Institute of Technology.

Microsoft, Windows, Windows-NT and Microsoft XP are U.S. registered trademarks of Microsoft Corporation. Microsoft Vista is either a registered trademark or trademark
of Microsoft Corporation in the United States and/or other countries.

Motif is a registered trademark of The Open Group UNIX is a registered trademark of The Open Group.

The VSI OpenVMS documentation set is available on DVD.

Lexical Functions

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

NOTE: In this abridged version of the VSI DCL Lexical Manual - the lexical functuons are only for Alpha and Itanium.
The (Alpha and Itanium Only) was messing up the formatting.
If you are running DCL on a VAX - ITS TIME TO MIGRATE TO AN ITANIUM !!!!!

Description

The command language includes constructs, called lexical functions, that return information about the current process and about
arithmetic and string expressions. The functions are called lexical functions because the command interpreter evaluates them during
the command input scanning (or lexical processing) phase of command processing.

You can use lexical functions in any context in which you normally use symbols or expressions. In command procedures, you
can use lexical functions to translate logical names, to perform character string manipulations, and to determine the current
processing mode of the procedure.

The general format of a lexical function is as follows:

F$function-name([args,...])

where:

F$	Indicates that what follows is a lexical function.
function-name	A keyword specifying the function to be evaluated. Function names can be truncated to any unique abbreviation.
( )	Enclose function arguments, if any. The parentheses are required for all functions, including functions thatdo not accept any arguments.
args,...	Specify arguments for the function, ifany, using integer or character string expressions.

For more information on specifying expressions, see the VSI OpenVMS User's Manual.

Table 2.1, “Summary of Lexical Functions” lists each lexical function and briefly describes the information that each function returns.
A detailed description of each function, including examples, is given in the following pages.

Table 2.1. Summary of Lexical Functions

Function	Description
F$CONTEXT	Specifies selection criteria for use with the F$PID function.
F$CSID	Returns an OpenVMS Cluster identification number and updates the context symbol to point to the current position in the system's cluster node list.
F$CUNITS	Converts a number from one specified unit of measure to another.
F$CVSI	Extracts bit fields from character string data and converts the result, as a signed value, to an integer.
F$CVTIME	Retrieves information about an absolute, combination, or delta time string.
F$CVUI	Extracts bit fields from character string data and converts the result, as an unsigned value, to an integer.
F$DELTA_TIME	Returns the time difference between a given start and end time.
F$DEVICE	Returns device names of all devices on a system that meet the specified selection criteria.
F$DIRECTORY	Returns the current default directory name string.
F$EDIT	Edits a character string based on the edits specified.
F$ELEMENT	Extracts an element from a string in which the elements are separated by a specified delimiter.
F$ENVIRONMENT	Obtains information about the DCL command environment.
F$EXTRACT	Extracts a substring from a character string expression.
F$FAO	Invokes the $FAO system service to convert the specified control string to a formatted ASCII output string.
F$FID_TO_NAME	Translates a file identification to a file specification.
F$FILE_ATTRIBUTES	Returns attribute information fora specified file.
F$GETDVI	Invokes the $GETDVI system service to return a specified item of information for a specified device.
F$GETENV	Invokes the $GETENV system service to return the value of the specified console environment variable.
F$GETJPI	Invokes the $GETJPI system service to return accounting, status, and identification information for a process.
F$GETQUI	Invokes the $GETQUI system service to return information about queues, batch and print jobs currently in those queues, form definitions, and characteristic definitions kept in the queue database.
F$GETSYI	Invokes the $GETSYI system service to return status and identification information about the local system, or about a node in the local cluster, if your system is part of a cluster.
F$IDENTIFIER	Converts an identifier in named format to its integer equivalent, or vice versa.
F$INTEGER	Returns the integer equivalent of the result of the specified expression.
F$LENGTH	Returns the length of a specified string.
F$LICENSE	Checks whether the specified license is loaded on the system.
F$LOCATE	Locates a character or character substring within a string and returns its offset within the string.
F$MATCH_WILD	Performs a wildcard matching between a candidate and a pattern string.
F$MESSAGE	Returns the message text associated with a specified system status code value.
F$MODE	Shows the mode in which a process is executing.
F$MULTIPATH	Returns a specified item of information for a specific multipath-capable device.
F$PARSE	Invokes the $PARSE RMS service to parse a file specification and return either the expanded file specification or the particular file specification field that you request.
F$PID	For each invocation, returns the next process identification number in sequence.
F$PRIVILEGE	Returns a value of TRUE or FALSE depending on whether your current process privileges match the privileges listed in the argument.
F$PROCESS	Returns the current process name string.
F$SEARCH	Invokes the $SEARCH RMS service to search a directory file,and returns the full file specification for a file you name.
F$SETPRV	Sets the specified privileges and returns a list of keywords indicating the previous state of these privileges for the current process.
F$STRING	Returns the string equivalent of the result of the specified expression.
F$TIME	Returns the current date and time of day, in the format dd-mmm-yyyy hh:mm:ss.cc.
F$TRNLNM	Translates a logical name and returns the equivalence name string or the requested attributes of the logical name.
F$TYPE	Determines the data type of a symbol.
F$UNIQUE	Generates a string that is suitable to be a file name and is guaranteed to be unique across the cluster.
F$USER	Returns the current user identification code (UIC).
F$VERIFY	Returns the integer 1 if command procedure verification is set on; returns the integer 0 if command procedure verification is set off. The F$VERIFY function also can set new verification states.

F$CONTEXT

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)

Return Value

A null string ("").

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. 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 Item	Selection Value	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, GTR, LEQ, LSS, EQL, NEQ	On Alpha, valid authorized base priority (0--63).
CANCEL			Cancels the selection criteria for this context.
CURPRIV	Keyword	ALL, ANY, EQL, NEQ	Valid privilege name keyword or list of keywords. For more information, see the HP OpenVMS Guide to System Security.
GRP	Integer	GEQ, GTR, LEQ, LSS, EQL, NEQ	UIC group number.
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, GTR, LEQ, LSS, EQL, NEQ	Subprocess count for entire job.
JOBTYPE	Keyword	EQL, NEQ	Valid job-type keyword. Valid keywords are DETACHED, NETWORK, BATCH, LOCAL, DIALUP, and REMOTE. For more information, see the VSI OpenVMS User's Manual.
MASTER_PID	String	EQL, NEQ	PID of master process.
MEM	Integer	GEQ, GTR, LEQ, LSS, EQL, NEQ	UIC member number.
MODE	Keyword	EQL, NEQ	Valid process mode keyword. Valid keywords are OTHER, NETWORK, BATCH, and INTERACTIVE. For more information, see the VSI OpenVMS User's Manual.
NODE_CSID	Integer	EQL, NEQ	Node's cluster ID number.
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, GTR, LEQ, LSS, EQL, NEQ	Subprocess count of process.
PRCNAM	String	EQL, NEQ	Process name or list of process names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
PRI	Integer	GEQ, GTR, LEQ, LSS, EQL, NEQ	Process priority level number (0--63, on Alpha).
PRIB	Integer	GEQ, GTR, LEQ, LSS, EQL, NEQ	Base process priority level number (0--63, on Alpha).
STATE	Keyword	EQL, NEQ	Valid process state keyword. For more
			information, see the description of the $GETJPI service in the HP 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 HP 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:

LSS – less than the value specified in the call to F$PID

LEQ – less than or equal to the value specified in the call to F$PID

GTR – greater than the value specified in the call to F$PID

GEQ – greater than or equal to the value specified in the call to F$PID

EQL – equal to the value specified in the call to F$PID

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.

ALL – requires that all items in the list be true for a process

ANY – requests that any item in the list be part of the attributes of a process

EQL – requires the values to match exactly (that is, values not specified must not be true of the process)

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.

Description

Use the F$CONTEXT function to set up selection criteria for the F$PID function.

The F$CONTEXT function is called as many times as necessary to produce the criteria needed; however, each call can specify only one selection item. Lists of item values are allowed, where appropriate, and more than one context can be operated upon at a time.

After establishing the selection criteria with appropriate calls to F$CONTEXT, F$PID is called repeatedly to return all the process identification (PID) numbers that meet the criteria specified in the F$CONTEXT function. When there are no more such processes, the F$PID function returns null string.

After the F$PID function is called, the context symbol is considered “frozen”; F$CONTEXT cannot be called again with the same context symbol until the associated context selection criteria have been deleted. If you attempt to set up additional selection criteria with the same context symbol, anerror message is displayed; however, the context and selection criteria are not affected and calls to the F$PID function can continue.

The F$CONTEXT function uses process memory to store the selection criteria. This memory is deleted under two circumstances. Memory is deleted when the F$PID function is called and a null string ("") is returned – that is, when all processes that meet the selection criteria have been returned. Memory also is deleted if the CANCEL selection- item keyword is used in a call to F$CONTEXT with an established context. This type of call is appropriate for a Ctrl/Y operation or another condition handling routine.

Examples

$!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.

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

F$CSID

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)

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 ("").

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

Description

The F$CSID function returns a cluster identification number, and updates the context symbol to point to the current position in the system's cluster node list.

If the current system is not a member of a cluster, the first return valueis null.

You can use the F$CSID function to obtain all of the cluster identification numbers on the system. For each cluster identification returned, the F$GETSYI function can be used to obtain information about the particular system.

Once the argument is initialized by the first call, each subsequent F$CSID function call returns the cluster identification number of another node in the cluster. (Note that the cluster identification numbers are returned in random order.) After the cluster identification number of the last system in the list is returned, the F$CSID function returns a null string.

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 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 non-clustered 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.

F$CUNITS

F$CUNITS — Converts a number from one specified unit of measure to another.

Format

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

Return Value

A number representing the converted value.

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.

Examples

$ 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

F$CVSI

F$CVSI — Converts the specified bits in the specified character string to a signed number.

Format

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

Return Value

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

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 exceeds the number of bits in the string, 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.

Examples

$ A[0,32] = %X2B

$ SHOW SYMBOL A

A = "+..."

$ X = F$CVSI(0,4,A)

$ SHOW SYMBOL X

X = -5 Hex = FFFFFFFB Octal = 3777777777

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, seethe 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.

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

F$CVTIME

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])

Return Value

A character string containing the requested information.

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 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 VSI OpenVMS User's Manual or the online help topic Date.

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

output_time_format

Specifies the time format for the information you want returned. Specify the 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 (default)	The requested information should be returned in the 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 argument, then you must also provide a delta time specification for the 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 argument.

If the argument is a delta time and the 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.

Description

When using the F$CVTIME function, you can omit optional arguments that can be used to the right of the last argument you specify; however, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument you specify.

When specifying the input time argument in either absolute or combination time format, you can specify ABSOLUTE or COMPARISON as the argument; you cannot specify DELTA.

When specifying the argument in delta time format, you must specify DELTA as the argument.

Examples

$ 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

$ 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 argument that is omitted.

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

F$CVUI

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)

Return Value

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

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. Specifies the character string to be edited.

string

Specifies the character string to be edited.

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.

F$DELTA_TIME

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.

Synopsis

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

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

Arguments

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:

ASCTIM: ASCII time format

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

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.

$ WRITE SYS$OUTPUT F$DELTA_TIME(START,END,"DCL")
0-00:00:11.91
$ WRITE SYS$OUTPUT F$DELTA_TIME(START,END,"ASCTIM")
0 00:00:11.91

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.

F$DEVICE

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])

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, theF$DEVICE function returns a null string ("").

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

Specify the argument as a character string expression.

devclass

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

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

devtype

Specifies the device type for which F$DEVICE is to search. Specify the 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 searchcontexts when you use the F$DEVICE function more than once and when you supplydifferent 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 arguments to identify each search separately.

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

If you omit the 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.

Description

The F$DEVICE function allows you to search for devices that meet certain search criteria by using the $DEVICE_SCAN system service.

The F$DEVICE function allows asterisk (*) and percent sign (%) wildcard character searches based only on the device name; you must specify a valid character string expression for the device class or device type.

You can use the F$DEVICE function in a loop in a command procedure to return device names that match the specified selection criteria. Each time the F$DEVICE function is executed, it returns the next device on the system that matches the selection criteria. Note that devices are returned in no particular order. After the last device name is returned, the next F$DEVICE function returns a null string.

Note that you must maintain the context of the search string explicitly (by specifying the argument) or implicitly (by omitting the argument). In either case, you must specify the same selection criteria each time you execute the F$DEVICE system service with the same (explicit or implicit) stream.

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

F$DIRECTORY

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()

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.

Arguments

None.

Description

You can use the F$DIRECTORY function to save the name of the current default directory in a command procedure, to change the default to another directory t odo work, and to later restore the original setting.

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

F$EDIT

F$EDIT — Edits the character string based on the edits specified in the argument.

Format

F$EDIT(string, edit-list)

Return Value

A character string containing the specified edits.

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.

Examples

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

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

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

F$ELEMENT

F$ELEMENT — Extracts one element from a string of elements.

Format

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

Return Value

A character string containing the specified element.

Arguments

element-number

Specifies the number of the element to extract (numbering begins with zero).Specify the argument as an integer expression. If the 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.

Examples

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

$! 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 strin “1”. The procedure runs the index, chapter1. 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.

F$ENVIRONMENT

F$ENVIRONMENT — Returns information about the current DCL command environment.

Format

F$ENVIRONMENT(item)

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.

Arguments

item

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

Item	Data 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 SETCONTROL. 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 SETNOCONTROL. 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_CONTROL	String	TRUE if a carriage return and line feed 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_PREFIX	String	Returns the prefix control string set by means of the SET PREFIX command.
VERIFY_PROCEDURE	String	TRUE if procedure verification SETVERIFY=PROCEDURE is in effect. If command verification is in effect, then the command procedure echoes DCL command lines.

Examples

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

$ 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 depthallowable within command procedures.

$ 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 defaul tprotection 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.

F$EXTRACT

F$EXTRACT — Extracts the specified characters from the specified string.

Format

F$EXTRACT(start,length,string)

Return Value

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

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.

Examples

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

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

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

F$FAO

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[,...]])

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.

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. Table 2.2,
“Summary of FAO Directives” lists the FAO directives you can specify in a 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.Table 2.2, “Summary of FAO Directives” lists the argument types required by each FAO directive.

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

Description

The F$FAO lexical function invokes the $FAO system service to convert 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.

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.

The FAO directives are grouped in the following categories:

Character string insertion

Zero-filled numeric conversion

Blank-filled numeric conversion

Special formatting

Parameter interpretation

Table 2.2, “Summary of FAO Directives” summarizes the FAO directives and shows the required argument types. In addition, the following sections describe output strings from directives that perform character string insertion, zero-filled numeric conversion, and blank-filled numeric conversion.

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:

Quadword numeric directives (Q, H, and J), which are not supported in DCL because all DCL numeric values are stored and manipulated as longwords.

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 HP OpenVMS System Services Reference Manual.

Table 2.2. Summary of FAO Directives

Directive	Argument 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 equal to 0	Inserts the current time.
!%D	Integer equal to 0	Inserts the current date/time.
Argument interpretation:
!-	None	Reuses the last argument.
!+	None	Skips the next argument.

Output Strings from Character String Insertion

The !AS directive inserts a character string (specified as an argument for the directive) into the control string. The field length of the character string when it is inserted into the control string defaults to the length of the character string. If the default length is shorter than an explicitly stated field length, the string is left-justified and blank- filled. If the default length is longer than an explicitly stated field length, the string is truncated on the right.

Output Strings from Zero-Filled Numeric Conversion

Directives for zero-filled numeric conversion convert an integer (specified as an argument for the directive) to decimal, octal, or hexadecimal notation. The ASCII representation of the integer is inserted into the control string. Default output field lengths for the converted argument are determined as follows:

Directives that convert arguments to octal notation return 3 digits for byte conversion, 6 digits for word conversion, and 11 digits for longword conversion. Numbers are right-justified and zero-filled on the left. Explicit-length fields longer than the default are blank-filled on the left. Explicit-length fields shorter than the default are truncated on the left.

Directives that convert arguments to hexadecimal notation return 2 digits for byte conversion, 4 digits for word conversion, and 8 digits for longword conversion. Numbers are right-justified and zero-filled on the left. Explicit-length fields longer than the default are blank-filled on the left. Explicit-length fields shorter than the default are truncated on the left.

Directives that convert arguments to decimal notation return the required number of characters for the decimal number. Explicit-length fields longer than the default are zero-filled on the left. If an explicit-length field is shorter than the number of characters required for the decimal number, the output field is completely filled with asterisks (*).

For byte conversion, only the low-order 8 bits of the binary representation of the argument are used. For word conversion, only the low-order 16 bits of the binary representation of the argument are used. For longword conversion, the entire 32-bit binary representation of the argument is used.

Output Strings from Blank-Filled Numeric Conversion

Directives for blank-filled numeric conversion convert an integer (specified as an argument for the directive) to decimal notation. These directives can convert the integer as a signed or unsigned number. The ASCII representation of the integer is inserted into the control string.

Output field lengths for the converted argument default to the required number of characters. Values shorter than explicit-length fields are right-justified and blank-filled; values longer than explicit-length fields cause the field to be filled with asterisks.

Output Strings from Special Formatting Directives

The !n%C and !%E directives insert an ASCII string (based on the value of the most recently evaluated argument) into the output string. These directives are useful for inserting irregular plural nouns and verbs.

If the most recently evaluated argument equals n, the text between one directive and the next is inserted into the output string. If the most recently evaluated argument does not equal n, the next !n%C directive is processed.

If n must be a negative number, you must specify it as an argument and use the number sign (#).

You can specify the !n%C and !%E directives with repeat counts. If you specify repeat counts, the text between one directive and the next is copied to the output string the specified number of times.

The %F directive marks the end of a plurals statement.

Examples

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

$ 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”.

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

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

F$FID_TO_NAME

F$FID_TO_NAME — (Alpha/Integrity servers Only). Translates a file identification to a file specification.

Format

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

Return Value

A character string containing the file specification.

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.

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 theparentheses around the file identifier, provided it is enclosed by double quotation marks.

F$FILE_ATTRIBUTES

F$FILE_ATTRIBUTES — Returns attribute information for a specified file.

Format

F$FILE_ATTRIBUTES(filespec,item)

Return value

Either an integer or a character string, depending on the item you request.Table 2.3, “F$FILE_ATTRIBUTES Items”shows the data types of the values returned for each item.

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 argument must be specified as a character string expression, and can be anyone of the OpenVMS RMS field names listed in Table 2.3, “F$FILE_ATTRIBUTES Items”.

Description

Use the F$FILE_ATTRIBUTES lexical function in DCL assignment statements and expressions to return file attribute information.Table 2.3, “F$FILE_ATTRIBUTES Items” lists the items you can specify with the F$FILE_ATTRIBUTES function, the information returned and the data type of this information.

Table 2.3. F$FILE_ATTRIBUTES Items

Item	Return 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_LENGTH_HINT	String	Record count and data byte count in the form (n,m), where n is the record count and m is 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_FILE	String	TRUE if the file is a journal; otherwise 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 move file 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 FALSE.
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_SEMANTICS	String	ASCII string that represents stored 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.

File attributes are stored in the file header, which is created from information in OpenVMS RMS control blocks. For more information on OpenVMS RMS control blocks, see the OpenVMS Record Management Services Reference Manual.

Examples

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

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

F$GETDVI

F$GETDVI — Returns a specified item of information for a specified device.

Format

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

Return Value

Either an integer or a character string, depending on the item you request.Table 2.4, “F$GETDVI Items” shows the data types of the values returned for each item.

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 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 argument must be specified as a character string expression and can be any one of the items listed in Table 2.4, “F$GETDVI Items”.

pathname(Alpha/Integrity servers only)

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

Check the definitions of the item codes in Table 2.4, “F$GETDVI Items” to see if the argument is used. In general, item codes that return information that can vary by path do use the 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 argument.

Description

The F$GETDVI lexical function invokes the $GETDVI system service to return a specified item of information for a specified device. You can obtain a list of devices on your current system by using the lexical function F$DEVICE. Unless otherwise stated in the description of the item argument, F$GETDVI returns device information about the local node only.

This lexical function allows a process to obtain information for a device to which the process has not necessarily assigned a channel.

The F$GETDVI function returns information on all items that can be specified with the $GETDVI system service. In addition to the items that the $GETDVI system service allows, the F$GETDVI function allows you to specify the item EXISTS.

Table 2.4, “F$GETDVI Items” lists the items you can specify with the F$GETDVI function, the type of information returned, and the data types of the return values. In addition to the return information listed in Table 2.4, “F$GETDVI Items”, the F$GETDVI lexical function returns any error messages generated by the $GETDVI system service.

For more information on the $GETDVI system service and the items you can specify, see the HP OpenVMS System Services Reference Manual.

Table 2.4. F$GETDVI Items

Item	Return Type	Information Returned
ACCESSTIMES_RECORDED	String	TRUE or FALSE to indicate whether the volume supports the recording of access times.
ACPPID	String	Ancillary control process (ACP) identification.
ACPTYPE	String	ACP type code, as one of the following strings: F11V1, F11V2, F11V3, F11V4, F11V5, F64, HBS, JNL, MTA, NET, REM, UCX, or ILLEGAL. The ACPTYPE item returns ILLEGAL if:
ALL	String	TRUE or FALSE to indicate whether the device is allocated.
ALLDEVNAM	String	Allocation class device name.
ALLOCLASS	Longword integer between 0 and 255	Allocation class of the host.
ALT_HOST_AVAIL	String	TRUE or FALSE to indicate whether the host serving the alternate path is available.
ALT_HOST_NAME	String	Name of the host serving the alternate path.
ALT_HOST_TYPE	String	Hardware type of the host serving the alternate path.
	Integer	Number of available, working paths for a multipath- capable device.
AVL	String	TRUE or FALSE to indicate whether the device is available for use.
CCL	String	TRUE or FALSE to indicate whether the device is a carriage control device.
CLUSTER	Integer	Volume cluster size.
CONCEALED	String	TRUE or FALSE to indicate whether the logical device name translates to a concealed device.
CYLINDERS	Integer	Number of cylinders on the volume (disks only).
DEVBUFSIZ	Integer	Device buffer size.
DEVCHAR	Integer	Device characteristics.
DEVCHAR2	Integer	Additional device characteristics.
DEVCLASS	Integer	Device class. See the Examples section to determine the device class values returned on your system.
DEVDEPEND	Integer	Device-dependent information. The device is not mounted or is mounted using the / FOREIGN qualifier. The ACPTYPE is not currently defined.
DEVDEPEND2	Integer	Additional device-dependent information.
DEVICE_MAX_IO_SIZE	Integer	The maximum unsegmented transfer size supported by the device's device driver. Although this value is the absolute maximum size supported by the device driver, other software layers (RMS and XFC, for example) might impose lower maximum values, thereby limiting the maximum transfer size.
DEVICE_TYPE_NAME	String	Device type name. Note that if the device is a SCSI tape or disk, the device type name is retrieved directly from the device.
DEVLOCKNAM	String	A unique lock name for the device.
DEVNAM	String	Device name.
DEVSTS	Integer	Device-dependent status information.
DEVTYPE	Integer	Device type. See the Examples section to determine the device type values returned on your system.
DFS_ACCESS	String	TRUE or FALSE to indicate whether the device is a virtual disk connected to a remote Distributed File System (DFS) server.
DIR	String	TRUE or FALSE to indicate whether the device is directory structured.
DMT	String	TRUE or FALSE to indicate whether the device is marked for dismount.
DUA	String	TRUE or FALSE to indicate whether the device is a generic device.
ELG	String	TRUE or FALSE to indicate whether the device has error logging enabled.
ERASE_ON_DELETE	String	TRUE or FALSE to indicate whether disk blocks are zeroed upon file deletion on the volume.
ERRCNT	Integer	Error count of the device. If the error count has been reset with the SET DEVICE /RESET=ERRCNT command, you can use the SHOW DEVICE/FULL command to display the date and time that the error count was reset. If the pathname parameter is specified, only the error count for that path is returned. If the pathname parameter is omitted, the summation of the error counts for all paths in a multipath device is returned.
ERROR_RESET_TIME	String	Time at which the error count was reset.
EXISTS	String	TRUE or FALSE to indicate whether the device exists on the system.
EXPSIZE	Integer	Current expansion limit on the volume.
FC_HBA_FIRMWARE_REV	String	Firmware revision information of a Fibre Channel host bus adapter. A null string is returned for all other devices.
FC_NODE_NAME	String	The Fibre Channel host bus adapter node name.
FC_PORT_NAME	String	The Fibre Channel host bus adapter port name.
FOD	String	TRUE or FALSE to indicate whether the device is a files-oriented device.
FOR	String	TRUE or FALSE to indicate whether the device is mounted using the /FOREIGN qualifier.
FREEBLOCKS	Integer	Number of free blocks on the volume (disks only).
FULLDEVNAM	String	Fully qualified device name.
GEN	String	TRUE or FALSE to indicate whether the device is a generic device.
HARDLINKS_SUPPORTED	String	TRUE or FALSE to indicate whether hardlinks, rather than aliases, are supported on the volume.
HOST_AVAIL	String	TRUE or FALSE to indicate whether the host serving the primary path is available.
HOST_COUNT	Integer	Number of hosts that make the device available to other nodes in the OpenVMS Cluster.
HOST_NAME	String	Name of the host serving the primary path.
HOST_TYPE	String	Hardware type of the host serving the primary path.
IDV	String	TRUE or FALSE to indicate whether the device is capable of providing input.
LAN_ALL_MULTICAST_MODE	String	TRUE or FALSE to indicate whether the device is enabled to receive all multicast packets rather than only packets addressed to enabled multicast addresses.
LAN_AUTONEG_ENABLED	String	TRUE or FALSE to indicate whether the device is set to autonegotiate the speed and duplex settings.
LAN_DEFAULT_MAC_ADDRESS	String	The default MAC (media access control) address of the device.
LAN_FULL_DUPLEX	String	TRUE or FALSE to indicate whether the device is operating in full-duplex mode.
LAN_JUMBO_FRAMES_ENABLED	String	TRUE or FALSE to indicate whether jumbo frames are enabled on the device.
LAN_LINK_STATE_VALID	String	TRUE or FALSE to indicate whether or not the device driver for the LAN device correctly maintains the link status. The device drivers for the following devices do not maintain the link status: DEMNA, any TURBOchannel adapter, any PCMPIA Ring adapter, Galaxy shared memory, TGEC, DE205, DE422, DE425, DE434, DE435, DE500 (the -XA and -AA variants; only the -BA variant is supported.)
LAN_LINK_UP	String	TRUE or FALSE to indicate whether the link is up. This item code is valid only for the template device (that is, unit number 0); this item returns 0 if used with a non-template LAN device. This item is supported only on newer adapters; to determine whether or not a particular device supports LAN_LINK_UP, you must first use F$GETDVI with the item LAN_LINK_STATE_VALID. See that item description for more information. If LAN_LINK_UP is used on an adapter that does not maintain the link status, the returned status will be SS$_UNSUPPORTED.
LAN_MAC_ADDRESS	String	The current MAC (media access control) address of the device. For more information about the distinction between the default and current MAC addresses, see the HP OpenVMS System Services Reference Manual.
LAN_PROMISCUOUS_MODE	String	TRUE or FALSE to indicate whether the device is enabled to receive all packets, rather than only packets addressed to the MAC addresses and to enabled multicast addresses.
LAN_PROTOCOL_NAME	String	The name of the LAN protocol running on the device.
LAN_PROTOCOL_TYPE	String	The type of the LAN protocol running on the device.
LAN_SPEED	Integer	The speed of the LAN device, in units of megabits per second. Valid values are 4, 10, 16, 100, 1000, and 10000.
LOCKID	Integer	Clusterwide lock identification.
LOGVOLNAM	String	Logical volume name.
MAILBOX_BUFFER_QUOTA	Integer	The current mailbox quota as an unsigned integer longword.
MAILBOX_INITIAL_QUOT	Integer	The initial mailbox quota as an unsigned integer longword.
MAXBLOCK	Integer	Number of logical blocks on the volume.
MAXFILES	Integer	Maximum number of files on the volume (disks only).
MBX	String	TRUE or FALSE to indicate whether the device is a mailbox.
MEDIA_ID	Integer	Nondecoded media ID.
MEDIA_NAME	String	Either the name of the disk or the tape type.
MEDIA_TYPE	String	Device name prefix.
MNT	String	TRUE or FALSE to indicate whether the device is mounted.
MOUNT_TIME ()	String	Time at which the volume was mounted. For volumes mounted in a cluster, only the time of the initial mount is recorded; the time of any subsequent mount is not recorded.
MOUNTCNT	Integer	Number of times the volume has been mounted on the local system. The value of MOUNTCNT displayed by the SHOW DEVICE command is the total of all mounts of the volume across all members of the cluster.
MOUNTVER_ELIGIBLE	String	TRUE or FALSE to indicate whether the volume is eligible to undergo mount verification. A volume mounted with either the /FOREIGN or / NOMOUNT_VERIFICATION qualifier is not subject to mount verification.
MPDEV_AUTO_PATH_SW_CNT ()	Integer	Number of times a multipath device has automatically switched paths because of an I/O error or as the result of automatically "failing back" to a local path from a remote path once the local path became available.
MPDEV_CURRENT_PATH	String	Current path name for multipath devices. If the device is not part of a multipath set, this lexical returns the name of the device path if the class driver for this device supports path names. SYS$DKDRIVER, SYS$DUDRIVER, SYS$MKDRIVER, and SYS $GKDRIVER support path names. Returns a null string if the class driver for the device does not support path names.
MPDEV_MAN_PATH_SW_CNT	Integer	Number of times a multipath device has manually switched paths because of a SET DEVICE /PATH / SWITCH command or use of the $SET_DEVICE system service.
MT3_DENSITY	String	Current density of the device (tapes only.)
MT3_SUPPORTED	String	TRUE or FALSE to indicate whether the device supports densities defined in the MT3DEF (for Alpha tapes only.)
MULTIPATH	String	TRUE or FALSE to indicate whether the device is a member of a multipath set.
MVSUPMSG	String	TRUE or FALSE to indicate whether mount verification OPCOM messages are currently being supressed on this device. See the MVSUPMSG_INTVL and MVSUPMSG_NUM system parameters for more information on the supression of mount verification messages.
NET	String	TRUE or FALSE to indicate whether the device is a network device.
NEXTDEVNAM	String	Device name of the next volume in a volume set (disks only).
NOCACHE_ON_VOLUME	String	TRUE or FALSE to indicate whether the volume is mounted with all caching disabled.
NOHIGHWATER	String	TRUE or FALSE to indicate whether high-water marking is disabled on the volume.
NOSHARE_MOUNTED	String	TRUE or FALSE to indicate whether the volume is mounted with /NOSHARE.
ODS2_SUBSET0	String	TRUE or FALSE to indicate whether the volume mounted supports only a subset of the ODS-2 file structure.
ODS5	String	TRUE or FALSE to indicate whether the volume is mounted ODS-5.
ODV	String	TRUE or FALSE to indicate whether the device is capable of providing output.
OPCNT	Integer	Operation count of the device. Note that the operation count may have been reset with the SET DEVICE/ RESET=OPCNT command. If the pathname parameter is specified, only the operation count for that path is returned. If the pathname parameter is omitted, the summation of the operation counts for all paths in a multipath device is returned.
OPR	String	TRUE or FALSE to indicate whether the device is an operator.
OWNUIC	String	User identification code (UIC) of the device owner.
PATH_AVAILABLE ()	String	TRUE or FALSE to indicate whether the specified path is available. This item code is typically used with the pathname parameter. If the pathname parameter is omitted, information about the current path of the multipath device is returned.
PATH_NOT_RESPONDING	String	TRUE or FALSE to indicate whether the specified path is marked as not responding. This item code is typically used with the pathname parameter. If the pathname parameter is omitted, information about the current path of the multipath device is returned.
PATH_POLL_ENABLED	String	TRUE or FALSE to indicate whether the specified path is enabled for multipath polling. This item code is typically used with the pathname parameter. If the pathname parameter is omitted, information about the current path of the multipath device is returned.
PATH_SWITCH_FROM_TIME ()	String	Time from which this path was switched, either manually or automatically. This item code is typically used with the pathname parameter. If the pathname parameter is omitted, information about the current path of the multipath device is returned.
PATH_SWITCH_TO_TIME	String	Time to which this path was switched, either manually or automatically. This item code is typically used with the pathname parameter. If the pathname parameter is omitted, information about the current path of the multipath device is returned.
PATH_USER_DISABLED	String	TRUE or FALSE to indicate whether the specified path has been disabled using the SET DEVICE / PATH /NOENABLE command. This item code is typically used with the pathname parameter. If the pathname parameter is omitted, information about the current path of the multipath device is returned.
PID	String	Process identification number of the device owner.
PREFERRED_CPU	Integer	Return argument is a 32-bit CPU bit mask with a bit set indicating the preferred CPU. A return argument containing a bit mask of zero indicates that no preferred CPU exists, either because Fast Path is disabled or the device is not a Fast Path capable device. The return argument serves as a CPU bit mask input argument to the $PROCESS_AFFINITY system service. The argument can be used to assign an application process to the optimal preferred CPU.
PREFERRED_CPU_BITMAP	String	A bitmap string of zeros and, at most, a single 1. The 1 in the bitmask represents the number of the CPU to which the device is affinitized. The length of the string determines by how many CPUs are on the system. If there is no 1 in the bitmap string, then either Fast Path is disabled systemwide, or the device is not Fast Path- capable.
PROT_SUBSYSTEM_ENABLED	String	TRUE or FALSE to indicate whether the volume is mounted with protected subsystems enabled.
QLEN ()	Integer	The queue length for the device. This value is the number of I/O requests already in the driver --- not the depth of the I/O pending queue.
RCK	String	TRUE or FALSE to indicate whether the device has read checking enabled.
RCT	String	TRUE or FALSE to indicate whether the disk contains RCT.
REC	String	TRUE or FALSE to indicate whether the device is record oriented.
RECSIZ	Integer	Blocked record size.
REFCNT	Integer	Reference count of processes using the device.
REMOTE_DEVICE	String	TRUE or FALSE to indicate whether the device is a remote device.
RND	String	TRUE or FALSE to indicate whether the device allows random access.
ROOTDEVNAM	String	Device name of the root volume in a volume set (disks only).
RTM	String	TRUE or FALSE to indicate whether the device is a real-time device.
SCSI_DEVICE_FIRMWARE_REV	String	Firmware revision number of a SCSI disk or SCSI tape. A null string is returned for any other device.
SDI	String	TRUE or FALSE to indicate whether the device is single-directory structured.
SECTORS	Integer	Number of sectors per track (disks only).
SERIALNUM	Integer	Volume serial number (disks only).
SERVED_DEVICE	String	TRUE or FALSE to indicate whether the device is a served device.
SET_HOST_TERMINAL	String	TRUE or FALSE to indicate whether the device is a remote terminal for a SET HOST session from a remote node.
SHDW_CATCHUP_COPYING	String	TRUE or FALSE to indicate whether the device is a member that is the target of a full copy operation.
SHDW_COPIER_NODE (Alpha/I64 only)	String	The name of the node that is actively performing the copy or merge operation.
SHDW_DEVICE_COUNT (Alpha/ I64 only)	Integer	The total number of devices in the virtual unit, including devices being added as copy targets.
SHDW_GENERATION (Alpha/I64 only)	String	The current internal revision number for the virtual unit. This value is subject to change.
SHDW_MASTER	String	TRUE or FALSE to indicate whether the device is a virtual unit.
SHDW_MASTER_MBR	String	The name of the master member unit that will be used for merge and copy repair operations and for shadow set recovery operations.
SHDW_MASTER_NAME	String	Device name of the virtual unit that represents the shadow set of which the specified device is a member. F$GETDVI returns a null string ("") if the specified device is not a member, or is itself a virtual unit.
SHDW_MBR_COPY_DONE	String	The percent of the copy operation completed on this member unit.
SHDW_MBR_COUNT	String	The number of full source members in the virtual unit. Devices being added as copy targets are not full source members.
SHDW_MBR_MERGE_DONE ()	String	The percent of the merge operation completed on this member unit.
SHDW_MBR_READ_COST (Alpha/ I64 only)	String	The current value set for the member unit. This value can be modified to use a user-specified value.
SHDW_MEMBER	String	TRUE or FALSE to indicate whether the device is a shadow set member.
SHDW_MERGE_COPYING	String	TRUE or FALSE to indicate whether the device is a merge member of the shadow set.
SHDW_MINIMERGE_ENABLE	String	A value of TRUE indicates that the virtual unit will undergo a mini-merge, not a full merge, if a system in the cluster crashes.
SHDW_NEXT_MBR_NAME	String	Device name of the next member in the shadow set. If you specify a virtual unit, F$GETDVI returns the device name of a member of the shadow set. If you specify the name of a shadow set member unit with the device name and item arguments, F$GETDVI returns the name of the "next" member unit or a null string if there are no more members. To determine all the members of a shadow set, first specify the virtual unit to F$GETDVI; on subsequent calls, specify the member name returned by the previous F$GETDVI call until it has finished, when it returns a null member name. The device name includes the allocation class if the allocation class is not zero; otherwise it includes the device name of the disk controller.
SHDW_READ_SOURCE	String	The name of the member unit that will be used for reads at this time. The unit with the lowest sum total of its queue length and read cost is used. This is a dynamic value.
SHDW_SITE	Integer	The site value for the specified device. This value is set by the SET DEVICE or SET SHADOW command.
SHDW_TIMEOUT ()	Integer	The user-specified timeout value set for the device. If the user has not set a value by using the SETSHOSHADOW utility, the value of the SYSGEN parameter SHADOW_MBR_TMO is used for member units and the value of MVTIMEOUT is used for virtual units.
SHR	String	TRUE or FALSE to indicate whether the device is shareable.
SPL	String	TRUE or FALSE to indicate whether the device is being spooled.
SPLDEVNAM	String	Name of the device being spooled.
SQD	String	TRUE or FALSE to indicate whether the device is sequential block-oriented (that is, magnetic tape).
STS	Integer	Status information.
SWL	String	TRUE or FALSE to indicate whether the device is software write-locked.
TOTAL_PATH_COUNT (Alpha/I64 only)	Integer	Number of paths for a multipath-capable device.
TRACKS	Integer	Number of tracks per cylinder (disks only).
TRANSCNT	Integer	Volume transaction count.
TRM	String	TRUE or FALSE to indicate whether the device is a terminal.
TT_ACCPORNAM	String	The terminal server name and port name.
TT_ALTYPEAHD	String	TRUE or FALSE to indicate whether the terminal has an alternate type-ahead buffer (terminals only).
TT_ANSICRT	String	TRUE or FALSE to indicate whether the terminal is an ANSI CRT terminal (terminals only).
TT_APP_KEYPAD	String	TRUE or FALSE to indicate whether the keypad is in applications mode (terminals only).
TT_AUTOBAUD	String	TRUE or FALSE to indicate whether the terminal has automatic baud rate detection (terminals only).
TT_AVO	String	TRUE or FALSE to indicate whether the terminal has a VT100-family terminal display (terminals only).
TT_BLOCK	String	TRUE or FALSE to indicate whether the terminal has block mode capability (terminals only).
TT_BRDCSTMBX	String	TRUE or FALSE to indicate whether the terminal uses mailbox broadcast messages (terminals only).
TT_CHARSET	Integer	A bitmap indicating the coded character set supported by the terminal.
TT_CRFILL	String	TRUE or FALSE to indicate whether the terminal requires fill after a carriage return (terminals only).
TT_CS_HANGUL	String	TRUE or FALSE to indicate whether the terminal supports the DEC Korean coded character set.
TT_CS_HANYU	String	TRUE or FALSE to indicate whether the terminal supports the DEC Hanyu coded character set.
TT_CS_HANZI	String	TRUE or FALSE to indicate whether the terminal supports the DEC Hanzi coded character set.
TT_CS_KANA	String	TRUE or FALSE to indicate whether the terminal supports the DEC Kana coded character set.
TT_CS_KANJI	String	TRUE or FALSE to indicate whether the terminal supports the DEC Kanji coded character set.
TT_CS_THAI	String	TRUE or FALSE to indicate whether the terminal supports the DEC Thai coded character set.
TT_DECCRT	String	TRUE or FALSE to indicate whether the terminal is a DIGITAL CRT terminal (terminals only).
TT_DECCRT2	String	TRUE or FALSE to indicate whether the terminal is a DIGITAL CRT2 terminal (terminals only).
TT_DECCRT3	String	TRUE or FALSE to indicate whether the terminal is a DIGITAL CRT3 terminal (terminals only).
TT_DECCRT4	String	TRUE or FALSE to indicate whether the terminal is a DIGITAL CRT4 terminal (terminals only).
TT_DIALUP	String	TRUE or FALSE to indicate whether the terminal is connected to dialup (terminals only).
TT_DISCONNECT	String	TRUE or FALSE to indicate whether the terminal can be disconnected (terminals only).
TT_DMA	String	TRUE or FALSE to indicate whether the terminal has direct memory access (DMA) mode (terminals only).
TT_DRCS	String	TRUE or FALSE to indicate whether the terminal supports loadable character fonts (terminals only).
TT_EDIT	String	TRUE or FALSE to indicate whether the edit characteristic is set.
TT_EDITING	String	TRUE or FALSE to indicate whether advanced editing is enabled (terminals only).
TT_EIGHTBIT	String	TRUE or FALSE to indicate whether the terminal uses the 8-bit ASCII character set (terminals only).
TT_ESCAPE	String	TRUE or FALSE to indicate whether the terminal generates escape sequences (terminals only).
TT_FALLBACK	String	TRUE or FALSE to indicate whether the terminal uses the multinational fallback option (terminals only).
TT_HALFDUP	String	TRUE or FALSE to indicate whether the terminal is in half-duplex mode (terminals only).
TT_HANGUP	String	TRUE or FALSE to indicate whether the hangup characteristic is set (terminals only).
TT_HOSTSYNC	String	TRUE or FALSE to indicate whether the terminal has host/terminal communication (terminals only).
TT_INSERT	String	TRUE or FALSE to indicate whether insert mode is the default line editing mode (terminals only).
TT_LFFILL	String	TRUE or FALSE to indicate whether the terminal requires fill after a line feed (terminals only).
TT_LOCALECHO	String	TRUE or FALSE to indicate whether the local echo characteristic is set (terminals only).
TT_LOWER	String	TRUE or FALSE to indicate whether the terminal has the lowercase characters set (terminals only).
TT_MBXDSABL	String	TRUE or FALSE to indicate whether mailboxes associated with the terminal will receive unsolicited input notification or input notification (terminals only).
TT_MECHFORM	String	TRUE or FALSE to indicate whether the terminal has mechanical form feed (terminals only).
TT_MECHTAB	String	TRUE or FALSE to indicate whether the terminal has mechanical tabs and is capable of tab expansion (terminals only).
TT_MODEM	String	TRUE or FALSE to indicate whether the terminal is connected to a modem (terminals only).
TT_MODHANGUP	String	TRUE or FALSE to indicate whether the modify hangup characteristic is set (terminals only).
TT_NOBRDCST	String	TRUE or FALSE to indicate whether the terminal will receive broadcast messages (terminals only).
TT_NOECHO	String	TRUE or FALSE to indicate whether the input characters are echoed.
TT_NOTYPEAHD	String	TRUE or FALSE to indicate whether data must be solicited by a read operation.
TT_OPER	String	TRUE or FALSE to indicate whether the terminal is an operator terminal (terminals only).
TT_PAGE	Integer	Terminal page length (terminals only).
TT_PASTHRU	String	TRUE or FALSE to indicate whether PASSALL mode with flow control is available (terminals only).
TT_PHYDEVNAM	String	Physical device name associated with a channel number or virtual terminal.
TT_PRINTER	String	TRUE or FALSE to indicate whether there is a printer port available (terminals only).
TT_READSYNC	String	TRUE or FALSE to indicate whether the terminal has read synchronization (terminals only).
TT_REGIS	String	TRUE or FALSE to indicate whether the terminal has ReGIS graphics (terminals only).
TT_REMOTE	String	TRUE or FALSE to indicate whether the terminal has established modem control (terminals only).
TT_SCOPE	String	TRUE or FALSE to indicate whether the terminal is a video screen display (terminals only).
TT_SECURE	String	TRUE or FALSE to indicate whether the terminal can recognize the secure server (terminals only).
TT_SETSPEED	String	TRUE or FALSE to indicate whether you cannot set the speed on the terminal line (terminals only).
TT_SIXEL	String	TRUE or FALSE to indicate whether the sixel is supported (terminals only).
TT_SYSPWD	String	TRUE or FALSE to indicate whether the system password is enabled for a particular terminal.
TT_TTSYNC	String	TRUE or FALSE to indicate whether there is terminal/ host synchronization (terminals only).
TT_WRAP	String	TRUE or FALSE to indicate whether a new line should be inserted if the cursor moves beyond the right margin.
UNIT	Integer	The unit number.
VOLCHAR ()	String	128-bit string (16 bytes) that represents the volume characteristics or capabilities of the mounted device. If a bit is set, the volume is capable of performing the function.
VOLCOUNT	Integer	The count of volumes in a volume set (disks only).
VOLNAM	String	The volume name.
VOLNUMBER	Integer	Number of the current volume in a volume set (disks only).
VOLSETMEM	String	TRUE or FALSE to indicate whether the device is a volume set (disks only).
VOLSIZE ()	Integer	The volume's current logical volume size.
VOLUME_EXTEND_QUANTITY	Integer	Number of blocks to be used as the default extension size for all files on the volume.
VOLUME_MOUNT_GROUP	String	TRUE or FALSE to indicate whether the volume is mounted /GROUP.
VOLUME_MOUNT_SYS	String	TRUE or FALSE to indicate whether the volume is mounted /SYSTEM.
VOLUME_PENDING_WRITE_ERR	Integer	The number of pending write errors on the volume.
VOLUME_RETAIN_MAX	String	The maximum retention time for the volume, as specified with the DCL command SET VOLUME/ RETENTION.
VOLUME_RETAIN_MIN	String	The minimum retention time for the volume, as specified with the DCL command SET VOLUME/ RETENTION.
VOLUME_SPOOLED_DEV_CNT	Integer	The number of devices spooled to the volume.
VOLUME_WINDOW	Integer	The default window size for the volume.
VPROT	String	The volume protection mask.
WCK	String	TRUE or FALSE to indicate whether the device has write checking enabled.
WRITETHRU_CACHE_ENABLE	String	TRUE or FALSE to indicate whether the volume is mounted with write through caching enabled.
WWID	String	Worldwide identifier for a Fibre Channel device.

1In addition to the return information listed, the F$GETDVI lexical function returns any error messages generated by the system service

$GETDVI.

Examples

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

$ 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"

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

F$GETENV

F$GETENV — Returns the value of the specified console environment variable.

Format

F$GETENV(itmlst)

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.

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

Description

Returns the value(s) of the specified console environment variable(s).

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.

F$GETJPI

F$GETJPI — Returns information about the specified process.

Format

F$GETJPI(pid,item)

Return Value

Either an integer or a character string, depending on the item you request. Table 2.5, “F$GETJPI Items” shows the data types of the values
returned foreach item.

Arguments

pid

Specifies the process identification (PID) number of the process for which information is being reported. Specify the 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 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 argument as a character string expression. You can specify any one of the items listed i n Table 2.5, “F$GETJPI Items”

The F$GETJPI lexical function invokes the $GETJPI system service to return information about the specified process.

Note

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. The function returns information on all items that can be specified with the $GETJPI system service. For more information on the $GETJPI system service, see the HP OpenVMS System Services Reference Manual.

The F$GETJPI lexical function returns a zero or a null string if the target process is in a suspended or MWAIT (resource wait) state and the item requested is stored in the virtual address space of the process.

You can use the F$GETJPI lexical function to find out whether a process automatically unshelves files.

When you specify the STS2 item code, F$GETJPI returns a 32--bitnumeric value. When you convert this numeric value to binary format, the digit at symbolic bit position

PCB$V_NOUNSHELVE

shows you the process unshelving default. If the bit is 1, automatic unshelvingis turned off; if 0, automatic unshelving is turned on.

Table 2.5, “F$GETJPI Items” lists the items you can specify with the F$GETJPI function, the information returned, and the data type of this information.

Table 2.5. F$GETJPI Items

Description

Item	Return Type	Information Returned
ACCOUNT	String	Account name string (8 characters filled with trailing blanks).
APTCNT	Integer	Active page table count.
ASTACT	Integer	Access modes with active asynchronous system traps(ASTs).
ASTCNT	Integer	Remaining AST quota.
ASTEN	Integer	Access modes with ASTs enabled.
ASTLM	Integer	AST limit quota.
AUTHPRI	Integer	Maximum priority that a process without the ALTPRI(alter priority) privilege can achieve with the $SETPRI system service.
AUTHPRIV	String	Privileges that a process is authorized to enable.
BIOCNT	Integer	Remaining buffered I/O quota.
BIOLM	Integer	Buffered I/O limit quota.
BUFIO	Integer	Count of process buffered I/O operations.
BYTCNT	Integer	Remaining buffered I/O byte count quota.
BYTLM	Integer	Buffered I/O byte count quota.
CASE_LOOKUP_IMAGE	String	Returns information about the file name lookup case sensitivity of a specified process. This value is set only for the life of the image. Values are BLIND or SENSITIVE. See the Guide to OpenVMS File Applications for additional information.
CASE_LOOKUP_PERM	String	Returns information about the file name lookup case sensitivity of a specified process. This value is set for the life of the process unless the style is set again. Values are BLIND or SENSITIVE. See the Guide to OpenVMS File Applications for additional information.
CLASSIFICATION	String	Current MAC classification, as a 20-byte padded string,stored in the PSB.
CLINAME	String	Current command language interpreter; always returns DCL.
CPULIM	Integer	Limit on process CPU time.
CPUTIM	Integer	CPU time used in hundredths of a second.
CREPRC_FLAGS	Integer	Flags specified by theargument in the $CREPRC call that created the process.
CURPRIV	String	Current process privileges.
CURRENT_CAP_MASK	Integer	Current capabilities mask for the specified kernel thread. See the SET PROCESS/CAPABILITIES command for additional information.
DFPFC	Integer	Default page fault cluster size.
DFWSCNT	Integer	Default working set size.
DIOCNT	Integer	Remaining direct I/O quota.
DIOLM	Integer	Direct I/O limit quota.
DIRIO	Integer	Count of direct I/O operations for the process.
EFCS	Integer	Local event flags 0--31.
EFCU	Integer	Local event flags 32--63.
EFWM	Integer	Event flag wait mask.
ENQCNT	Integer	Lock request quota remaining.
ENQLM	Integer	Lock request quota limit.
EXCVEC	Integer	Address of a list of exception vectors.
FAST_VP_SWITCH	Integer	Number of times this process has issued a vector instruction that enabled an inactive vector processor without the expense of a vector context switch.
FILCNT	Integer	Remaining open file quota.
FILLM	Integer	Open file quota.
FINALEXC	Integer	Address of a list of final exception vectors.
FREP0VA	Integer	First free page at end of program region (P0space) (irrelevant if no image is running).
FREP1VA	Integer	First free page at end of control region (P1space).
FREPTECNT	Integer	Number of pages available for virtual memory expansion.
GPGCNT	Integer	Global page count in working set.
GRP	Integer	Group number of the user identification code (UIC).
HOME_RAD	Integer	Home resource affinity domain (RAD). RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
IMAGECOUNT	Integer	Number of images that have been run down for the process.
IMAGE_AUTHPRIV	String	Authorized privilege mask of the installed image.
IMAGE_PERMPRIV	String	Permanent (default) privilege mask of the installed image.
IMAGE_WORKPRIV	String	Working (active) privilege mask of the installed image.
IMAGNAME	String	File name of the current image.
IMAGPRIV	String	Privileges with which the current image was installed.
INSTALL_RIGHTS	Integer	Binary content of the install rights list. This item code returns a list of install rights separated by commas.
INSTALL_RIGHTS_SIZE	Integer	Number of bytes needed to store the install rights.
JOBPRCCNT	Integer	Number of subprocesses owned by the job.
JOBTYPE	Integer	Execution mode of the process at the root ofthe job tree.
KT_LIMIT	Integer	Returns the per-process kernel threads limit for the process.
LAST_LOGIN_I	String	Time of your last interactive login (the value that was reported when you logged in).
LAST_LOGIN_N	String	Time of your last non-interactive login (thev alue that was reported when you logged in).
LOGIN_FAILURES	Integer	Number of login failures that occurred prior to the start of the current session (the value that was reported when you logged in).
LOGIN_FLAGS	Integer	A longword bitmask that contains additional information relating to the login sequence.
LOGINTIM	String	Process creation time.
MASTER_PID	String	Process identification (PID) number of the process at the top of the current job's process tree.
MAXDETACH	Integer	Maximum number of detached processes allowed the user who owns the process.
MAXJOBS	Integer	Maximum number of active processes allowed for the user who owns the process.
MEM	Integer	Member number of the UIC.
MODE	String	Current process mode (BATCH, INTERACTIVE, NETWORK,or OTHER).
MSGMASK	Integer	Current message mask as established by the SETMESSAGE command. If no mask is specified, the default system message mask is described in the $GETMSG system service. For additional information, seethe $PUTMSG system service (for message mask bits), and the F$ENVIRONMENTl exical MESSAGE item.
MULTITHREAD	Integer	Current setting for the process (limited by the system setting).
NODENAME	String	The name of the OpenVMS Cluster node on which the process is running.
NODE_CSID	Integer	Cluster ID of the OpenVMS Cluster node on which the process is running.
NODE_VERSION	String	Operating system version number of theOpenVMS Cluster node on which the process is running.
OWNER	String	Process identification number of process owner.
PAGEFLTS	Integer	Count of page faults.
PAGFILCNT	Integer	Remaining paging file quota.
PAGFILLOC	Integer	Location of the paging file.
PARSE_STYLE_PERM	String	Values that were set by $SET_PROCESS_PROPERTIESW.
PARSE_STYLE_IMAGE	String	Values that were set by $SET_PROCESS_PROPERTIESW.
PERMANENT_CAP_MASK	Integer	Permanent capabilities mask for the specified kernel thread. See the SET PROCESS/ CAPABILITIES command for additional information.
PERSONA_AUTHPRIV	String	Authorized privilege mask of the persona.
PERSONA_ID	Integer	The ID of the persona as a longword integer.
PERSONA_PERMPRIV	String	Permanent (default) privilege mask of the persona.
PERSONA_RIGHTS	Integer	Binary content of the persona rights list. This item code returns a list of persona rights separated by commas.
PERSONA_RIGHTS_SIZE	Integer	Number of bytes needed to store the persona rights.
PERSONA_WORKPRIV	String	Privilege mask of the working (active) persona.
PGFLQUOTA	Integer	Paging file quota (maximum virtual page count).
PHDFLAGS	Integer	Flags word.
PID	String	Process identification number.
PPGCNT	Integer	Process page count.
PRCCNT	Integer	Number of subprocesses owned by the process.
PRCLM	Integer	Subprocess quota.
PRCNAM	String	Process name.
PRI	Integer	Process's current priority.
PRIB	Integer	Process's base priority.
PROC_INDEX	Integer	Process's index number.
PROCESS_RIGHTS	String	Contents of the process's local rights list, including your UIC. This item code returns a list of identifier names separated by commas.
PROCPRIV	String	Process's default privileges.
RIGHTSLIST	String	Contents of all of the process rights lists; the equivalent of PROCESS_RIGHTS plus SYSTEM_RIGHTS. This item code returns a list of identifier names separated by commas.
RIGHTS_SIZE	Integer	Number of bytes required to buffer the rights list. The rights list includes both the system rights list and the process rights list.
SCHED_CLASS_NAME	String	Returns the name of the scheduling class if the process is class scheduled, null string if not.
SHRFILLM	Integer	Maximum number of open shared files allowed for the job to which the process belongs.
SEARCH_SYMLINK_PERM	String	Returns one of the following values: NOWILDCARD WILDCARD NOELLIPSIS
SEARCH_SYMLINK_TEMP	String	Returns one of the following values: NOWILDCARD WILDCARD NOELLIPSIS
SITESPEC	Integer	Per-process site-specific longword.
SLOW_VP_SWITCH	Integer	Number of times this process has issued a vector instruction that enabled an inactive vector processor with a full vector context switch.
STATE	String	Process state.
STS	Integer	First longword of process status flags.
STS2	Integer	Second longword of process status flags.
SUBSYSTEM_RIGHTS	Integer	Binary content of the subsystem rights list. This item code returns a list of subsystem rights separated by commas.
SUBSYSTEM_RIGHTS_SIZE	Integer	Number of bytes needed to store the subsystem rights.
SWPFILLOC	Integer	Location of the swap file.
SYSTEM_RIGHTS	String	Contents of the system rights list for the process. This item code returns a list of identifier names separated by commas.
SYSTEM_RIGHTS_SIZE	Integer	Number of bytes needed to store the system rights.
TABLENAME	String	File specification of the process's current command language interpreter (CLI) table.
TERMINAL	String	Login terminal name for interactive users (1--7 characters)
TMBU	Integer	Termination mailbox unit number.
TOKEN	String	Token size, specified as TRADITIONAL (255 bytes) or EXPANDED (4000 bytes).
TQCNT	Integer	Remaining timer queue entry quota.
TQLM	Integer	Timer queue entry quota.
TT_ACCPORNAM	String	Access port name for the terminal associated with the process.
TT_PHYDEVNAM	String	Physical device name of the terminal associated with the process.
UAF_FLAGS	Integer	User authorization file (UAF)flags from the UAF record of the user who owns the process.
UIC	String	Process's user identification code (UIC).
USERNAME	String	User name string (12 characters filled with trailing blanks).
VIRTPEAK	Integer	Peak virtual address size.
VOLUMES	Integer	Count of currently mounted volumes.
VP_CONSUMER	Boolean	Flag indicating whether the process is a vector consumer.
VP_CPUTIM	Integer	Total amount of time the process has accumulated as a vector customer.
WSAUTH	Integer	Maximum authorized working set size.
WSAUTHEXT	Integer	Maximum authorized working set extent.
WSEXTENT	Integer	Current working set extent.
WSPEAK	Integer	Working set peak.
WSQUOTA	Integer	Working set size quota.
WSSIZE	Integer	Process's current working set limit.

If you use the $GETJPI function to request information on the null processor the swapper process, you can specify any of the items Table 2.5, “F$GETJPI Items” except the following:

ACCOUNT	BYTLM	ENQCNT	ENQLM
EXCVEC	FILCNT	FILM	FINALEXC
IMAGNAME	LOGINTIM	MSGMASK	PAGFILCNT
PGFLQUOTA	PRCCNT	PRCLM	PROCPRIV
SITESPEC	TQCNT	TQLM	USERNAME
VIRTPEAK	VOLUMES	WSPEAK

Examples

$ NAME = F$GETJPI("3B0018","USERNAME")

$ SHOW SYMBOL NAME

NAME = "JANE "

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

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

F$GETQUI

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.

Format

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

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 $GETQUIs ystem service returns an error code, F$GETQUI returns a null string ("").

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_CHARACTERISTIC	Returns information about a specific 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 int hat 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 the or the argument. The following table lists each function argument and corresponding format line to show whether the ,, and 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_OPERATION	F$GETQUI( “CANCEL_OPERATION”) orF $GETQUI ( “ ”)
DISPLAY_CHARACTERISTIC	F$GETQUI( “DISPLAY_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 argument specifies the kind of information you want returned about a particular queue, job, file, form, or characteristic. Table 2.7, “F$GETQUI Items” lists each item code and the data type of the value returned for each item code.

object-id

Corresponds to the $GETQUI system service QUI$SEARCH_NAME, QUI$_SEARCH_NUMBER, and QUI$_SEARCH_JOB_NAME input item codes. The 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 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 Table 2.6, “F$GETQUI Keywords” can be used only with certain function codes.

Table 2.6. F$GETQUI Keywords

Keyword	Valid Function 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 DISPLAY_ENTRY	Selects batch queues.
EXECUTING_JOBS	DISPLAY_ENTRY DISPLAY_JOB	Selects executing jobs.
FREEZE_CONTEXT	DISPLAY_CHARACTERISTIC DISPLAY_ENTRY DISPLAY_FILE DISPLAY_FORM DISPLAY_JOB DISPLAY_MANAGER DISPLAY_QUEUE	When in wildcard mode,prevents advance of wildcard context to the next object.If you do not specify this flag, the context is advanced to the next object.
GENERIC	DISPLAY_ENTRY DISPLAY_QUEUE	Selects generic queues for searching.
HOLDING_JOBS	DISPLAY_ENTRY DISPLAY_JOB	Selects jobs on unconditional hold.
PENDING_JOBS	DISPLAY_ENTRY DISPLAY_JOB	Selects pending jobs.
PRINTER	DISPLAY_QUEUE DISPLAY_ENTRY	Selects printer queues.
RETAINED_JOBS	DISPLAY_ENTRY DISPLAY_JOB	Selects jobs being retained.
SERVER	DISPLAY_QUEUE DISPLAY_ENTRY	Selects server queues.
SYMBIONT	DISPLAY_QUEUE DISPLAY_ENTRY	Selects all output queues. Equivalent to specifying “PRINTER,SERVER,TERMINAL”.
TERMINAL	DISPLAY_QUEUE DISPLAY_ENTRY	Selects terminal queues.
THIS_JOB	DISPLAY_ENTRY DISPLAY_FILE DISPLAY_JOB DISPLAY_QUEUE	Selects all job file information about the calling batch job (entry), the command file being executed, or the queue associated with the calling batch job.
TIMED_RELEASE_JOBS	DISPLAY_ENTRY DISPLAY_JOB	Selects jobs on hold until a specified time.
WILDCARD	DISPLAY_CHARACTERISTIC DISPLAY_ENTRY DISPLAY_FORM DISPLAY_MANAGER DISPLAY_QUEUE	Establishes and saves a context. Because the context is saved, the next operation can be performed based on that context.

Description

Note

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

The F$GETQUI lexical function provides all the features of the$GETQUI system service, including wildcard and nested wildcard operations. For example, in nested wildcard operations, $GETQUI returns information about objects defined within another object. Specifically, this mode allows you to query jobs contained in a selected queue or files contained in a selected job in a sequence of calls. After each call, the system saves the GQC (internal GETQUI context block) so that the GQC can provide the queue or job context necessary for subsequent calls.

Restriction

The GQC that is saved for wildcarded F$GETQUI calls is destroyed if you run any DCL queue-related command, such as SHOW QUEUE or SHOW ENTRY. To avoid this problem, use the SPAWN command to create a new process in which to run the DCL commands.

For more information, see the description of the $GETQUI system service in the HP OpenVMS System Services Reference Manual.

The F$GETQUI function returns information on all items that can be specified with the $GETQUI system service. Table 2.7, “F$GETQUI Items” lists the items you can specify with the F$GETQUI function, the information returned, and the data type of this information.

Table 2.7. F$GETQUI Items

The F$GETQUI lexical function invokes the $GETQUI system service to return information about queues, batch and print jobs currently in those queues,form definitions, and characteristic definitions kept in the system job queue file.

Item	Return Type	Information Returned
ACCOUNT_NAME 1	String	The account name of the owner of the specified job.
AFTER_TIME	String	The system time at or after which the specified job can execute.
ASSIGNED_QUEUE_NAME 1	String	The name of the execution queue to which the logical queue specified in the call to F$GETQUI is assigned.
AUTOSTART_ON	String	A list of nodes or node device pairs indicating where the queue can start.
BASE_PRIORITY	Integer	The priority at which batch jobs are initiated from a batch execution queue or the priority of a symbiont
		process that controls output execution queues.
CHARACTERISTICS 1	String	The characteristics associated with the specified queue or job.
CHARACTERISTIC_NAME	String	The name of the specified characteristic.
CHARACTERISTIC_NUMBER	Integer	The number of the specified characteristic.
CHECKPOINT_DATA 1	String	The value of the DCL symbol BATCH$RESTART when the specified batch job is restarted.
CLI 1	String	The name of the command language interpreter (CLI) used to execute the specified batch job. The file specification returned assumes the device name SYS$SYSTEM and the file type EXE.
COMPLETED_BLOCKS	Integer	The number of blocks that the symbiont has processed for the specified print job. This item code is applicable only to print jobs.
CONDITION_VECTOR 1	Integer	The vector of three longwords. The first longword gives the completion status of the specified job. The second and third longwords give additional status about the print job.
CPU_DEFAULT	String	The default CPU time limit specified for the queue in delta time. This item code is applicable only to batch execution queues.
CPU_LIMIT 1	String	The maximum CPU time limit specified for the specified job or queue in delta time. This item code is applicable only to batch jobs and batch execution queues.
DEFAULT_FORM_NAME	String	The name of the default form associated with the specified output queue.
DEFAULT_FORM_STOCK	String	The name of the paper stock on which thespecified default form is to be printed.
DEVICE_NAME	String	The node and device (or both) on which the specified execution queue is located. For output execution queues, only the device name is returned. The node name is used only in mixed-architecture OpenVMS Cluster systems. The node name is specified by the system parameter SCSNODE for the processor on which the queue executes.
		For batch execution queues, a null string ("") is returned. To get the name of the node on which a batch queue is executing, use the SCSNODE_NAME item.
ENTRY_NUMBER	Integer	The queue entry number of the specified job.
EXECUTING_JOB_COUNT	Integer	The number of jobs in the queue that are currently executing.
FILE_BURST	String	TRUE or FALSE to indicate whether burst and flag pages are to be printed preceding a file.
FILE_CHECKPOINTED 1	String	TRUE or FALSE to indicate whether the specified file is checkpointed.
FILE_COPIES 1	Integer	The number of times the specified file is to be processed. This item code is applicable only to output execution queues.
FILE_COPIES_DONE 1	Integer	The number of times the specified file has been processed. This item code is applicable only to output execution queues.
FILE_COUNT	Integer	The number of files in a specified job.
FILE_DELETE	String	TRUE or FALSE to indicate whether the specified file is to be deleted after execution of request.
FILE_DEVICE 1	String	The internal file-device value that uniquely identifies the selected file. This value specifies the following field in the RMS NAM block: NAM$T_DVI (16 bytes)
FILE_DID 1	String	The internal file-did value that uniquely identifies the selected file. This value specifies the following field in the RMS NAM block: NAM$W_DID (6 bytes)
FILE_DOUBLE_SPACE	String	TRUE or FALSE to indicate whether the symbiont formats the file with double spacing.
FILE_EXECUTING 1	String	TRUE or FALSE to indicate whether the specified file is being processed.
FILE_FLAG	String	TRUE or FALSE to indicate whether a flag page isto be printed preceding a file.
FILE_FLAGS 1	Integer	The processing options that have been selected for the specified file.
		The integer represents a bit field. Tof ind the settings of each bit in the field, use one of the following items in place of FILE_FLAGS: FILE_BURST FILE_DELETE FILE_DOUBLE_SPACE FILE_FLAG FILE_PAGE_HEADER FILE_PAGINATE FILE_PASSALL FILE_TRAILER
FILE_IDENTIFICATION 1	String	The internal file-identification value that uniquely identifies the selected file. This value specifies the following file-identification field in the RMS NAM block: NAM$W_FID (6 bytes)
FILE_PAGE_HEADER	String	TRUE or FALSE to indicate whether a page header is to be printed on each page of output.
FILE_PAGINATE	String	TRUE or FALSE to indicate whether the symbiont paginates output by inserting a form feed whenever output reaches the bottom margin of the form.
FILE_PASSALL	String	TRUE or FALSE to indicate whether the symbiont prints the file in PASSALL mode.
FILE_SETUP_MODULES 1	String	The names of the text modules that are to be extracted from the device control library and copied to the printer before the specified file is printed. This item code is meaningful only for output execution queues.
FILE_SPECIFICATION 1	String	The fully qualified RMS filespecification of the file about which F$GETQUI is returning information.
FILE_STATUS 1	Integer	File status information. The integer represents a bit field. To find the settings of each bit in the field,use one of the following items in place of FILE_STATUS: FILE_CHECKPOINTED FILE_EXECUTING
FILE_TRAILER	String	TRUE or FALSE to indicate whether a trailer page is to be printed following a file.
FIRST_PAGE 1	Integer	The page number at which the printing of the specified file is to begin. This item code is applicable only to output execution queues.
FORM_DESCRIPTION	String	The text string that describes the specified form to users and operators.
FORM_FLAGS	Integer	The processing options that have been selected for the specified form. The integer represents a bit field. To find the settings of each bit in the field, use one of the following items in place of FORM_FLAGS: FORM_SHEET_FEED FORM_TRUNCATE FORM_WRAP
FORM_LENGTH	Integer	The physical length of the specified form in lines. This item code is applicable only to output execution queues.
FORM_MARGIN_BOTTOM	Integer	The bottom margin of the specified form in lines.
FORM_MARGIN_LEFT	Integer	The left margin of the specified form in characters.
FORM_MARGIN_RIGHT	Integer	The right margin of the specified form in characters.
FORM_MARGIN_TOP	Integer	The top margin of the specified form inlines.
FORM_NAME 1	String	The name of the specified form or the mounted form associated with the specified job or queue.
FORM_NUMBER	Integer	The number of the specified form.
FORM_SETUP_MODULES	String	The names of the text modules that are to be extracted from the device control library and copied to the printer before a file is printed on the specified form. This item code is meaningful only fo routput execution queues.
FORM_SHEET_FEED	String	TRUE or FALSE to indicate whether the symbiont pauses at the end of each physical page so that another sheet of paper can be inserted.
FORM_STOCK 1	String	The name of the paper stock on which the specified form is to be printed.
FORM_TRUNCATE	String	TRUE or FALSE to indicate whether the printer discards any
		characters that exceed the specified right margin.
FORM_WIDTH	Integer	The width of the specified form.
FORM_WRAP	String	TRUE or FALSE to indicate whether the printer prints any characters that exceed the specified right margin on the following line.
GENERIC_TARGET	String	The names of the execution queues that are enabled to accept work from the specified generic queue. This item code is meaningful only for generic queues.
HOLDING_JOB_COUNT	Integer	The number of jobs in the queue being held until explicitly released.
INTERVENING_BLOCKS	Integer	The number of blocks associated with pending jobs in the queue that were skipped during the current call to F$GETQUI. These jobs were not reported because they did not match the selection criterion in effect for the call to F$GETQUI.
INTERVENING_JOBS	Integer	The number of pending jobs in the queue that were skipped during the current call to F$GETQUI. These jobs were not reported because they did not match the selection criterion in effect for the call to F$GETQUI.
JOB_ABORTING	String	TRUE or FALSE to indicate whether the system is attempting to abort the execution of a job.
JOB_COMPLETION_QUEUE 1	String	The name of the queue on which the specified job executed.
JOB_COMPLETION_TIME 1	String	The time at which the execution of the specified job completed.
JOB_COPIES 1	Integer	The number of times the specified print job is to be repeated.
JOB_COPIES_DONE 1	Integer	The number of times that the specified print job has been repeated.
JOB_CPU_LIMIT 1	String	TRUE or FALSE to indicate whether a CPU time limit is specified for the job.
JOB_ERROR_RETENTION 1	String	TRUE or FALSE to indicate whether the user requested that the specified job be retained in the queue if the job completes unsuccessfully.
JOB_EXECUTING	String	TRUE or FALSE to indicate whether the specified job is executing or printing.
JOB_FILE_BURST 1	String	TRUE or FALSE to indicate whethera burst page option is explicitly specified for the job.
JOB_FILE_BURST_ONE 1	String	TRUE or FALSE to indicate whether burst and flag pages precede only the first copy of the first file in the job.
JOB_FILE_FLAG 1	String	TRUE or FALSE to indicate whethe ra flag page precedes each file in the job.
JOB_FILE_FLAG_ONE 1	String	TRUE or FALSE to indicate whether a flag page precedes only the first copy of the first file in the job.
JOB_FILE_PAGINATE 1	String	TRUE or FALSE to indicate whether a paginate option is explicitly specified for the job.
JOB_FILE_TRAILER 1	String	TRUE or FALSE to indicatewhether a trailer page follows each file in the job.
JOB_FILE_TRAILER_ONE 1	String	TRUE or FALSE to indicate whether a trailer page follows only the last copy of the last file in the job.
JOB_FLAGS 1	Integer	The processing options selected for the specified job. The integer represents a bit field. To find the settings of each bit in the field, use one of the following items in place of JOB_FLAGS: JOB_CPU_LIMIT JOB_ERROR_RETENTION 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_LOG_DELETE JOB_LOG_NULL JOB_LOG_SPOOL JOB_LOWERCASE JOB_NOTIFY JOB_RESTART JOB_RETENTION_TIME JOB_WSDEFAULT JOB_WSEXTENT JOB_WSQUOTA
JOB_HOLDING	String	TRUE or FALSE to indicate whether the job will be held until it is explicitly released.
JOB_INACCESSIBLE	String	TRUE or FALSE to indicate whether the caller does not have read access to the specific job and file information in the system queue file. When FALSE, the DISPLAY_JOB and DISPLAY_FILE operations can return information for only the following output value item codes: AFTER_TIME COMPLETED_BLOCKS ENTRY_NUMBER INTERVENING_BLOCKS INTERVENING_JOBS JOB_SIZE JOB_STATUS
JOB_LIMIT	Integer	The number of jobs that can execute simultaneously on the specified queue. This item code is applicable only to batch execution queues.
JOB_LOG_DELETE 1	String	TRUE or FALSE to indicate whether the log file is deleted after it is printed.
JOB_LOG_NULL 1	String	TRUE or FALSE to indicate whether a log file is not created.
JOB_LOG_SPOOL 1	String	TRUE or FALSE to indicate whether the job log file is queued for printing when the job is complete.
JOB_LOWERCASE 1	String	TRUE or FALSE to indicate whether the job is to be printed on a printer that can print both uppercase and lowercase letters.
JOB_NAME 1	String	The name of the specified job.
JOB_NOTIFY 1	String	TRUE or FALSE to indicate whether a message is broadcast to a terminal when a job completes or aborts.
JOB_PENDING	String	TRUE or FALSE to indicate whether the job is pending.
JOB_PID	String	The process identification (PID) number of the executing batch job.
JOB_REFUSED	String	TRUE or FALSE to indicate whether the job was refused by the symbiont and is waiting for the symbiont to accept it for processing.
JOB_RESET_MODULES	String	The names of the text modules that are to be extracted from the device control library and copied to the printer before each job in the specified queue is printed. This item
		code is meaningful only for output execution queues.
JOB_RESTART 1	String	TRUE or FALSE to indicate whether the job will restart after a system failure or can be requeued during execution.
JOB_RETAINED	String	TRUE or FALSE to indicate whether the job has completed but is being retained in the queue.
JOB_RETENTION	String	TRUE or FALSE to indicate whether the user requested that the job be retained indefinitely in the queue regardless of the job's completion status.
JOB_RETENTION_TIME 1	String	Returns the system time until which the user requested the job be retained in the queue. The system time may be expressed in either absolute or delta time format.
JOB_SIZE	Integer	The total number of blocks in the specified print job.
JOB_SIZE_MAXIMUM	Integer	The maximum number of blocks that a print job initiated from the specified queue can contain. This item code is applicable only to output execution queues.
JOB_SIZE_MINIMUM	Integer	The minimum number of blocks that a prin job initiated from the specified queue can contain. This item code is applicable only to output execution queues.
JOB_STALLED	String	TRUE or FALSE to indicate whether the specified job is stalled because the physical device on which the job is printing is stalled.
JOB_STARTING	String	TRUE or FALSE to indicate whether the job controller is starting to process the job and has begun communicating with an output symbiont or a job controller on another node.
JOB_STATUS	Integer	The specified job's status flags. The integer represents a bit field. To find the settings of each bit in the field, use one of the following items in place of JOB_STATUS: JOB_ABORTING JOB_EXECUTING JOB_HOLDING JOB_INACCESSIBLE JOB_REFUSED JOB_REQUEUE
		JOB_RESTART JOB_RETAINED JOB_STARTING JOB_TIMED_RELEASE JOB_SUSPENDED JOB_PENDING
JOB_SUSPENDED	String	TRUE or FALSE to indicate whether the job is suspended.
JOB_TIMED_RELEASE	String	TRUE or FALSE to indicate whether the jobis waiting for a specified time to execute.
JOB_WSDEFAULT 1	String	TRUE or FALSE to indicate whether a default working set size is specified for the job.
JOB_WSEXTENT 1	String	TRUE or FALSE to indicate whether a working set extent is specified for the job.
JOB_WSQUOTA 1	String	TRUE or FALSE to indicate whether a working set quota is specified for the job.
LAST_PAGE 1	Integer	The page number at which the printing of the specified file should end. This item code is applicable only to output execution queues.
LIBRARY_SPECIFICATION	String	The name of the device control library for the specified queue. The library specification assumes the device and directory name SYS $LIBRARY and a file type of .TLB. This item code is meaningful only for output execution queues.
LOG_QUEUE 1	String	The name of the queue into which the log file produced for the specified batch job is to be entered for printing. This item code is applicable only to batch jobs.
LOG_SPECIFICATION 1	String	The name of the log file specified for a job. This item code is meaningful only for batch jobs. Use the JOB_LOG_NULL item code to determine whether a log file will be produced.
MANAGER_NAME	String	The queue manager name.
MANAGER_NODES	String	The names of the nodes on which the queuemanager may run.
MANAGER_STATUS	Integer	The specified queue manager's status flags. To find the settings of each bit in the field, use one of the following items in place of MANAGER_STATUS: MANAGER_FAILOVER
		MANAGER_RUNNING MANAGER_START_PENDING MANAGER_STARTING MANAGER_STOPPED MANAGER_STOPPING
NOTE 1	String	The note that is to be printed on the job flag and file flag pages of the specified job. This item code is meaningful only for output execution queues.
OPERATOR_REQUEST 1	String	The message that is to be sent to the queue operator before the specified job begins to execute. This item code is meaningful only for output execution queues.
OWNER_UIC 1	String	The owner user identification code(UIC) of the specified queue.
PAGE_SETUP_MODULES	String	The names of the text modules to be extracted from the device control library and copied to the printer before each page of the specified form is printed.
PARAMETER_1 to PARAMETER_8 1	String	The value of the user-defined parameters that become the value of the DCL symbols P1 to P8respectively.
PENDING_JOB_BLOCK_COUNT	Integer	The total number of blocks for all pending jobs in the queue (valid only for output execution queues).
PENDING_JOB_COUNT	Integer	The number of jobs in the queue in a pending state.
PENDING_JOB_REASON	Integer	The reason that the job is in a pending state. The integer represents a bit field. To find the settings of each bit in the field, use one of the following items in place of PENDING_JOB_REASON: PEND_CHAR_MISMATCH PEND_JOB_SIZE_MAX PEND_JOB_SIZE_MIN PEND_LOWERCASE_MISMATC PEND_NO_ACCESS PEND_QUEUE_BUSY PEND_QUEUE_STATE PEND_STOCK_MISMATCH
PEND_CHAR_MISMATCH	String	TRUE or FALSE to indicate whether the job requires characteristics that are not available on the execution queue.
PEND_JOB_SIZE_MAX	String	TRUE or FALSE to indicate whether the block size of the job
		exceeds the upper block limit of the execution queue.
PEND_JOB_SIZE_MIN	String	TRUE or FALSE to indicate whether the block size of the job is less than the lower limit of the execution queue.
PEND_LOWERCASE_MISMATC	HString	TRUE or FALSE to indicate whether the job requires a lowercase printer.
PEND_NO_ACCESS	String	TRUE or FALSE to indicate whether the ownerof the job does not have access to the execution queue.
PEND_QUEUE_BUSY	String	TRUE or FALSE to indicate whether the job is pending because the number of jobs currently executing on the queue equals thejob limit for the queue.
PEND_QUEUE_STATE	String	TRUE or FALSE to indicate whether the job is pending because the execution queue is not in a running open state.
PEND_STOCK_MISMATCH	String	TRUE or FALSE to indicate whether the stock type required by the job's form does not match the stock type of the form mounted on the execution queue.
PRIORITY 1	Integer	The scheduling priority of the specified job.
PROCESSOR	String	The name of the symbiont image that executes printjobs initiated from the specified queue.
PROTECTION 1	String	The specified queue's protection mask.
QUEUE_ACL_SPECIFIED	String	TRUE or FALSE to indicate whether anaccess control list has been specified for the queue.
QUEUE_ALIGNING	String	TRUE or FALSE to indicate whether the queue is currently printing alignment pages. A queue prints alignment pages when itis restarted from a paused state by using the command START/ QUEUE/ALIGN.
QUEUE_AUTOSTART	String	TRUE or FALSE if the specified queue has been designated as an AUTOSTART queue.
QUEUE_AUTOSTART_INACTIVE	String	TRUE or FALSE if the queue is an autostart queue that will not be automatically started. If TRUE, a START/QUEUE or INIT/QUEUE/
		START command must be issued to restart the queue.
QUEUE_AVAILABLE	String	TRUE or FALSE if the queue is processing one or more jobs but is capable of processing one or more additional jobs.
QUEUE_BATCH	String	TRUE or FALSE to indicate whether the queue is abatch queue or a generic batch queue.
QUEUE_BUSY	String	TRUE or FALSE if the number of jobs currently executing on the queue equals the job limit for the queue.
QUEUE_CLOSED	String	TRUE or FALSE to indicate whether the queue is closed and will not accept new jobs until the queue is put in an open state.
QUEUE_CPU_DEFAULT	String	TRUE or FALSE to indicate whether a default CPU time limit has been specified for all jobs in the queue.
QUEUE_CPU_LIMIT	String	TRUE or FALSE to indicate whether a maximum CPU time limit has been specified for all jobs in the queue.
QUEUE_DESCRIPTION	String	The description of the queue that was defined by using the / DESCRIPTION qualifier with the INITIALIZE/QUEUE command.
QUEUE_DIRECTORY	String	The device and directory specification of the queue database directory for the queue manager.
QUEUE_FILE_BURST	String	TRUE or FALSE to indicate whether burst andflag pages precede each file in each job initiated from the queue.
QUEUE_FILE_BURST_ONE	String	TRUE or FALSE to indicate whether burst and flag pages precede only the first copy of the first file in each job initiated from the queue.
QUEUE_FILE_FLAG	String	TRUE or FALSE to indicate whether a flagpage precedes each file in each job initiated from the queue.
QUEUE_FILE_FLAG_ONE	String	TRUE or FALSE to indicate whether a flag page precedes only the first copy of the first file in each job initiated from the queue.
QUEUE_FILE_PAGINATE	String	TRUE or FALSE to indicate whether the output symbiont
		paginates output for each job initiated from this queue. The output symbiont paginates output by inserting a form feed whenever output reaches the bottom margin of the form.
QUEUE_FILE_TRAILER	String	TRUE or FALSE to indicate whether a trailer page follows each file in each job initiated from the queue.
QUEUE_FILE_TRAILER_ONE	String	TRUE or FALSE to indicate whether a trailer page follows only the last copy of the last file in each job initiated from the queue.
QUEUE_FLAGS	Integer	The processing options that have been selected for the specified queue. The integer represents a bit field. To find the settings of each bit in the field, use one of the following items in place of QUEUE_FLAGS: QUEUE_ACL_SPECIFIED QUEUE_AUTOSTART QUEUE_BATCH QUEUE_CPU_DEFAULT QUEUE_CPU_LIMIT 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_GENERIC QUEUE_GENERIC_SELECTION QUEUE_JOB_BURST QUEUE_JOB_FLAG QUEUE_JOB_SIZE_SCHED QUEUE_JOB_TRAILER QUEUE_NO_INITIAL_FF QUEUE_PRINTER QUEUE_RECORD_BLOCKING QUEUE_RETAIN_ALL QUEUE_RETAIN_ERROR QUEUE_SWAP QUEUE_TERMINAL QUEUE_WSDEFAULT QUEUE_WSEXTENT QUEUE_WSQUOTA
QUEUE_GENERIC	String	TRUE or FALSE to indicate whether the queue is a generic queue.
QUEUE_GENERIC_SELECTION	String	TRUE or FALSE to indicate whether the queue is an execution
		queue that can accept work from a generic queue.
QUEUE_IDLE	String	TRUE or FALSE to indicate whether the queue is not processing any jobs and is capable of doing so or whether the generic queue is capable of feeding executor queues.
QUEUE_JOB_BURST	String	TRUE or FALSE to indicate whether burst andf lag pages precede each job initiated from the queue.
QUEUE_JOB_FLAG	String	TRUE or FALSE to indicate whether a flag page precedes each job initiated from the queue.
QUEUE_JOB_SIZE_SCHED	String	TRUE or FALSE to indicate whether jobs initiated from the queue are scheduled according to size with the smallest job of a given priority processed first. (Meaningful only for output queues.)
QUEUE_JOB_TRAILER	String	TRUE or FALSE to indicate whether a trailer page follows each job initiated from the queue.
QUEUE_LOWERCASE	String	TRUE or FALSE to indicate whether queue is associated with a printer that can print both uppercase and lowercase characters.
QUEUE_NAME 1	String	The name of the specified queue orthe name of the queue that contains the specified job.
QUEUE_PAUSED	String	TRUE or FALSE to indicate whether execution ofall current jobs in the queue is temporarily halted.
QUEUE_PAUSING	String	TRUE or FALSE to indicate whether the queue is temporarily halting execution. Currently executing jobs are completing;temporarily, no new jobs can begin executing.
QUEUE_PRINTER	String	TRUE or FALSE to indicate whether the queueis a printer queue.
QUEUE_RECORD_BLOCKING	String	TRUE or FALSE to indicate whether the symbiont is permitted to concatenate, or block together, the output records it sends to the output device.
QUEUE_REMOTE	String	TRUE or FALSE to indicate whether the queue is assigned to a physical device that is not connected to the local node.
QUEUE_RESETTING	String	TRUE or FALSE to indicate whether the queue is resetting and stopping.
QUEUE_RESUMING	String	TRUE or FALSE to indicate whether the queue is restarting after pausing.
QUEUE_RETAIN_ALL	String	TRUE or FALSE to indicate whether all jobs initiated from the queue remain in the queue after they finish executing. Completed jobs are marked with a completion status.
QUEUE_RETAIN_ERROR	String	TRUE or FALSE to indicate whether only jobs that do not complete successfully are retained in the queue.
QUEUE_SERVER	String	TRUE or FALSE to indicate whether queue processing is directed to a server symbiont.
QUEUE_STALLED	String	TRUE or FALSE to indicate whether the physical device to which the queue is assigned is stalled; that is, the device has not completed the last I/O request submitted to it.
QUEUE_STARTING	String	TRUE or FALSE to indicate whether the queue is starting.
QUEUE_STATUS	Integer	The specified queue's status flags. The integer represents a bit field. To find the settings of each bit in the field, use one of the following items in place of QUEUE_STATUS: QUEUE_ALIGNING QUEUE_AUTOSTART QUEUE_AUTOSTART_INACTIVE QUEUE_AVAILABLE QUEUE_BUSY QUEUE_CLOSED QUEUE_IDLE QUEUE_LOWERCASE QUEUE_PAUSED QUEUE_PAUSING QUEUE_REMOTE QUEUE_RESETTING QUEUE_RESUMING QUEUE_SERVER QUEUE_STALLED QUEUE_STARTING QUEUE_STOP_PENDING QUEUE_STOPPED QUEUE_STOPPING QUEUE_UNAVAILABLE
QUEUE_STOP_PENDING	String	TRUE or FALSE if queue will be stopped when jobs currently in progress have completed.
QUEUE_STOPPED	String	TRUE or FALSE to indicate whether the queue is stopped.
QUEUE_STOPPING	String	TRUE or FALSE to indicate whether the queue is stopping.
QUEUE_SWAP	String	TRUE or FALSE to indicate whether jobs initiated from the queue can be swapped.
QUEUE_TERMINAL	String	TRUE or FALSE to indicate whether the queue is a terminal queue.
QUEUE_UNAVAILABLE	String	TRUE or FALSE to indicate whether the physical device to which queue is assigned is not available.
QUEUE_WSDEFAULT	String	TRUE or FALSE to indicate whether a default working set size is specified for each job initiated from the queue.
QUEUE_WSEXTENT	String	TRUE or FALSE to indicate whether a working set extent is specified for each job initiated from the queue.
QUEUE_WSQUOTA	String	TRUE or FALSE to indicate whether a working set quota is specified for each job initiated from the queue.
RAD	Integer	Value of the RAD. A value of "-1" indicates no RAD value is attributed to the queue. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
REQUEUE_QUEUE_NAME 1	String	The name of the queue to which the specified job is reassigned.
RESTART_QUEUE_NAME 1	String	The name of the queue in which the job will be placed if the job is restarted.
RETAINED_JOB_COUNT	Integer	The number of jobs in the queue retained after successful completion plus those retained on error.
SCSNODE_NAME	String	The 6-byte name of the VMS node on which jobs initiated from the specified queue execute. The node name matches the value of the system parameter SCSNODE for the target node.
SECURITY_INACCESSIBLE	String	TRUE or FALSE to indicate whether the user has read access to the specified queue.
SUBMISSION_TIME 1	String	The time at which the specified job was submitted to the queue.
TIMED_RELEASE_JOB_COUNT	Integer	The number of jobs in the queue on hold until a specified time.
UIC 1	String	The user identification code (UIC) of the owner of the specified job.
USERNAME 1	String	The user name of the owner of the specified job.
WSDEFAULT 1	Integer	The default working set size specified for the specified job or queue. This value is meaningful only for batch jobs and execution and output queues.
WSEXTENT 1	Integer	The working set extent specified for the specified job or queue. This value is meaningful only for batch jobs and execution and output queues.
WSQUOTA 1	Integer	The working set quota for the specified job or queue. This value is meaningful only for batch jobs and execution and output queues.

1Requires Read (R) access if used with one of the function codes:DISPLAY_ENTRY, DISPLAY_JOB, or DISPLAY_FILE.

Examples

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

$ 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 ("").

! 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, call is made toe stablish 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.

$ 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 node name 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.

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

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

F$GETSYI

F$GETSYI — Returns status and identification information about the local system (or abouta 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])

Return Value

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

Arguments

item

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

node-name

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 argument of F$GETSYI to gather information about each node.

Description

The F$GETSYI lexical function invokes the $GETSYI system service to return status and identification information about the local system (or about a node in the local OpenVMS Cluster, if your system is part of a cluster). The F$GETSYI function returns information on the items that can be specified with the $GETSYI

system service. For more information about the $GETSYI system service, see the HP OpenVMS System Services Reference Manual.

You can specify the node for which you want information by supplying either the or the argument, but not both.

Table 2.8, “F$GETSYI Items” lists the items you can specify with the F$GETSYI lexical function.

Table 2.8. F$GETSYI Items

Item	Return Type	Information Returned
ACTIVE_CPU_MASK	Integer	A value that represents a CPU- indexed bitvector. When a particular bit position is set, the processor with that CPU ID value is a member of the instance's active set - those currently participating in the OpenVMS SMP scheduling activities.
ACTIVECPU_CNT	Integer	The count of CPUs actively participating in the current boot of a symmetric multiprocessing (SMP) system.
ARCHFLAG	Integer	Architecture flags for the system.
ARCH_NAME	String	Name of CPU architecture: Alpha for OpenVMS Alpha.
ARCH_TYPE	Integer	Type of CPU architecture; 1 for VAX, 2 for Alpha, and 3 for Integrity servers
AVAIL_CPU_MASK	Integer	A value that represents a CPU- indexed bitvector. When a particular bit position is set, the processor with that CPU ID value is a member of the instance's configure set - those owned by the partition and controlled by the issuing instance.
AVAILCPU_CNT	Integer	The count of CPUs recognized in the system.
BOOT_DEVICE	String	The name of the device from which the system was booted. For a system with a shadowed system disk, BOOT_DEVICE returns the name of the member device from which the shadow set was formed.
BOOTTIME	String	The time the system was booted.
CHARACTER_EMULATED	String	TRUE or FALSE to indicate whether the character string instructions are emulated on the CPU.
CLUSTER_EVOTES	Integer	Total number of votes in the cluster.
CLUSTER_FSYSID	String	System identification number for first node to boot in the cluster (the founding node). This number
		is returned as a character string containing a hexadecimal number.
CLUSTER_FTIME	String	The time when the first node in the cluster was booted.
CLUSTER_MEMBER	String	TRUE or FALSE if the node is a member of the local cluster.
CLUSTER_NODES	Integer	Total number of nodes in the cluster, as an integer.
CLUSTER_QUORUM	Integer	Total quorum for the cluster.
CLUSTER_VOTES	Integer	Total number of votes in the cluster.
CONSOLE_VERSION	String	Console firmware version.
CONTIG_GBLPAGES	Integer	Total number of free, contiguous global pages.
COMMUNITY_ID	Integer	The hardware community ID for the issuing instance within the hard partition. Supported only on AlphaServer systems that support partitioning.
CPU_AUTOSTART	Integer	A list of zeroes and ones, separated by commands and indexed by CPU ID. Any entry with a value of one indicates that specific CPU will be brought into the OpenVMS active set if it transitions into the current instance from outside, or is powered up while already owned.
CPU_FAILOVER	Integer	List of numeric partition IDs, separated by commas and indexed by CPU ID, that define the destination of the processor if the current instance should crash. Supported only on AlphaServer systems that support partitioning.
CPUCAP_MASK	String	List of hexadecimal values, separated by commas and indexed by CPU ID. Each individual value represents a bitvector; when set, the corresponding user capability is enabled for that CPU.
CPUTYPE	Integer	On Alpha, the processor type, as stored in the hardware restart parameter block (HWRPB). The value of 2represents a DECchip 21064 processor.
CWLOGICALS	Boolean	Flag indicating that the clusterwide logical name database has been initialized on the CPU.
DECIMAL_EMULATED	String	TRUE or FALSE to indicate whether the decimal string
		instructions are emulated on the CPU.
DECNET_FULLNAME	String	The node name of a DECnet Phase IV system or the node full name of a DECnet-Plus system.
DECNET_VERSION	String	The information on the particular version and ECO level of the DECnet package installed on the local system. This item returns a string containing a hexadecimal number, using the following format: Byte 0 = Customer ECO Byte 1 = DECnet ECO Byte 2 = DECnet phase (4 for Phase IV, 5 for DECnet-Plus for OpenVMS) Byte 3 = Reserved To distinguish Phase IV from DECnet-Plus for OpenVMS, use the byte containing the DECnet version (byte 2). For additional information on interpreting byte 0 and byte 1, see the current HP DECnet-Plus for OpenVMS Release Notes documentation.
D_FLOAT_EMULATED	String	TRUE or FALSE to indicate whether the D_floating instructions are emulated on the CPU.
ERLBUFFERPAGES	Integer	Number of pagelets on Alpha and Integrity servers used for each S0 error log buffer.
ERLBUFFERPAG_S2	Integer	Number of system pagelets(on Alpha and Integrity servers used for each S2 error log buffer.)
ERRORLOGBUFF_S2	Integer	Number of S2 error log buffers.
ERRORLOGBUFFERS	Integer	Number of S0 error log buffers.
F_FLOAT_EMULATED	String	TRUE or FALSE to indicate whether th eF_floating instructions are emulated on the CPU.
FREE_GBLPAGES	Integer	Current count of free global pages.
FREE_GBLSECTS	Integer	Current count of free global section table entries.
FREE_PAGES	Integer	Total number of free pages.
G_FLOAT_EMULATED	String	TRUE or FALSE to indicate whether the G_floating instructions are emulated on the CPU.
DDAGGALAXY_ID	Integer	The 128-bit Galaxy ID. Supported only on AlphaServer GS series systems.
DDAGGALAXY_MEMBER	Integer	1 if member of a Galaxy sharing community, 0 if not. Supported only on AlphaServer GS series systems.
DDAGGALAXY_PLATFORM	Integer	1 if running on a Galaxy platform, 0 if not. Supported only on AlphaServer GS series systems.
DDAGGALAXY_SHMEMSIZE	Integer	The number of shared memory pages. If the current instance is not a member of a Galaxy, no shared memory is reported. Supported only on AlphaServer GS series systems.
DDAGGH_RSRVPGCNT	Integer	On Alpha, number of pages covered by granularity hints to reserve for use by the INSTALL utility after system startup has completed.
DDAGGLX_FORMATION	String	A time-stamp string when the Galaxy configuration, of which this instance is a member, was created. Supported only on AlphaServer GS series systems.
DDAGGLX_MAX_MEMBERS	Integer	The maximum count of instances that may join the current Galaxy configuration. Supported only on AlphaServer GS series systems.
GLX_MBR_MEMBER	Integer	A 64-byteinteger. Each 8 bytes represents a Galaxy member number, listed from 7 to0. The value is 1 if the instance is currently a member, 0 if not a member. Supported only on AlphaServer GS series systems.
GLX_MBR_NAME	String	A string indicating the names which are known in the Galaxy membership. Supported only on AlphaServer GS series systems.
GLX_TERMINATION	String	A time-stamp string when the Galaxy configuration, of which this instance last was a member, was terminated. Supported only on AlphaServer GS series systems.
HP_ACTIVE_CPU_CNT	Integer	The count of CPUs in the hard partition that are not currently in firmware console mode. For OpenVMS, this implies that the CPU is in, or in the process of
		joining,the active set in one of the instances in the hard partition. Supported only on AlphaServer systems that support partitioning.
HP_ACTIVE_SP_CNT	Integer	The count of active operating system instances currently executing within the hard partition. Supported only on AlphaServer systems that support partitioning.
HP_CONFIG_SBB_CNT	Integer	A count of theexisting system building blocks within the current hard partition. Supported only on AlphaServer systems that support partitioning.
HP_CONFIG_SP_CNT	Integer	The maximumcount of soft partitions within the current hard partition. This countdoes not imply that an operating system instance is currently runningwithin any given soft partition. Supported only on AlphaServer systems that support partitioning.
HW_MODEL	Integer	An integer that identifies the Alpha node's model type. An integer greater than 1023 represents the Alpha operating system.
HW_NAME	String	The Alpha model name.
DDAGITB_ENTRIES	Integer	On Alpha, number of I-stream translation buffer entries that support granularity hints to be allocated for resident code.
DDAGMAX_CPUS	Integer	The maximum number of CPUs that could be recognized by this instance.
MEMSIZE	Integer	Number of pages of memory in the system configuration.
MODIFIED_PAGES	Integer	Total number of modified pages.
MULTITHREAD	Integer	Value of the MULTITHREAD system parameter.
NODENAME	String	Node name (does not include the following double colon).
NODE_AREA	Integer	The DECnet area for the target node.
NODE_CSID	String	The CSID of the specified node, as a string containing a hexadecimal number. The CSID is a form of system identification.
NODE_EVOTES	Integer	Number of votes allotted to the node.
NODE_HWVERS	String	Hardware version of the specified node.
NODE_NUMBER	Integer	The DECnet number for the specified node.
NODE_QUORUM	Integer	Quorum that the node has.
NODE_SWINCARN	String	Software incarnation number for the specified node. This number is returned as a string containing a hexadecimal number.
NODE_SWTYPE	String	Type of operating system software used by the specified node.
NODE_SWVERS	String	Software version of the specified node.
NODE_SYSTEMID	String	System identification number for the specified node. This number is returned as a string containing a hexadecimal number.
NODE_VOTES	Integer	Number of votes allotted to the node.
NPAGED_FREE	Integer	Number of free bytes in nonpaged pool.
NPAGED_INUSE	Integer	Total number of bytes currently being used in nonpaged pool.
NPAGED_LARGEST	Integer	Size of the largest contiguous area of free memory in nonpaged pool.
NPAGED_TOTAL	Integer	Total size (in bytes) of nonpaged pool.
PAGED_FREE	Integer	Number of free bytes in paged pool.
PAGED_INUSE	Integer	Total number of bytes currently being used in paged pool.
PAGED_LARGEST	Integer	Size of the largest contiguous area of free memory in paged pool.
PAGED_TOTAL	Integer	Total size (in bytes) of paged pool.
PAGEFILE_FREE	Integer	Number of free pages in the currently installed paging files.
PAGEFILE_PAGE	Integer	Number of pages in the currently installed paging files.
PAGE_SIZE	Integer	Indicates the number of bytes in a physical page.
PALCODE_VERSION	String	Version of the PALCODE(privileged architectural library) on your Alpha system.
PARTITION_ID	Integer	The soft partition ID. Supported only on AlphaServer systems that support partitioning.
POTENTIAL_CPU_MASK	Integer	A value that represents a CPU- indexed bitvector. When a particular
		bit position is set, the processor with that CPU ID value is a member of the instance's potential set. A CPU in the potential set implies that it could actively join the OpenVMS active set for this instance if it is ever owned by it. To meet this rule the CPU's characteristics must match hardware and software compatibility rules defined particularly for that instance.
POTENTIALCPU_CNT	Integer	The count of CPUs in the hard partition that are members of the potential set for this instance. A CPU in the potential set implies that it could actively joint he OpenVMS active set for this instance if it is ever owned by it. To meet this rule the CPU's characteristics must match hardware and software compatibility rules defined particularly for that instance.
POWERED_CPU_MASK	Integer	A value that represents a CPU- indexed bitvector. When a particular bit position is set, the processor with that CPU ID value is a member of the instance's powered set -those CPUs physically existing within the hard partition and powered up fo roperation.
POWEREDCPU_CNT	Integer	The count of CPUs in the hard partition that are physically powered up.
PRESENT_CPU_MASK	Integer	A value that represents a CPU- indexed bitvector. When a particular bit position is set, the processor with that CPU ID value is a member of the instance's present set -those CPUs physically existing within the hard partition. Being in the present set does not imply that it is part of the powered set.
PRESENTCPU_CNT	Integer	The count of CPUs in the hard partition that physically reside in a hardware slot.
PRIMARY_CPUID	Integer	The CPU ID of the primary processor for this OpenVMS instance.
QUANTUM	Integer	Maximum amount of processor time a process can receive while other processes are waiting.
RAD_CPUS	Integer	List of RAD, CPU pairs,separated by commas. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
RAD_MAX_RADS	Integer	The maximum number of RADS possible on this platform. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
RAD_MEMSIZE	Integer	List of RAD, PAGES pairs, separated by commas. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
RAD_SHMEMSIZE	Integer	List of RAD,PAGESpairs, separated by commas. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
REAL_CPUTYPE	Integer	The actual CPU type of the primary CPU of the system extracted from the hardware restart parameter block (HWRPB).
SCS_EXISTS	String	TRUE or FALSE to indicate whether the system communication subsystem (SCS) is currently loaded on a VMS node.
DDAGSCSNODE	String	The Galaxy instance name. Supported only on AlphaServer systems that support partitioning.
SID	Integer	System identification register. On Alpha, returns a value where all fields are zero except the CPU type field, which always contains the value of 256.
SWAPFILE_FREE	Integer	Number of free pages in the currently installed swapping files.
SWAPFILE_PAGE	Integer	Number of pages in the currently installed swapping files.
SYSTEM_RIGHTS	String	The contents of the system rights list on the local system. If you specify a remote system, a null string ("")is returned. This item
		returns a list of identifier names separated by commas (,).
SYSTEM_UUID	Integer	The 128-bit Universal Unique Identifier (UUID) for the system.
SYSTYPE	Integer	On Alpha, the family or system hardware platform. For example, the integer 2 represents a DEC 4000, the integer 3 represents a DEC 7000 or DEC 10000, and the integer 4 represents a DEC 3000.
TOTAL_PAGES	Integer	Total number of physical memory pages.
USED_GBLPAGCNT	Integer	Number of pages currently in use in the global page table.
USED_GBLPAGMAX	Integer	Maximum number of pages ever in use in the global page table.
USED_PAGES	Integer	Total number of used pages.
VECTOR_EMULATOR	Boolean	Flag indicating the presence of the VAX vector instruction emulator facility (VVIEF) in the system.
VERSION	String	Version of OpenVMS in use (8- character stringfilled with trailing blanks).
VP_MASK	Integer	Mask indicating which processors in the system have vector coprocessors.
VP_NUMBER	Integer	Number of vector processors in the system.

DDAGAlpha only

SIntegrity servers only

Examples

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

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

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

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

$ 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 R D,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.

F$IDENTIFIER

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)

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

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 HP OpenVMS Guide to System Security

conversion-type

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

Examples

$ 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].

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

F$INTEGER

F$INTEGER — Returns the integer equivalent of the result of the specified expression.

Format

F$INTEGER(expression)

Return Value

An integer value that is equivalent to the specified expression.

Arguments

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.

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.

F$LENGTH

F$LENGTH — Returns the length of the specified character string.

Format

F$LENGTH(string)

Return Value

An integer value for the length of the string.

Arguments

string

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

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.

F$LICENSE (Alpha/Integrity servers Only)

F$LICENSE (Alpha/Integrity servers Only) — Checks whether the specified license is loaded on the system.

Format

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

Return Value

A character string stating TRUE or FALSE.

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 HP is assumed to be the producer on Integrity server systems. To find an exception, specify a different producer name.

Examples

$ SHOW LICENSE VMSCLUSTER*

Active licenses on node NODE1:

------- Product ID -------- ---- Rating ----- -- Version -- Product Producer Units Avail Activ Version Release

Termination

VMSCLUSTER

DEC

100

0.0 (none)

14-

MAY-2005

VMSCLUSTER-CLIENT

DEC

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.

$ 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 HP). In the second instance, an ABC PAK is found for producer XYZ.

F$LOCATE

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)

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

Arguments

substring

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

string

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

Examples

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

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

F$MATCH_WILD

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)

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.

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.

F$MESSAGE

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])

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.

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.

Table 2.9, “F$MESSAGE Keywords” describes the valid system message component keywords:

Table 2.9. F$MESSAGE 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 (, ).

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
$ ! CODE

$ ELSE

$ IF "%JOBABORT" .EQS. F$MESSAGE (JOB_STATUS, "IDENT")

$ THEN
$ ! CODE

$ ELSE
$ ! CODE

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

F$MODE

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()

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.

Arguments

None.

Description

The lexical function 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.

The F$MODE function is useful in command procedures that must operate differently when executed interactively and noninteractively. You should include either the F$MODE function or the F$ENVIRONMENT function in your login command file to execute different commands for interactive terminal sessions and noninteractive sessions.

If you do not include the F$MODE function to test whether your login command file is being executed from an interactive process, and the login command file is executed from a noninteractive process (such as a batch job), the process may terminate if the login command file contains commands that are appropriate only for interactive processing.

A command procedure can use the F$MODE function to test whether the procedure is being executed during an interactive terminal session.
It can direct the flow of execution according to the results of this test.

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 non interactive 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.

F$MULTIPATH

F$MULTIPATH — (Alpha/Integrity servers Only). Returns a specified item of information for a specific multipath-capable device.

Format

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

Return Value

A character string containing the requested information.

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

Description

Invokes the $DEVICE_PATH_SCAN system service to return a specified item of information for a specific multipath-capable device.

The F$MULTIPATH lexical function also returns any error messages generated by the $DEVICE_PATH_SCAN system service. For more information about the $DEVICE_PATH_SCAN system service, see the HP OpenVMS System Services Reference Manual.

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

F$PARSE

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])

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 argument, the F$PARSE function supplies defaults in the return string. For more information, see the Description section for this lexical function.

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.

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 argument is missing. You can make
further substitutions in the argument by using the

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 and arguments.

field

Specifies a character string containing the name of a field in a file specification. Specifying the 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 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_ONLY	The syntax of the file specification is checked without verifying that the specified directory exists on the specified device.

Description

The F$PARSE function parses file specifications by using the RMS service $PARSE. For more information on the $PARSE service, see the OpenVMS Record Management Services Reference Manual.

When you use the F$PARSE function, you can omit those optional arguments to the right of the last argument you specify. However, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument you specify.

If you omit the device and directory names in the argument, the F$PARSE function supplies defaults, first from the argument and second from the argument. If names are not provided by these arguments, the F$PARSE function uses your current default disk and directory.

If you omit the node name, the file name, the file type, or the version number, the F$PARSE function supplies defaults, first from the argument and second from the argument. (Note that the version number is not picked up from the argument.) If names are not provided by these arguments, the F$PARSE function returns a null specification for these fields.

The parse operation simply validates that the provided file specification is syntactically correct; it does not enforce file specification semantics. For example, fields such as the version number are verified to contain five or fewer numeric digits, optionally preceded by a hyphen (-), but are not range checked. File specification semantics are enforced by services such as Open and Create.

Examples

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

$ 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 and arguments are omitted from the argument list, commas (,) must be inserted in their place.

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

F$PID

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

Format

F$PID(context-symbol)

Return Value

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

Arguments

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 fitst he 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.

Description

The F$PID function returns a process identification (PID) number and updates the context symbol to point to the current position in the system's process list. You can step through all the processes on a system, or use the lexical function F$CONTEXT to specify selection criteria. The function F$CONTEXT is not required.

The PIDs returned by the F$PID function depend on the privilege of your process. If you have GROUP privilege, the F$PID function returns PIDs o processes in your group. If you have WORLD privilege, the F$PID function returns PIDs of all processes on the system. If you lack GROUP or WORLD privilege, the F$PID function returns only those processes that you own.

The F$CONTEXT function enables the F$PID function to retrieve processes from any node in a mixed-architecture OpenVMS Cluster system.

The first time you use the F$PID function, use a symbol that is either undefined or equated to the null string or to a context symbol that has been created by the F$CONTEXT function. This causes the F$PID function to return the first PID in the system's process list that you have the privilege to access. It also causes the F$PID function to initialize the argument.

Once the argument is initialized, each subsequent F$PID returns the next PID in sequence, using the selection criteria set up by the F$CONTEXT function, if any, and updates the context symbol. After the last PID in the process list is returned, the F$PID function returns a null string.

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

F$PRIVILEGE

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)

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 argument list is false.

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.

Description

Use the F$PRIVILEGE function to identify your current process privileges.

If “NO” precedes the privilege, the privilege must be disabled in order for the function to return a value of TRUE. The F$PRIVILEGE function checks each of the keywords in the specified list, and if the result for any one is false, the string FALSE is returned.

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.

F$PROCESS

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

Format

F$PROCESS()

Return Value

A character string containing the current process name.

Arguments

None.

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.

F$SEARCH

F$SEARCH — Searches a directory file and returns the full file specification for a file you specify.

Format

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

Return Value

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

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 argument contains the asterisk (*) or the percent sign (%) wildcard characters, each time F$SEARCH is called, the next file specification that agrees with the argument is returned. A null string is returned after the last file specification that agrees with the 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 arguments. If you use the F$SEARCH function more than once in a command procedure and if you also use different arguments, specify arguments to identify each search separately.

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

Description

The lexical function F$SEARCH invokes the RMS service $SEARCH to search a directory file and return the full file specification for a file you specify. The F$SEARCH function allows you to search for files in a directory by using the RMS service $SEARCH. For more information on the $SEARCH routine, see the OpenVMS Record Management Services Reference Manual.

You can use the F$SEARCH function in a loop in a command procedure to return file specifications for all files that match a argument containing an asterisk (*) or a percent sign (%) wildcard character. Each time the F$SEARCH function is executed, it returns the next file specification that matches the file specification that contains a wildcard character. After the last file specification is returned, the next F$SEARCH call returns a null string. When you use the F$SEARCH function in a loop, you must include an asterisk (*) or the percent sign (%) wildcard characters in the argument; otherwise, the F$SEARCH always returns the same file specification.

Note that you must maintain the context of the search stream in one of the following ways:

Explicitly, by stating a argument

Implicitly, by omitting the argument and by using the same argument each time you execute the F$SEARCH function

If you do not maintain the context of the search stream, you start a new search at the beginning of the directory file each time you specify a different argument.

Note

The lexical function F$SEARCH can return any file that matches the selection criteria you specify, and that exists in the directory at some time between the beginning and the end of the search. Files that are created, renamed, or deleted during the search may or may not be returned.

Examples

$ 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 argument SYS$SYSTEM:*.EXE is surrounded by quotation marks (“ ”) because it is a character string expression. Because no argument is specified, the F$SEARCH function uses a single search stream. Each subsequent F$SEARCH call uses the same 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.

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

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

F$SETPRV

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.

Format

F$SETPRV(priv-states)

Return Value

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

$SETPRV function.

Arguments

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 VSI
OpenVMS User's Manual.

Description

The lexical function F$SETPRV invokes the $SETPRV system service to enable or disable 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.

Note

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.

The F$SETPRV function returns keywords for your current privileges, whether or not you are authorized to change the privileges listed in the argument; however, the F$SETPRV function enables or disables only the privileges you are authorized to change.

When you run programs or execute procedures that include the F$SETPRV function, be sure that F$SETPRV restores your process to its proper privileged state. For additional information, see the examples that follow.

Examples

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

$ 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 system wide global sections

SYSLCK may lock system wide 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)

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

F$STRING

F$STRING — Returns the string that is equivalent to the specified expression.

Format

F$STRING(expression)

Return Value

A character string equivalent to the specified expression.

Arguments

expression

The integer or string expression to be evaluated.

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

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

Example

$ A = 5

$ B = F$STRING(-2 + A)

$ SHOW SYMBOL B

B = "3"

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

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

F$TIME

F$TIME — Returns the current date and time in absolute time format. The F$TIME function has no arguments, but must be followed
by parentheses.

Format

F$TIME()

Return Value

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

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 12characters from the beginning of the string.

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

Arguments

None.

Example

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

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

F$TRNLNM

F$TRNLNM — Translates a logical name and returns the equivalence name string or the requested attributes of the logical name specified.

Format

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

Return value

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

Arguments

logical-name

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

table

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

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

LNM$SYSTEM_DIRECTORY

LNM$PROCESS_DIRECTORY

Note

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

$ SHOW LOGICAL/STRUCTURE LNM$DCL_LOGICAL

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

If you do not specify a table, the default value is LNM$DCL_LOGICAL. That is, the F$TRNLNM function searches the tables whose names are equated to the logical name LNM$DCL_LOGICAL. Unless LNM$DCL_LOGICAL has been redefined for your process, the F$TRNLNM function searches the process, job, group, and system logical name tables, in that order, and returns the equivalence name of 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 he 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 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 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 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, regardlessof 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 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 nullstring ("").

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

item

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

Item	Return Type	Information Returned
ACCESS_MODE	String	One of the following access modes associated with the logical name: USER, SUPERVISOR, EXECUTIVE, KERNEL.
CLUSTERWIDE	String	TRUE or FALSE to indicate whether the logical name is in a clusterwide name table.
CONCEALED	String	TRUE or FALSE to indicate whether the CONCEALED attribute was specified with the / TRANSLATION_ATTRIBUTES qualifier when the logical name was created. The CONCEALED attribute is used to create a concealed logical name.
CONFINE	String	TRUE or FALSE to indicate whether the logical name is confined. If the logical name is confined (TRUE), then the name is not copied to subprocesses. If the logical name is not confined (FALSE),then the name is copied to subprocesses.
CRELOG	String	TRUE or FALSE to indicate whether the logical name was created with the $CRELOG system service or with the $CRELNM system service, using the CRELOG attribute. If the logical name was created with the $CRELOG system service or with the $CRELNM system service, using the CRELOG attribute, then TRUE is returned. Otherwise, FALSE is returned.
LENGTH	Integer	Length of the equivalence name associated with the specified logical name. If the logical name has more
		than one equivalence name, the F $TRNLNM function returns the length of the name specified by the index argument.
MAX_INDEX	Integer	The largest index defined for the logical name. The index shows how many equivalence names are associated with a logical name. The index is zero based; that is, the index zero refers to the first name in a list of equivalence names.
NO_ALIAS	String	TRUE or FALSE to indicate whether the logical name has the NO_ALIAS attribute. The NO_ALIAS attribute means that a logical name must be unique within outer access mode.
TABLE	String	TRUE or FALSE to indicate whether the logical name is the name of a logical name table.
TABLE_NAME	String	Name of the table where the logical name was found.
TERMINAL	String	TRUE or FALSE to indicate whether the TERMINAL attribute was specified with the / TRANSLATION_ATTRIBUTES qualifier when the logical name was created. The TERMINAL attribute indicates that the logical name is not a candidate for iterative translation.
VALUE	String	Default. The equivalence name associated with the specified logical name. If the logical name has more than one equivalence name, the F$TRNLNM function returns the name specified by the index argument.

Description

The lexical function F$TRNLNM uses the $TRNLNM system service to translate a logical name and return the equivalence name string, or the requested attributes of the logical name specified. The translation is not iterative;the equivalence string is not checked to determine whether it is a logical name.

When you use the F$TRNLNM function, you can omit optional arguments that can be used to the right of the last argument you specify. However, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument that you specify.

You can use the F$TRNLNM function in command procedures to save the current equivalence of a logical name and later restore it. You can also use it to test whether logical names have been assigned.

Examples

$ 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 namestring.

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.

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

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

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

$ FOO = F$TRNLNM("FOO","LNM$SYSCLUSTER",,,"INTERLOCKED,CASE_SENSITIVE",)

This example specifies both case sensitive and interlocked translation.

F$TYPE

F$TYPE — Returns the data type of a symbol. The string INTEGER is returned if the symbol is equated to an integer, or if the symbol is equated to a string whose characters form a valid integer. The string STRING is returned if the symbol is equated to a character string whose characters do not form a valid integer. If the symbol is undefined, a null string ("") is returned.

Format

F$TYPE(symbol-name)

Return Value

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

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

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

If the symbol is a context symbol, then the return value will be one of the types shown in Table 2.10, “Context Symbol Types”.

Table 2.10. Context Symbol Types

Symbol Type	Lexical Creating Symbol
PROCESS_CONTEXT	F$PID or F$CONTEXT (with PROCESS context type )
CLUSTER_SYSTEM_CONTEXT	F$CSID

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.

Arguments

Specifies the name of the symbol to be evaluated.

Examples

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

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

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

$ 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 argument value CANCEL.

F$UNIQUE (Alpha/Integrity servers Only)

F$UNIQUE (Alpha/Integrity servers Only) — Generates a string that is suitable to be a file name and is guaranteed to be unique across the cluster. Unique file names can be useful when creating temporary files. (See CLOSE/ DISPOSITION for an example.) The F$UNIQUE function has no arguments, but must be followed by a blank pair of parentheses.

Format

F$UNIQUE()

Return Value

A character string containing the unique string.

Arguments

None.

Examples

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

$ OPEN/WRITE TEMP_FILE 'F$UNIQUE()

$ DIRECTORY

Directory WORK1:[TEST] 594B53554C421C9C11D75463D61F58B7.DAT;1

Total of 1 file.

$ CLOSE/DISPOSITION=DELETE TEMP_FILE

$ DIRECTORY

%DIRECT-W-NOFILES, no files found

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

F$USER

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

Format

F$USER()

Return Value

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

Arguments

None.

Example

$ UIC = F$USER()

$ SHOW SYMBOL UIC

UIC = "[GROUP6,JENNIFER]"

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

F$VERIFY

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

Format

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

Return Value

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

Arguments

procedure-value

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

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

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

image-value

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

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

Description

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

Using the F$VERIFY function in command procedures allows you to test the current procedure verification setting. For example, a command procedure can save the current procedure verification setting before changing it and then later restore the setting. In addition, you can construct a procedure that does not display (or print) commands, regardless of the initial state of verification.

When you use the F$VERIFY function, you can specify zero, one, or two arguments. If you do not specify any arguments, neither of the verification settings is changed. If you specify only the argument, both procedure and image verification are turned on (if the value is1) or off (if the value is 0).

If you specify both arguments, procedure and image verification are turned on or off independently. If you specify the argument alone, only image verification is turned on or off. If you specify the argument alone, you must precede the argument with a comma (,).

You can also use the F$ENVIRONMENT function with VERIFY_PROCEDURE or VERIFY_IMAGE as the argument. With the F$ENVIRONMENT function, you can determine either the procedure or image verification setting; the F$VERIFY function determines only the procedure verification setting.

DCL performs the F$VERIFY function even if it appears after a comment character, if it is enclosed in single quotation marks (` '). This is the only processing that DCL performs within a comment.

Example

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

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