HP OpenVMS Systems Documentation

To ensure that addresses and integers are displayed properly on the system, use the following conventions when using the $FAO and $FAOL system services:

• Identify longword data as !xL (where x is O, X, Z, U, or S).
• On Alpha and Integrity server systems, identify quadword data as !xQ for $FAO and $FAOL_64 or !@xQ for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.
• If the size of an address is determined by operating system software ( 64-bits on Alpha and Integrity server systems), identify the address as !xA for $FAO and $FAOL_64 or !@xA for $FAOL (where x is O, X, Z, U, or S).
• If the size of an address is determined by the hardware architecture ( 64 bits on Alpha and Integrity servers, identify the address as !xH for $FAO and $FAOL_64 or !@xH for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.
• If the size of an integer is determined by operating system software (32 bits on Alpha and Integrity server systems), identify the integer as !xI for $FAO and $FAOL_64 or !@xI for $FAOL (where x is O, X, Z, U, or S).
• If the size of an integer is determined by the hardware architecture ( 64 bits on Alpha and Integrity servers, identify the address as !xJ for $FAO and $FAOL_64 or !@xJ for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.

Table SYS-35 lists $FAO directives.

Table SYS-36 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 */ 
} 
 
      

---

Previous

Next

Contents

Index