HELPLIB.HLB  —  Lexicals  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[,...]])

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.
Close Help