Document revision date: 30 March 2001

## OpenVMS DCL Dictionary

Previous | Contents | Index

## 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 element-number argument as an integer expression. If the element-number argument exceeds the number of elements in the string, F$ELEMENT returns the delimiter.

> #### delimiter

> Specifies a character used to separate the elements in the string. Specify the delimiter as a character string expression.

> #### string

> Specifies a string containing a delimited list of elements. Specify the string as a character string expression.

###

#### Examples

#1
    $ DAY_LIST = "MON/TUE/WED/THU/FRI/SAT/SUN"
    $ INQUIRE DAY "ENTER DAY (MON TUE WED THU FRI SAT SUN)"
    $ NUM = 0
    $ LOOP:
    $       LABEL = F$ELEMENT(NUM,"/",DAY_LIST)
    $       IF LABEL .EQS. "/" THEN GOTO END
    $       IF DAY .EQS. LABEL THEN GOTO 'LABEL'
    $       NUM = NUM +1
    $       GOTO LOOP
    $
    $ MON:
       .
       .
       .

> This example sets up a loop to test an input value against the elements in a list of values. If the value for DAY matches one of the elements in DAY_LIST, control is passed to the corresponding label. If the value returned by the F$ELEMENT function matches the delimiter, the value DAY was not present in the DAY_LIST, and control is passed to the label END.

#2
    $ ! INDEX.COM
    $ !
    $ CHAPTERS = "0,1,2,3,4,5,6,A,B,C"
    $ NEXT = 0
    $ LOOP:
    $   NEXT = NEXT + 1
    $   NUM = F$ELEMENT(NEXT,",",CHAPTERS)
    $   IF (NUM .NES. ",")
    $   THEN
    $      RUN INDEX CHAP'NUM'
    $      GOTO LOOP
    $   ENDIF

> This example processes files named CHAP1, CHAP2, ... CHAP6, CHAPA, CHAPB, and CHAPC, in that order. (Zero is included in the CHAPTERS string to initialize the procedure logic.) NEXT is initialized to zero. The procedure enters the loop. In the first iteration, NEXT is incremented to 1 and the result of the F$ELEMENT call is the string "1". The procedure runs the index, chapter 1. In the second iteration, NEXT is incremented to 2 and the result of the F$ELEMENT call is the string "1". The procedure runs the index, chapter 2. Processing continues until the result of the F$ELEMENT call is the delimiter specified in the call.

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

### Argument

> #### 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 SET CONTROL. Multiple characters are separated by commas; if no control characters are enabled, the null string ("") is returned.
> DEFAULT | String | Current default device and directory name. The returned string is the same as SHOW DEFAULT output.
> DEPTH | Integer | Current command procedure depth. The command procedure depth is 0 when you log in interactively and when you submit a batch job. The command procedure depth is 1 when you execute a command procedure interactively or from within a batch job. A nested command procedure has a depth of 1 greater than the depth of the command procedure from which the nested procedure is executed.
> DISIMAGE | String | TRUE if you are logged in to an account that does not allow the use of the RUN and MCR commands or foreign commands. The system manager can add or remove the DISIMAGE attribute for accounts in the UAF by using AUTHORIZE.
> INTERACTIVE | String | TRUE if the process is executing interactively.
> KEY_STATE | String | Current locked keypad state. See the description of the DEFINE/KEY command for more information on keypad states.
> MAX_DEPTH | Integer | Maximum allowable command procedure depth.
> MESSAGE | String | Current setting of SET MESSAGE qualifiers. Each qualifier in the string is prefaced by a slash (/); therefore, the output from F$ENVIRONMENT("MESSAGE") can be appended to the SET MESSAGE command to form a valid DCL command line.
> NOCONTROL | String | Control characters currently disabled with SET NOCONTROL. Multiple characters are separated by commas (,); if no control characters are disabled, the null string is returned.
> ON_CONTROL_Y | String | If issued from a command procedure, returns TRUE if ON_CONTROL_Y is set. ON_CONTROL_Y always returns FALSE at DCL command level.
> ON_SEVERITY | String | If issued from a command procedure, returns the severity level at which the action specified with the ON command is performed. ON_SEVERITY returns NONE when SET NOON is in effect or at DCL command level.
> OUTPUT_RATE | String | Delta time string containing the default output rate, which indicates how often data is written to the batch job log file while the batch job is executing. OUTPUT_RATE returns a null string if used interactively.
> PROCEDURE | String | File specification of the current command procedure. If used interactively, the terminal device name is returned.
> PROMPT | String | Current DCL prompt.
> PROMPT_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 SET VERIFY=PROCEDURE is in effect. If command verification is in effect, then the command procedure echoes DCL command lines.

###

#### Examples

#1
    $ SAVE_MESSAGE = F$ENVIRONMENT("MESSAGE")
    $ SET MESSAGE/NOFACILITY/NOIDENTIFICATION
       .
       .
       .
    $ SET MESSAGE'SAVE_MESSAGE'

> This example uses the F$ENVIRONMENT function to save the current message setting before changing the setting. At the end of the command procedure, the original message setting is restored. The single quotation marks (` ') surrounding the symbol SAVE_MESSAGE indicate that the value for the symbol should be substituted.

#2
    $ MAX = F$ENVIRONMENT("MAX_DEPTH")
    $ SHOW SYMBOL MAX
      MAX = 32   Hex = 00000020  Octal = 00000000040

> This example uses the F$ENVIRONMENT function to determine the maximum depth allowable within command procedures.

#3
    $ SAVE_PROT = F$ENVIRONMENT("PROTECTION")
    $ SET PROTECTION = (SYSTEM:RWED, OWNER:RWED, GROUP, WORLD)/DEFAULT
       .
       .
       .
    $ SET PROTECTION = ('SAVE_PROT')/DEFAULT

> This example uses the F$ENVIRONMENT function to save the current default protection before changing the protection. At the end of the command procedure, the original protection is restored. You must place single quotation marks around the symbol SAVE_PROT to request symbol substitution.

## 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 start and length 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

#1
    $ NAME = "PAOLO TESTA"
    $ FIRST = F$EXTRACT(0,5,NAME)
    $ SHOW SYMBOL FIRST
      FIRST = "PAOLO"

> This portion of a command procedure uses the F$EXTRACT function to extract the first 5 characters from the character string assigned to the symbol NAME. The offset and length arguments are integers, and the string argument is a symbol. You do not need to use quotation marks (" ") around integers or symbols when they are used as arguments for lexical functions.

#2
    $ P1 = "MYFILE.DAT"
    $ FILENAME = F$EXTRACT(0,F$LOCATE(".",P1),P1)

> This portion of a command procedure shows how to locate a character within a string, and how to extract a substring ending at that location.

> The lexical function F$LOCATE gives the numeric value representing the offset position of a period in the character string value of P1. (The offset position of the period is equal to the length of the substring before the period.)

> This F$LOCATE function is used as an argument in the F$EXTRACT function to specify the number of characters to extract from the string. If a procedure is invoked with the parameter MYFILE.DAT, these statements result in the symbol FILENAME being given the value MYFILE.

> Note that the F$LOCATE function in the above example assumes that the file specification does not contain a node name or a directory specification containing a subdirectory name. To obtain the file name from a full file specification, use the F$PARSE function.

#3
    $ IF F$EXTRACT(12,2,F$TIME()) .GES. "12" THEN GOTO AFTERNOON
    $ MORNING:
    $ WRITE SYS$OUTPUT "Good morning!"
    $ EXIT
    $ AFTERNOON:
    $ WRITE SYS$OUTPUT "Good afternoon!"
    $ EXIT

> This example shows a procedure that displays a different message, depending on whether the current time is morning or afternoon. It first obtains the current time of day by using the F$TIME function. The F$TIME function returns a character string, which is the string argument for the F$EXTRACT function. The F$TIME function is automatically evaluated when it is used as an argument, so you do not need to use quotation marks.

> Next, the F$EXTRACT function extracts the hours from the date and time string returned by F$TIME. The string returned by F$TIME always contains the hours field beginning at an offset of 12 characters from the start of the string.

> The F$EXTRACT function extracts 2 characters from the string, beginning at this offset, and compares the string value extracted with the string value 12. If the comparison is true, then the procedure writes "Good afternoon!". Otherwise, it writes "Good morning!".

> Note that you can also use the F$CVTIME function to extract the hour field from a time specification. This method is easier than the one shown in the above example.

## 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 DCLI-4 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 DCLI-4 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 DCLI-4 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, refer to the OpenVMS System Services Reference Manual.

> Table DCLI-4 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.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 9996PRO_028.HTML