HP OpenVMS Systems Documentation

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("BJOBLIM")
$ SHOW SYMBOL LIM
  LIM = 16   Hex = 00000010  Octal = 00000000020
      

This example uses the system parameter BJOBLIM 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 RAD,CPU pairs, separated by commas. In this example, the first RAD,CPU pair is 0,0, the second pair is 0,1, and so forth.

Supported only on AlphaServer GS series systems.

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

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, refer to the HP OpenVMS Guide to System Security.

conversion-type

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

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.

Returns the integer equivalent of the result of the specified expression.

Format

F$INTEGER (expression)

Return Value

Argument

expression

Specifies the expression to be evaluated. Specify either an integer or a character string expression.

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

After evaluating a string expression, the F$INTEGER function converts the result to an integer in the following way. If the resulting string contains characters that form a valid integer, the F$INTEGER function returns the integer value. If the string contains characters that do not form a valid integer, the F$INTEGER function returns the integer 1 if the string begins with T, t, Y, or y. The function returns the integer 0 if the string begins with any other character.

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.

Returns the length of the specified character string.

Format

F$LENGTH (string)

Return Value

Argument

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.

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

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 string 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 string argument FILE_SPEC is a symbol, so it should not be placed within quotation marks. It is automatically replaced by its current value during the processing of the function.

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

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

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, refer to 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 DCLI-11 describes the valid system message component keywords:

Table DCLI-11 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
       .
           .
           .
$ ELSE
$    IF "%JOBABORT" .EQS. F$MESSAGE (JOB_STATUS, "IDENT")
$    THEN
        .
            .
            .
$    ELSE
$       .
            .
            .
$    ENDIF
$ ENDIF
  .
  .
  .

      

This command procedure submits a batch job and waits for it to complete. Upon successful completion, the procedure exits. If the job completes unsuccessfully, more processing is done based on the termination status of the batch job.

The first command submits the command procedure IMPORTANT.COM. In the second command, the SYNCHRONIZE command tells the procedure to wait for the job to finish. The third command determines if the job completed successfully and, if so, the procedure exits. The next command saves the status in a symbol.

The first IF statement uses F$MESSAGE to determine whether the job was deleted before execution. If so, it does some processing, possibly to resubmit the job or to inform a user via MAIL.

The next IF statement uses F$MESSAGE to determine whether the job was deleted during execution. As a result, some cleanup or human intervention may be required, which would be done in the THEN block.

If neither IF statement was true, then some other unsuccessful status was returned. Other processing, which would be done in the block following the ELSE statement, might be required.

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

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 noninteractive mode (including batch and network jobs). The IF command compares the character string returned by F$MODE with the character string INTERACTIVE; if they are not equal, control branches to the label NON_INT_DEF. If the character strings are equal, the statements following the label INTDEF are executed and the procedure exits before the statements at NON_INT_DEF.

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

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

related-spec

Specifies a character string containing the related file specification.

The fields in the related file specification are substituted in the output string if a particular field is missing from both the filespec and default-spec arguments.

field

Specifies a character string containing the name of a field in a file specification. Specifying the field argument causes the F$PARSE function to return a specific portion of a file specification.

Specify one of the following field names (do not abbreviate):

NODE	Node name
DEVICE	Device name
DIRECTORY	Directory name
NAME	File name
TYPE	File type
VERSION	File version number

parse-type

Specifies the type of parsing to be performed. By default, the F$PARSE function verifies that the directory in the file specification exists on the device in the file specification; however, the existence of the directory is not verified if you provide a field argument. Note that the device and directory can be explicitly given in one of the arguments, or can be provided by default.

Also, by default the F$PARSE function translates logical names if they are provided in any of the arguments. The F$PARSE function stops iterative translation when it encounters a logical name with the CONCEALED attribute.

You can change how the F$PARSE function parses a file specification by using one of the following keywords:

NO_CONCEAL	Ignores the "conceal" attribute in the translation of a logical name as part of the file specification; that is, logical name translation does not end when a concealed logical name is encountered.
SYNTAX_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, refer to 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 filespec argument, the F$PARSE function supplies defaults, first from the default-spec argument and second from the related-spec 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 default-spec argument and second from the related-spec argument. (Note that the version number is not picked up from the related-spec argument.) If names are not provided by these arguments, the F$PARSE function returns a null specification for these fields.

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 default-spec argument in the assignment statement, it is used as the directory name in the output string. Note that the default device returned in the output string is DISK2, and the default version number for the file is null. You must place quotation marks (" ") around the arguments JAMES.MAR and ROOT because they are string literals.

If you had not specified syntax-only parsing, and [ROOT] were not on DISK2, a null string would have been returned.

$ SET DEFAULT DB1:[VARGO]
$ SPEC = F$PARSE("INFO.COM",,,"DIRECTORY")
$ SHOW SYMBOL SPEC
  SPEC = "[VARGO]"

      

In this example the F$PARSE function returns the directory name of the file INFO.COM. Note that because the default-spec and related-spec arguments are omitted from the argument list, commas (,) must be inserted in their place.

$ SPEC= F$PARSE("DENVER::DB1:[PROD]RUN.DAT",,,"TYPE")
$ SHOW SYMBOL SPEC
  SPEC = ".DAT"

      

---

Previous

Next

Contents

Index