/sys$common/syshlp/helplib.hlb System Services, $FAO  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Converts a binary value into an ASCII character string in
    decimal, hexadecimal, or octal notation; returns the character
    string in an output string; and inserts variable character-string
    data into an output string.

    The Formatted ASCII Output with List Parameter ($FAOL) service
    provides an alternate method for specifying input parameters when
    calling the $FAO system service.

    On Alpha systems, this service accepts 64-bit addresses.

    Format

      SYS$FAO  ctrstr ,[outlen] ,outbuf ,[p1]...[pn]

      SYS$FAOL  ctrstr ,[outlen] ,outbuf ,[prmlst]

    C Prototype

      int sys$fao  (void *ctrstr, unsigned short int *outlen, void

                   *outbuf,...);

      int sys$faol  (void *ctrstr, unsigned short int *outlen, void

                    *outbuf, void *prmlst);

    Arguments

 ctrstr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor (Alpha)
    mechanism:    by 32-bit descriptor-fixed-length string descriptor
                  (VAX)
    Control string passed to $FAO that contains the text to be output
    together with one or more $FAO directives. $FAO directives are
    used to specify repeat counts or the output field length, or
    both, and they are preceded by an exclamation point (!).  The
    ctrstr argument is the 32- or 64-bit address (on Alpha systems)
    or the 32-bit address (on VAX systems) of a character string
    descriptor pointing to the control string.

    There is no restriction on the length of the control string or
    on the number of $FAO directives it can contain; however, if an
    exclamation point must appear in the output string, it must be
    represented in the control string by a double exclamation point
    (!!).  A single exclamation point in the control string indicates
    to $FAO that the next characters are to be interpreted as FAO
    directives.

    When $FAO processes the control string, it writes to the output
    buffer each character that is not part of an $FAO directive.

    If the $FAO directive is valid, $FAO processes it. If the
    directive requires a parameter, $FAO processes the next
    consecutive parameter in the specified parameter list. If the
    $FAO directive is not valid, $FAO terminates and returns a
    condition value in R0.

    The $FAO service reads parameters from the argument list
    specified in the call; these arguments have the names p1, p2,
    p3, and so on, up to p17. Each argument specifies one parameter.
    Because $FAO accepts a maximum of 17 parameters in a single call,
    you must use $FAOL if the number of parameters exceeds 17. The
    $FAOL service accepts any number of parameters used with the
    prmlst argument.

 outlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha)
    mechanism:    by 32-bit reference (VAX)
    Length in bytes of the fully formatted output string returned
    by $FAO. The outlen argument is the 32- or 64-bit address (on
    Alpha systems) or the 32-bit address (on VAX systems) of a word
    containing this value.

 outbuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor (Alpha)
    mechanism:    by 32-bit descriptor-fixed-length string descriptor
                  (VAX)
    Output buffer into which $FAO writes the fully formatted output
    string. The outbuf argument is the 32- or 64-bit address (on
    Alpha systems) or the 32-bit address (on VAX systems) of a
    character string descriptor pointing to the output buffer. The
    maximum number of bytes written is limited to 64K.

 p1 to pn

    OpenVMS usage:varying_arg
    type:         quadword (signed)
    access:       read only
    mechanism:    by value
    $FAO directive parameters. The p1 argument is a quadword
    containing the parameter needed by the first $FAO directive
    encountered in the control string, the p2 argument is a quadword
    containing the parameter needed for the second $FAO directive,
    and so on for the remaining arguments up to p17. If an $FAO
    directive does not require a parameter, that $FAO directive is
    processed without reading a parameter from the argument list.

    Depending on the directive, a parameter can be a value to be
    converted, a 32- or 64-bit address of a string to be inserted
    into the output string, or a length or argument count. Each
    directive in the control string might require a corresponding
    parameter or parameters.

 prmlst

    OpenVMS usage:vector_longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha)
    mechanism:    by 32-bit reference (VAX)
    List of $FAO directive parameters to be passed to $FAOL. The
    prmlst argument is the 32- or 64-bit address (on Alpha systems)
    or the 32-bit address (on VAX systems) of a list of longwords
    wherein each longword is a parameter. The $FAOL service processes
    these parameters sequentially as it encounters, in the control
    string, $FAO directives that require parameters.

    The parameter list can be a data structure that already exists in
    a program and from which certain values are to be extracted.