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[,...]])
1 – 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.
2 – 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.
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.
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.)
3 – Directives
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.
Here is a summary of the FAO directives you can specify in a
control string.
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:
o Quadword numeric directives, which are not supported
in DCL because all DCL numeric values are stored and
manipulated as longwords.
o 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, see the VSI OpenVMS System Services Reference
Manual.
Argument
Directive 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 Inserts the current time.
equal to 0
!%D Integer Inserts the current date/time.
equal to 0
Argument interpretation:
!- None Reuses the last argument.
!+ None Skips the next argument.
4 – Examples
1.$ COUNT = 57
$ REPORT = F$FAO("NUMBER OF FORMS = !SL",COUNT)
$ SHOW SYMBOL REPORT
REPORT = "NUMBER OF FORMS = 57"
In this command procedure, the FAO directive !SL is used in
a control string to convert the number equated to the symbol
COUNT to a character string. The converted string is inserted
into the control string.
Note that COUNT is assigned an integer value of 57. The F$FAO
function returns the ASCII string, "NUMBER OF FORMS = 57", and
assigns the string to the symbol REPORT.
2.$ A = "ERR"
$ B = "IS"
$ C = "HUM"
$ D = "AN"
$ PHRASE = F$FAO("TO !3(AS)",A,B,C+D)
$ SHOW SYMBOL PHRASE
$ PHRASE = "TO ERRISHUMAN"
In this command procedure, the !AS directive is used to insert
the values assigned to the symbols A, B, C, and D into the
control string.
Because the specified repeat count for the !AS directive is 3,
F$FAO looks for three arguments. The arguments in this example
include the symbol A ("ERR"), the symbol B ("IS"), and the
expression C+D ("HUMAN"). Note that the values of these string
arguments are concatenated to form the string "ERRISHUMAN".
3.$ A = "ERR"
$ B = "IS"
$ C = "HUMAN"
$ PHRASE = F$FAO("TO !#(#AS)",3,6,A,B,C)
$ SHOW SYMBOL PHRASE
$ PHRASE = "TO ERR IS HUMAN "
In this command procedure, the F$FAO function is used with
the !AS directive to format a character string. The first
number sign (#) represents the repeat count given by the
first argument, 3. The second number sign represents the field
size given by the second argument, 6. The next three arguments
(A,B,C) provide the strings that are placed into the control
string each time the !AS directive is repeated.
Each argument string is output to a field having a length of
6 characters. Because each string is less than 6 characters,
each field is left-justified and padded with blank spaces. The
resulting string is assigned to the symbol PHRASE.
4.$ OFFSPRING = 1
$ REPORT = F$FAO-
("There !0UL!1%Cis!%Eare!%F !-!UL !-!0UL!1%Cchild!%Echildren!%F here",OFFSPRING)
$ SHOW SYMBOL REPORT
$ REPORT ="There is 1 child here"
In this command procedure, the !0UL directive evaluates the
argument OFFSPRING but does not insert the value in the output
string. The !n%C directive inserts the character string "is"
into the output string because its value and the value of the
argument OFFSPRING match. The directives !-!UL evaluate the
argument a second time so that the correct character string can
be inserted in the proper place in the output string. The !%F
directive marks the end of each plurals statement. The F$FAO
function returns the ASCII string "There is 1 child here" and
assigns the string to the symbol REPORT.