OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

Table SYS-9 lists $FAO directives.

Table SYS-9 $FAO Directives
Directive Description

Directives for Character String Substitution

!AC Inserts a counted ASCII string. It requires one parameter: the address of the string to be inserted. The first byte of the string must contain the length (in characters) of the string.

!AD Inserts an ASCII string. It requires two parameters: the length of the string and the address of the string. Each of these parameters is a separate argument.

!AF Inserts an ASCII string and replaces all nonprintable ASCII codes with periods (.). It requires two parameters: the length of the string and the address of the string. Each of these parameters is a separate argument.

!AS Inserts an ASCID string. It requires one parameter: the address of a character string descriptor pointing to the string. $FAO assumes that the descriptor is a CLASS_S (static) or CLASS_D (dynamic) string descriptor. Other descriptor types might give incorrect results.

!AZ Inserts a zero-terminated (ASCIZ) string. It requires one parameter: the address of a zero-terminated string.

Directives for Zero-Filled Numeric Conversion

!OB Converts a byte value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.

!OW Converts a word value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.

!OL Converts a longword value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted.

!OQ Converts on Alpha systems a quadword to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.

!OA Converts an address to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!OI Converts an integer to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!OH Converts an address to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!OJ Converts an integer to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!XB Converts a byte value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.

!XW Converts a word value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.

!XL Converts a longword value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted.

!XQ Converts on Alpha systems a quadword to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. This directive cannot be used from DCL.

!XA Converts an address to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!XI Converts an integer to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!XH Converts an address to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!XJ Converts an integer to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!ZB Converts an unsigned byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.

!ZW Converts an unsigned word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.

!ZL Converts an unsigned longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.

!ZQ Converts on Alpha systems an unsigned quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.

!ZA Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!ZI Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!ZH Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!ZJ Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

Directives for Blank-Filled Numeric Conversion

!UB Converts an unsigned byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.

!UW Converts an unsigned word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.

!UL Converts an unsigned longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.

!UQ Converts on Alpha systems an unsigned quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.

!UA Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!UI Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!UH Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!UJ Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!SB Converts a signed byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.

!SW Converts a signed word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.

!SL Converts a signed longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.

!SQ Converts on Alpha systems a signed quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.

!SA Converts a signed address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!SI Converts a signed integer to the ASCII representation of its equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹

!SH Converts a signed address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

!SJ Converts a signed integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²

Directives for Output String Formatting

!/ Inserts a new line, that is, a carriage return and line feed. It takes no parameters.

!_ Inserts a tab. It takes no parameters.

!^ Inserts a form feed. It takes no parameters.

!! Inserts an exclamation point. It takes no parameters.

!%S Inserts the letter S if the most recently converted numeric value is not 1. An uppercase S is inserted if the character before the !%S directive is an uppercase character; a lowercase s is inserted if the character is lowercase.

!%T Inserts the system time. It takes one parameter: the address of a quadword time value to be converted to ASCII. If you specify 0, the current system time is inserted.

!%U Converts a longword integer UIC to a standard UIC specification in the format [xxx,yyy], where xxx is the group number and yyy is the member number. It takes one parameter: a longword integer. The directive inserts the surrounding brackets ([ ]) and comma (,).

!%I Converts a longword to the appropriate alphanumeric identifier. If the longword represents a UIC, surrounding brackets ([ ]) and comma (,) are added as necessary. If no identifier exists and the longword represents a UIC, the longword is formatted as in !%U. Otherwise it is formatted as in !XL with a preceding !%X added to the formatted result.

!%D Inserts the system date and time. It takes one parameter: the address of a quadword time value to be converted to ASCII. If you specify 0, the current system date and time is inserted.

!n%C Inserts a character string when the most recently evaluated argument has the value n. (Recommended for use with multilingual products.)

!%E 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 Makes the end of a plurals statement.

!n< See description of next directive (!>).

!> This directive and the preceding one (!n<) are used together to define an output field width of n characters within which all data and directives to the right of !n< and to the left of !> are left-justified and blank-filled. It takes no parameters.

!n*c Repeats the character c in the output string n times.

Directives for Parameter Interpretation

!-- Causes $FAO to reuse the most recently used parameter in the list. It takes no parameters.

!+ Causes $FAO to skip the next parameter in the list. It takes no parameters.

**Table SYS-9 $FAO Directives**
Directive	Description
Directives for Character String Substitution
!AC	Inserts a counted ASCII string. It requires one parameter: the address of the string to be inserted. The first byte of the string must contain the length (in characters) of the string.
!AD	Inserts an ASCII string. It requires two parameters: the length of the string and the address of the string. Each of these parameters is a separate argument.
!AF	Inserts an ASCII string and replaces all nonprintable ASCII codes with periods (.). It requires two parameters: the length of the string and the address of the string. Each of these parameters is a separate argument.
!AS	Inserts an ASCID string. It requires one parameter: the address of a character string descriptor pointing to the string. $FAO assumes that the descriptor is a CLASS_S (static) or CLASS_D (dynamic) string descriptor. Other descriptor types might give incorrect results.
!AZ	Inserts a zero-terminated (ASCIZ) string. It requires one parameter: the address of a zero-terminated string.
Directives for Zero-Filled Numeric Conversion
!OB	Converts a byte value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!OW	Converts a word value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!OL	Converts a longword value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted.
!OQ	Converts on Alpha systems a quadword to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.
!OA	Converts an address to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!OI	Converts an integer to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!OH	Converts an address to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!OJ	Converts an integer to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!XB	Converts a byte value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!XW	Converts a word value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!XL	Converts a longword value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted.
!XQ	Converts on Alpha systems a quadword to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. This directive cannot be used from DCL.
!XA	Converts an address to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!XI	Converts an integer to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!XH	Converts an address to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!XJ	Converts an integer to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!ZB	Converts an unsigned byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!ZW	Converts an unsigned word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!ZL	Converts an unsigned longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.
!ZQ	Converts on Alpha systems an unsigned quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.
!ZA	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!ZI	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!ZH	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!ZJ	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
Directives for Blank-Filled Numeric Conversion
!UB	Converts an unsigned byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!UW	Converts an unsigned word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!UL	Converts an unsigned longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.
!UQ	Converts on Alpha systems an unsigned quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.
!UA	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!UI	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!UH	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!UJ	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!SB	Converts a signed byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!SW	Converts a signed word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!SL	Converts a signed longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.
!SQ	Converts on Alpha systems a signed quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.
!SA	Converts a signed address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!SI	Converts a signed integer to the ASCII representation of its equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ¹
!SH	Converts a signed address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
!SJ	Converts a signed integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. ²
Directives for Output String Formatting
!/	Inserts a new line, that is, a carriage return and line feed. It takes no parameters.
!_	Inserts a tab. It takes no parameters.
!^	Inserts a form feed. It takes no parameters.
!!	Inserts an exclamation point. It takes no parameters.
!%S	Inserts the letter S if the most recently converted numeric value is not 1. An uppercase S is inserted if the character before the !%S directive is an uppercase character; a lowercase s is inserted if the character is lowercase.
!%T	Inserts the system time. It takes one parameter: the address of a quadword time value to be converted to ASCII. If you specify 0, the current system time is inserted.
!%U	Converts a longword integer UIC to a standard UIC specification in the format [xxx,yyy], where xxx is the group number and yyy is the member number. It takes one parameter: a longword integer. The directive inserts the surrounding brackets ([ ]) and comma (,).
!%I	Converts a longword to the appropriate alphanumeric identifier. If the longword represents a UIC, surrounding brackets ([ ]) and comma (,) are added as necessary. If no identifier exists and the longword represents a UIC, the longword is formatted as in !%U. Otherwise it is formatted as in !XL with a preceding !%X added to the formatted result.
!%D	Inserts the system date and time. It takes one parameter: the address of a quadword time value to be converted to ASCII. If you specify 0, the current system date and time is inserted.
!n%C	Inserts a character string when the most recently evaluated argument has the value n. (Recommended for use with multilingual products.)
!%E	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	Makes the end of a plurals statement.
!n<	See description of next directive (!>).
!>	This directive and the preceding one (!n<) are used together to define an output field width of n characters within which all data and directives to the right of !n< and to the left of !> are left-justified and blank-filled. It takes no parameters.
!n*c	Repeats the character c in the output string n times.
Directives for Parameter Interpretation
!--	Causes $FAO to reuse the most recently used parameter in the list. It takes no parameters.
!+	Causes $FAO to skip the next parameter in the list. It takes no parameters.

¹Determined by the operating system. On VAX and Alpha systems, this is 32 bits.
²Determined by the hardware architecture. On VAX systems, this is 32 bits; on Alpha systems, this is 64 bits.

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

Table SYS-10 $FAO Output Field Lengths and Fill Characters
Conversion/Substitution Type Default Length of Output Field Action When Explicit Output Field Length Is Longer Than Default Action When Explicit Output Field Length Is Shorter Than Default

Hexadecimal

Byte
Word
Longword
Quadword 2 (zero-filled)
4 (zero-filled)
8 (zero-filled)
16 (zero-filled) ASCII result is right-justified and blank-filled to the specified length. ASCII result is truncated on the left.

Octal

Byte
Word
Longword
Quadword 3 (zero-filled)
6 (zero-filled)
11 (zero-filled)
22 (zero-filled) Hexadecimal or octal output is always zero-filled to the default output field length, then blank-filled to specified length.

Signed or unsigned decimal

Signed or unsigned decimal As many characters as necessary ASCII result is right-justified and blank-filled to the specified length. Signed and unsigned decimal output fields and completely filled with asterisks (*).

Unsigned zero-filled decimal

Unsigned zero-filled decimal As many characters as necessary ASCII result is right-justified and zero-filled to the specified length.

ASCII string substitution

ASCII string substitution Length of input character string ASCII string is left-justified and blank-filled to the specified length. ASCII string is truncated on the right.

**Table SYS-10 $FAO Output Field Lengths and Fill Characters**
Conversion/Substitution Type	Default Length of Output Field	Action When Explicit Output Field Length Is Longer Than Default	Action When Explicit Output Field Length Is Shorter Than Default
Hexadecimal
Byte Word Longword Quadword	2 (zero-filled) 4 (zero-filled) 8 (zero-filled) 16 (zero-filled)	ASCII result is right-justified and blank-filled to the specified length.	ASCII result is truncated on the left.
Octal
Byte Word Longword Quadword	3 (zero-filled) 6 (zero-filled) 11 (zero-filled) 22 (zero-filled)	Hexadecimal or octal output is always zero-filled to the default output field length, then blank-filled to specified length.
Signed or unsigned decimal
Signed or unsigned decimal	As many characters as necessary	ASCII result is right-justified and blank-filled to the specified length.	Signed and unsigned decimal output fields and completely filled with asterisks (*).
Unsigned zero-filled decimal
Unsigned zero-filled decimal	As many characters as necessary	ASCII result is right-justified and zero-filled to the specified length.
ASCII string substitution
ASCII string substitution	Length of input character string	ASCII string is left-justified and blank-filled to the specified length.	ASCII string is truncated on the right.

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 DEC Fortran for OpenVMS program used to output an ASCII string.

#1
/* 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 */ }

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

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

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

Previous Next Contents Index

privacy and legal statement

4527PRO_036.HTML

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.