HP OpenVMS Systems Documentation

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

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

Arguments

context-symbol

Specifies a symbol that DCL uses to store a pointer into the system's list of clustered nodes. The F$CSID function uses this pointer to return a cluster identification number.

Specify the context-symbol argument by using a symbol. The first time you use the F$CSID function, use a symbol that is either undefined or equated to the null string.

If the context-symbol argument is undefined or equated to a null string, the F$CSID function returns the cluster identification number of the first system in the system's cluster node list. Subsequent calls to the F$CSID function will return the cluster identification number of the rest of the nodes in the cluster.

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 value is 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 context-symbol 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 context-symbol argument for the F$CSID function. Because CONTEXT is equated to a null string, the F$CSID function will return the first cluster identification number in the cluster node list.

If the F$CSID function returns a null value, then the command procedure either is at the end of the list, or is attempting this operation on a nonclustered node. The call to F$GETSYI checks whether the current node is a member of a cluster. The command procedure will exit on this condition.

If the F$CSID function does not return a null value, then the command procedure uses the identification number as the third argument to the F$GETSYI function to obtain the name of the system. The name is then displayed using the WRITE command.

Converts the specified bits in the specified character string to a signed number.

Format

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

Return 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 is invalid when added to the bit position offset, then DCL displays the INVRANGE error message.

string

Specifies the string from which the bits are taken. Specify the string as a character string expression.

Examples

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

Format

F$CVTIME ([input_time] [,output_time_format] [,output_field])

Return Value

Arguments

input_time

Specifies a string containing absolute, a delta, or a combination time, or TODAY, TOMORROW, or YESTERDAY. Specify the input time string as a character string expression. If the input_time argument is omitted or is specified as a null string (""), the current system date and time, in absolute format, is used. If parts of the date field are omitted, the missing values default to the current date. If parts of the time field are omitted, the missing values default to zero.

For more information on specifying time values, 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_format

Specifies the time format for the information you want returned. Specify the output_time_format argument as one of the following character string expressions:

ABSOLUTE	The requested information should be returned in absolute time format, which is dd-mmm-yyyy hh:mm:ss.cc. Single-digit days are returned with no leading space or zero.
COMPARISON (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 output_time_format argument, then you must also provide a delta time specification for the input_time argument.

output_field

Specifies a character string expression containing one of the following (do not abbreviate): DATE, MONTH, DATETIME (default), SECOND, DAY, TIME, HOUR, WEEKDAY, HUNDREDTH, YEAR, MINUTE. 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.

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

Examples

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

Format

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

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

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.

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

Arguments

search_devnam

Specifies the name of the device for which F$DEVICE is to search. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the search_devnam argument.

Specify the search_devnam argument as a character string expression.

devclass

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

See the DEVCLASS item in F$GETDVI for additional information.

devtype

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

See the DEVTYPE item in F$GETDVI for additional information.

Note Specifying a device type without specifying a device class will result in an error.

stream-id

A positive integer representing the search stream identification number.

The search stream identification number is used to maintain separate search contexts when you use the F$DEVICE function more than once and when you supply different search criteria. If you use the F$DEVICE function more than once in a command procedure and if you also use different search criteria, specify stream-id arguments to identify each search separately.

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

If you omit the stream-id argument, the F$DEVICE function assumes an implicit single search stream. That is, the F$DEVICE function starts searching at the beginning each time you specify different search criteria.

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

Example

$ START:
$     DEVICE_NAME = F$DEVICE("*0:","DISK","RA60")
$     IF DEVICE_NAME .EQS. "" THEN EXIT
$     SHOW SYMBOL DEVICE_NAME
$     GOTO START
      

This command procedure displays the device names of all the RA60s on a unit numbered 0.

Because no stream-id argument is specified, F$DEVICE uses an implicit search stream. Each subsequent use of the F$DEVICE function uses the same search criteria to return the next device name. After the last device name is displayed, the F$DEVICE function returns a null string and the procedure exits.

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

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

Format

F$EDIT (string, edit-list)

Return Value

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.