HP OpenVMS Systems Documentation
OpenVMS DCL Dictionary
Extracts one element from a string of elements.
F$ELEMENT (element-number, delimiter, string)
A character string containing the specified element.
$ 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 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.
Returns information about the current DCL command environment.
itemSpecifies 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.
$ 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 depth allowable 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 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.
Extracts the specified characters from the specified string.
startSpecifies 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 ("").
lengthSpecifies 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.
stringSpecifies the character string to be edited. Specify the string as a character string expression.
$ 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.
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.
control-stringSpecifies 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.)
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.
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
!%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
!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.
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