HP OpenVMS Systems Documentation

HP OpenVMS System Services Reference Manual

Table SYS-37 shows the $FAO output field lengths and their fill characters.

Required Access or Privileges

None

Required Quota

None

Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_BUFFEROVF	The service completed successfully. The formatted output string overflowed the output buffer and has been truncated.
SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The ctrstr, p1 through pn, or prmlst arguments cannot be read, or the outlen argument cannot be written (it can specify 0).
SS$_BADPARAM	You specified an invalid directive in the $FAO control string.
SS$_OVERMAXARG	Maximum parameter count exceeded.

$FAO Control String Examples

Each of the following examples shows an $FAO control string with several directives, parameters defined as input for the directives, and the calls to $FAO to format the output strings.

Each example is accompanied by notes. These notes show the output string created by the call to $FAO and describe in more detail some considerations for using directives. The sample output strings show the underscore character (_) for each space in all places where $FAO output contains multiple spaces.

Each of the first 10 examples (numbered 1 through 10) refers to the following output fields but does not include these fields within the examples.

int status, /* Status of system calls */ outlen; /* Length of output string from $FAO */ char out_buffer[80]; /* Buffer for $FAO output */ $DESCRIPTOR(out_desc, out_buffer); /* Descriptor for out_buffer */

Each of the 10 examples also assumes the caller of each example will check the returned status, and write the output string produced by $FAO if no error occurred. The following code fragment shows how the example call may be made, and the resultant string output to the user's terminal.

#include <stdio.h> #include <stsdef.h> #include <lib$routines.h> . . . status = example(); /* Immediately signal (and quit) if error occurred */ if ((status & STS$M_SUCCESS) == 0) lib$signal(status); /* FAO directive succeeded, output resultant string */ out_buffer[outlen] = '\0'; /* add string terminator to buffer */ puts(out_buffer); /* output the result */

The final example (numbered 11) shows a segment of a HP Fortran for OpenVMS program used to output an ASCII string.

/* SYS$FAO example - illustrating !AC, !AS, !AD, and !/ directives */
#include <string.h>
#include <descrip.h>
#include <starlet.h>

/* MACRO and typedef for counted ASCII strings... */
typedef struct {char len, str[25];} ASCIC;
#define ASCIC_STRING(name, string) ASCIC name = {sizeof(string) - 1, string}

int example()
{
    char    *nod = "Nod";               /* Normal "C" string */
    const int nodlen = strlen(nod); /* Length of "Nod" without '\0' */
    static  ASCIC_STRING(winken, "Winken");
    static  $DESCRIPTOR(blinken, "Blinken");
    static  $DESCRIPTOR(fao_desc, "!/Sailors: !AC !AS !AD");

    return (sys$fao(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    &winken,    /* P1 - Counted ASCII string */
                    &blinken,   /* P2 - ASCII string descriptor */
                    nodlen,     /* P3 - Length of ASCII string */
                    nod));      /* P4 - ASCII string */
}

      

$FAO writes the following string into the output buffer:

<CR><KEY>(LF\TEXT)Sailors: Winken Blinken Nod

The !/ directive provides a carriage-return/line-feed character (shown as <CR><KEY>(LF\TEXT)) for terminal output.

The !AC directive requires the address of a counted ASCII string (p1 argument).

The !AS directive requires the address of a character string descriptor (p2 argument).

The !AD directive requires two parameters: the length of the string to be substituted (p3 argument) and its address (p4 argument).

/*
** SYS$FAO example - illustrating !! and !AS directives,
** repeat count, and output field length
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(jones, "Jones");
    static $DESCRIPTOR(harris, "Harris");
    static $DESCRIPTOR(wilson, "Wilson");
    static $DESCRIPTOR(fao_desc, "Unable to locate !3(8AS)!!");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   &jones,      /* P1 - ASCII string descriptor */
                   &harris,     /* P2 - ASCII string descriptor */
                   &wilson));   /* P3 - ASCII string descriptor */
}
      

$FAO writes the following string into the output buffer:

Unable to locate Jones___Harris__Wilson__!

The !3(8AS) directive contains a repeat count: three parameters (addresses of character string descriptors) are required. $FAO left-justifies each string into a field of eight characters (the output field length specified).

The double exclamation point directive (!!) supplies a literal exclamation point (!) in the output.

If the directive were specified without an output field length, that is, if the directive were specified as !3(AS), the three output fields would be concatenated, as follows:

Unable to locate JonesHarrisWilson!

/* SYS$FAO example - illustrating !UL, !XL, and !SL directives */
#include <descrip.h>
#include <starlet.h>

int example()
{
    int val1 = 200,             /* Values */
        val2 = 300,             /*  for   */
        val3 = -400;            /*   $FAO */

    static $DESCRIPTOR(fao_desc,
                       "Values !UL (Decimal) !XL (Hex) !SL (Signed)");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   val1,        /* P1 - longword value */
                   val2,        /* P2 - longword value */
                   val3));      /* P3 - longword value */
}
      

$FAO writes the following string to the output buffer:

Values 200 (Decimal) 0000012C (Hex) -400 (Signed)

The longword value 200 is converted to decimal, the value 300 is converted to hexadecimal, and the value --400 is converted to signed decimal. The ASCII results of each conversion are placed in the appropriate position in the output string.

Note that the hexadecimal output string has eight characters and is zero-filled to the left. This is the default output length for hexadecimal longwords.

/* SYS$FAOL example - illustrating !UL, !XL, and !SL directives */
#include <descrip.h>
#include <starlet.h>

int example()
{
    static int values[3] = {200, 300, -400};   /* Parameters for $FAOL */
    static $DESCRIPTOR(fao_desc,
                       "Values !UL (Decimal) !XL (Hex) !SL (Signed)");

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    values));   /* Parameter list - longwords */
}
      

$FAOL writes the following string to the output buffer:

Values 200 (Decimal) 0000012C (Hex) -400 (Signed)

The results are the same as the results of Example 3; however, unlike the $FAO directive, which requires each parameter on the call to be specified, the $FAOL directive points to a list of consecutive longwords, which $FAO reads as parameters.

/* SYS$FAOL example - illustrating !UB, !XB, and !SB directives */
#include <descrip.h>
#include <starlet.h>

int example()
{
    static int values[3] = {200, 300, -400};   /* Parameters for $FAOL */
    static $DESCRIPTOR(fao_desc,
                       "Values !UB (Decimal) !XB (Hex) !SB (Signed)");

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    values));   /* Parameter list - longwords */
}
      

$FAO writes the following output string:

Values 200 (Decimal) 2C (Hex) 112 (Signed)

The input parameters are the same as those for Example 4; however, the control string (fao_desc) specifies that byte values are to be converted. $FAO uses the low-order byte of each longword parameter passed to it. The high-order three bytes are not evaluated. Compare these results with the results of Example 4.

/*
** SYS$FAO example - illustrating !XW, !ZW, and !- directives,
** repeat count, and output field length
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(fao_desc,
                       "Hex: !2(6XW) Zero-filled Decimal: !2(-)!2(7ZW)");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   10000,       /* P1 - longword value */
                   9999));      /* P2 - longword value */
}
      

$FAO writes the following string to the output buffer:

Hex:___2710__270F Zero-filled Decimal: 00100000009999

Each of the directives !2(6XW) and !2(7ZW) contains repeat counts and output lengths. First, $FAO performs the !XW directive twice, using the low-order word of the numeric parameters passed. The output length specified is two characters longer than the default output field width of hexadecimal word conversion, so two spaces are placed between the resulting ASCII strings.

The !-- directive causes $FAO to back up over the parameter list. A repeat count is specified with the directive so that $FAO skips back over two parameters; then, it uses the same two parameters for the !ZW directive. The !ZW directive causes the output string to be zero-filled to the specified length (in this example, seven characters). Thus, there are no spaces between the output fields.

/*
** SYS$FAOL example - illustrating !AS, !UB, !%S, and !- directives,
** and variable repeat count
*/
#include <descrip.h>
#include <starlet.h>

/* Layout of argument list for examples */
typedef struct {void    *desc;          /* ASCII string descriptor */
                int     arg[4];         /* Longword arguments */
                } LIST;

$DESCRIPTOR(fao_desc, "!AS received !UB argument!%S: !-!#(4UB)");

int example_a()
{
    static $DESCRIPTOR(orion, "ORION");
    static LIST
        list_a = {&orion,       /* Address of descriptor */
                  3,            /* Number of arguments */
                  10,           /* Argument 1 */
                  123,          /* Argument 2 */
                  210};         /* Argument 3 */

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    &list_a));  /* Parameter list */
}

int example_b()
{
    static $DESCRIPTOR(lyra, "LYRA");
    static LIST
        list_b = {&lyra,        /* ASCII descriptor cast as an (int) */
                  1,            /* Number of arguments */
                  255};         /* Argument 1 */

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    &list_b));  /* Parameter list */
}
      

In example A, $FAO writes the following string to the output buffer:

ORION received 3 arguments:___10 123 210

In example B, $FAO writes the following string to the output buffer:

LYRA received 1 argument:__255

In each of the examples, the parameter list argument points to a different parameter list; each list contains, in the first longword, the address of a character string descriptor. The second longword begins an argument list, with the number of arguments remaining in the list. The control string uses this second longword twice: first to output the value contained in the longword, and then to provide the repeat count to output the number of arguments in the list (the !- directive indicates that $FAO should reuse the parameter).

The !%S directive provides a conditional plural. When the last value converted has a value not equal to 1, $FAO outputs the character s; if the value is a 1 (as in Example B), $FAO does not output the character s. $FAO outputs the plural character in lowercase since the preceding character was in lowercase.

The output field length defines a width of four characters for each byte value converted, to provide spacing between the output fields.

/*
** SYS$FAO example - illustrating !n*c (repeat character)
** and !%D (date/time) directives
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(fao_desc, "!5*> The time is now: !%D");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   0));         /* P1 - time value, 0 = current time */
}
      

$FAO writes the following string to the output buffer:

>>>>> The time is now: dd-mmm-yyyy hh:mm:ss.cc

where:

dd	is the day of the month
mmm	is the month
yyyy	is the year
hh:mm:ss.cc	is the time in hours, minutes, seconds, and hundredths of a second

The !5*> directive requests $FAO to write five greater-than (>) characters into the output string. Because there is a space after the directive, $FAO also writes a space after the greater-than characters on output.

The !%D directive requires the address of a quadword time value, which must be in the system time format; however, when the address of the time value is specified as 0, $FAO uses the current date and time. For a detailed description of the ASCII date and time string returned, see the discussion of the Convert Binary Time to ASCII String ($ASCTIM) system service.

/*
** SYS$FAO example - illustrating !%D and !%T (with output field lengths),
** and !n directive with variable repeat count
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(fao_desc, "Date: !11%D!#*_Time: !5%T");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   0,           /* P1 - time value, 0 = current time */
                   5,           /* P2 - Number of underscores */
                   0));         /* P3 - time value, 0 = current time */
}
      

$FAO writes the following string to the output buffer:

Date: dd-mmm-yyyy_____Time: hh:mm

An output length of 11 bytes is specified with the !%D directive so that $FAO truncates the time from the date and time string, and outputs only the date.

The !#*_ directive requests that the underscore character (_) be repeated the number of times specified by the next parameter. Because p2 is specified as 5, five underscores are written into the output string.

The !%T directive normally returns the full system time. The !5%T directive provides an output length for the time; only the hours and minutes fields of the time string are written into the output buffer.

/*
** SYS$FAO example - illustrating !< and !> (define field width),
** !AC, and !UL directives
*/
#include <descrip.h>
#include <starlet.h>

/* MACRO and typedef for counted ASCII strings... */
typedef struct {char len, str[25];} ASCIC;
#define ASCIC_STRING(name, string) ASCIC name = {sizeof(string) - 1, string}

$DESCRIPTOR(fao_desc, "!32<Variable: !AC Value: !UL!>Total:!7UL");

int example_a()
{
    int     val_a = 334,        /* Current value for variable */
            tot_a = 6554;       /* Current total for variable */

    static ASCIC_STRING(var_a, "Inventory");    /* Counted ASCII string */

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   &var_a,      /* P1 - Variable name */
                   val_a,       /* P2 - Value for variable */
                   tot_a));     /* P3 - Total for variable */
}

int example_b()
{
    int val_b = 280,            /* Current value for variable */
        tot_b = 10750;          /* Current total for variable */

    static ASCIC_STRING(var_b, "Sales");        /* Counted ASCII string */

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   &var_b,      /* P1 - Variable name */
                   val_b,       /* P2 - Value for variable */
                   tot_b));     /* P3 - Total for variable */
}
      

In example A, $FAO writes the following string to the output buffer:

Variable: Inventory Value: 334__Total:___6554

In example B, $FAO writes the following string to the output buffer:

Variable: Sales Value: 280______Total:__10750

The !25< directive requests an output field width of 25 characters; the end of the field is delimited by the !> directive. Within the field defined are two directives, !AC and !UL. The strings substituted by these directives can vary in length, but the entire field always has 25 characters.

The !7UL directive formats the longword passed in each example (p2 argument) and right-justifies the result in a 7-character output field.

 INTEGER STATUS,
 2       SYS$FAO,
 2       SYS$FAOL

 ! Resultant string
 CHARACTER*80 OUTSTRING
 INTEGER*2    LEN
 ! Array for directives in $FAOL
 INTEGER*4    PARAMS(2)

 ! File name and error number
 CHARACTER*80 FILE
 INTEGER*4    FILE_LEN,
 2            ERROR
 ! Descriptor for $FAOL
 INTEGER*4    DESCR(2)

 ! These variables would generally be set following an error
 FILE = '[BOELITZ]TESTING.DAT'
 FILE_LEN = 18
 ERROR = 25

 ! Call $FAO
 STATUS = SYS$FAO ('File !AS aborted at error !SL',
 2                 LEN,
 2                 OUTSTRING,
 2                 FILE(1:FILE_LEN),
 2                 %VAL(ERROR))
 IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))

 TYPE *,'From SYS$FAO:'
 TYPE *,OUTSTRING (1:LEN)

 ! Set up descriptor for filename
 DESCR(1) = FILE_LEN    ! Length
 DESCR(2) = %LOC(FILE)  ! Address
 ! Set up array for directives
 PARAMS(1) = %LOC(DESCR) ! File name
 PARAMS(2) = ERROR       ! Error number
 ! Call $FAOL
 STATUS = SYS$FAOL ('File !AS aborted at error !SL',
 2                  LEN,
 2                  OUTSTRING,
 2                  PARAMS)
 IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))

 TYPE *,'From SYS$FAOL:'
 TYPE *,OUTSTRING (1:LEN)

 END
      

This example shows a segment of a HP Fortran for OpenVMS program used to output the following string:

FILE [BOELITZ]TESTING.DAT ABORTED AT ERROR 25