$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).

#2

/* ** 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

On Alpha and Integrity server systems, 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.

$FAOL_64 interprets the parameter list as a list of quadwords rather than a list of longwords. In all other respects, $FAOL_64 is identical to $FAOL. For all other information about the $FAOL_64 service, refer to the description of $FAO/$FAOL in this manual.

This service accepts 64-bit addresses.

Format

SYS$FAOL_64 ctrstr_64 [,outlen_64 [,outbuf_64 [,quad_prmlst_64]]]

C Prototype

int sys$faol_64 (void *ctrstr_64, unsigned short int *outlen_64, void *outbuf_64, void *quad_prmlst_64);

Arguments

ctrstr_64

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

The 32- or 64-bit address of the control string (64-bit or 32-bit string descriptor).

outlen_64

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit address of the quadword that contains the output length, in bytes, of the fully formatted output string.

outbuf_64

OpenVMS usage:	char_string
type:	character-coded text string
access:	write only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

The 32- or 64-bit address of a character string descriptor that points to the output buffer into which $FAOL_64 writes the fully formatted output string.

quad_prmlst_64

OpenVMS usage:	vector_quadword_unsigned
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit address of a quadword-aligned array of quadword FAO arguments.

Searches a string for a file specification and parses the components of that file specification.

Format

SYS$FILESCAN srcstr ,valuelst ,[fldflags] ,[auxout] ,[retlen]

C Prototype

int sys$filescan (void *srcstr, void *valuelst, unsigned int *fldflags, void *auxout, unsigned short int *retlen);

Arguments

srcstr

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

String to be searched for the file specification. The srcstr argument is the address of a descriptor pointing to this string.

valuelst

OpenVMS usage:	item_list_2
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Item list specifying which components of the file specification are to be returned by $FILESCAN. The components are the full node specification, primary node name, primary node's access control, secondary node information, device, directory, file name, file type, and version number. The itmlst argument is the address of a list of item descriptors wherein each item descriptor specifies one component. The list of item descriptors is terminated by a longword of 0.

The following diagram depicts a single item descriptor:

The following table defines the item descriptor fields:

Descriptor Field	Definition
Component length	A word in which $FILESCAN writes the length (in characters) of the requested component. If $FILESCAN does not locate the component, it returns the value 0 in this field and in the component address field and returns the SS$_NORMAL condition value.
Item code	A user-supplied, word-length symbolic code that specifies the component desired. The $FSCNDEF macro defines the item codes.
Component address	A longword in which $FILESCAN writes the starting address of the component. This address points to a location in the input string itself. If $FILESCAN does not locate the component, it returns the value 0 in this field (see item code FSCN$_NAME for exception) and 0 in the component length field, and returns the SS$_NORMAL condition value.

fldflags

The $FSCNDEF macro defines a symbolic name for each significant flag bit. The following table shows the file specification component that corresponds to the symbolic name of each flag bit:

Symbolic Name	Corresponding Component
FSCN$V_DEVICE	Device name
FSCN$V_DIRECTORY	Directory name
FSCN$V_NAME	File name
FSCN$V_NODE	Node name
FSCN$V_NODE_ACS	Access control string of primary node
FSCN$V_NODE_PRIMARY	Primary (first) node name
FSCN$V_NODE_SECONDARY	Secondary (additional) node information
FSCN$V_ROOT	Root directory name string
FSCN$V_TYPE	File type
FSCN$V_VERSION	Version number

The fldflags argument is optional. When you want to know which components of a file specification are present in a string but do not need to know the contents or length of these components, specify fldflags instead of valuelst.

auxout

When you specify an auxiliary output buffer, $FILESCAN copies the entire source string, with quotation information reduced and simplified for only the primary node, into the auxiliary output buffer.