Updated: 11 December 1998

OpenVMS DCL Dictionary

Extracts one element from a string of elements.

Format

F$ELEMENT (element-number, delimiter, string)

Return Value

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

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

Format

F$ENVIRONMENT (item)

Return Value

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

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

Format

F$EXTRACT (start,length,string)

Return Value

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

$ NAME = "BRIAN MACKRILL"
$ FIRST = F$EXTRACT(0,5,NAME)
$ SHOW SYMBOL FIRST
  FIRST = "BRIAN"
 
      

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.

Format

F$FAO (control-string[,argument[,...]])

Return Value

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

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

9996PRO_028.HTML