 |
HP OpenVMS DCL Dictionary
HP OpenVMS DCL Dictionary
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 you to
directly invoke images (for example, RUN is not allowed). 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 HP 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.
|
