HP OpenVMS Systems Documentation
OpenVMS DCL Dictionary
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.
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.
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 ("").
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.
Converts the specified bits in the specified character string to a signed number.
The integer equivalent of the extracted bit field, converted as a signed value.
$ A[0,32] = %X2B $ SHOW SYMBOL A A = "+..." $ X = F$CVSI(0,4,A) $ SHOW SYMBOL X X = -5 Hex = FFFFFFFB Octal = 37777777773
This example uses an arithmetic overlay to assign the hexadecimal value 2B to all 32 bits of the symbol A. For more information on arithmetic overlays, see the description of the assignment statement (=).
The symbol A has a string value after the overlay because it was previously undefined. (If a symbol is undefined, it has a string value as a result of an arithmetic overlay. If a symbol was previously defined, it retains the same data type after the overlay.) The hexadecimal value 2B corresponds to the ASCII value of the plus sign (+).
Next, the F$CVSI function extracts the low-order 4 bits from the symbol A; the low-order 4 bits contain the binary representation of the hexadecimal value B. These bits are converted, as a signed value, to an integer. The converted value, --5, is assigned to the symbol X.
$ 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.
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.
F$CVTIME ([input_time] [,output_time_format] [,output_field])
input_timeSpecifies a string containing absolute, a delta, or a combination time, or TODAY, TOMORROW, or YESTERDAY. Specify the input time string as a character string expression. If the input_time argument is omitted or is specified as a null string (""), the current system date and time, in absolute format, is used. If parts of the date field are omitted, the missing values default to the current date. If parts of the time field are omitted, the missing values default to zero.
For more information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
If the input_time argument is a delta time, you must specify the output_time_format argument as DELTA.
output_time_formatSpecifies the time format for the information you want returned. Specify the output_time_format argument as one of the following character string expressions:
ABSOLUTE The requested information should be returned in absolute time format, which is dd-mmm-yyyy hh:mm:ss.cc. Single-digit days are returned with no leading space or zero. COMPARISON
The requested information should be returned in the form yyyy-mm-dd hh:mm:ss.cc (used for comparing two times). DELTA The requested information should be returned in delta format, which is dddd-hh:mm:ss.cc. If you specify DELTA as the output_time_format argument, then you must also provide a delta time specification for the input_time argument.
output_fieldSpecifies a character string expression containing one of the following (do not abbreviate): DATE, MONTH, DATETIME (default), SECOND, DAY, TIME, HOUR, WEEKDAY, HUNDREDTH, YEAR, MINUTE. The information is returned in the time format specified by the output_time_format argument. If the input_time argument is a delta time and the output_time_format argument is DELTA, you cannot specify MONTH, WEEKDAY, or YEAR.
When the weekday is returned, the first letter is in uppercase, and the following letters are in lowercase.
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 output_time_format argument; you cannot specify DELTA.
When specifying the input_time argument in delta time format, you must specify DELTA as the output_time_format argument.
$ TIME = F$TIME() $ SHOW SYMBOL TIME TIME = "14-DEC-2001 10:56:23.10" $ TIME = F$CVTIME(TIME) $ SHOW SYMBOL TIME TIME = "2001-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, the F$CVTIME returns the weekday that corresponds to the absolute time keyword "TOMORROW". You must enclose the arguments "TOMORROW" and "WEEKDAY" in quotation marks because they are character string expressions. Also, you must include a comma as a placeholder for the output_time_format argument that is omitted.
Extracts bit fields from character string data and converts the result to an unsigned number.
start-bitSpecifies 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-bitsSpecifies 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.
stringSpecifies the character string to be edited.
$ 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.
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.
F$DEVICE ([search_devnam],[devclass],[devtype], [stream-id])
search_devnamSpecifies the name of the device for which F$DEVICE is to search. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the search_devnam argument.
Specify the search_devnam argument as a character string expression.
devclassSpecifies the device class for which F$DEVICE is to search. Specify the devclass argument as a character string expression that corresponds to a valid device class name.
See the DEVCLASS item in F$GETDVI for additional information.
devtypeSpecifies the device type for which F$DEVICE is to search. Specify the devtype argument as a character string expression that corresponds to a valid type name.
See the DEVTYPE item in F$GETDVI for additional information.
Specifying a device type without specifying a device class will result in an error.
stream-idA positive integer representing the search stream identification number.
The search stream identification number is used to maintain separate search contexts when you use the F$DEVICE function more than once and when you supply different search criteria. If you use the F$DEVICE function more than once in a command procedure and if you also use different search criteria, specify stream-id arguments to identify each search separately.
If the search criteria are changed in a call before the device name list is exhausted, the context will be reinitialized and the search will restart.
If you omit the stream-id argument, the F$DEVICE function assumes an implicit single search stream. That is, the F$DEVICE function starts searching at the beginning each time you specify different search criteria.
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 stream-id argument) or implicitly (by omitting the stream-id 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.
$ START: $ DEVICE_NAME = F$DEVICE("*0:","DISK","RA60") $ IF DEVICE_NAME .EQS. "" THEN EXIT $ SHOW SYMBOL DEVICE_NAME $ GOTO START
This command procedure displays the device names of all the RA60s on a unit numbered 0.
Because no stream-id argument is specified, F$DEVICE uses an implicit search stream. Each subsequent use of the F$DEVICE function uses the same search criteria to return the next device name. After the last device name is displayed, the F$DEVICE function returns a null string and the procedure exits.
Returns the current default directory name string. The F$DIRECTORY function has no arguments, but must be followed by parentheses.
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 to do work, and to later restore the original setting.
$ SAVE_DIR = F$DIRECTORY() $ SET DEFAULT [CARLEN.TESTFILES] . . . $ SET DEFAULT 'SAVE_DIR'
This example shows an excerpt from a command procedure that uses the F$DIRECTORY function to save the current default directory setting. The assignment statement equates the symbol SAVE_DIR to the current directory. Then the SET DEFAULT command establishes a new default directory. Later, the symbol SAVE_DIR is used in the SET DEFAULT command that restores the original default directory.
Note that you can use the F$ENVIRONMENT function with the DEFAULT keyword to return the default disk and directory. You should use the F$ENVIRONMENT function rather than the F$DIRECTORY function in situations involving more than one disk.
Edits the character string based on the edits specified in the edit-list argument.
F$EDIT (string, edit-list)
stringSpecifies a character string to be edited. Quoted sections of the string are not edited.
edit-listSpecifies 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.
When UPCASE is specified with LOWERCASE in an edit-list, UPCASE takes precedence.
$ 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.