HP OpenVMS Systems Documentation

HP OpenVMS System Services Reference Manual

$EXTEND

The Extend service increases the amount of space allocated to a disk file. This service is most useful for extending relative files and indexed files when you are doing block I/O transfers using the Write service.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

$FAO/$FAOL

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.
The formats for both services are shown in the Format section.
On Alpha and I64 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 and I64)

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 and I64 systems) or the 32-bit address (on VAX systems) of a character string descriptor pointing to the control string. The formatting of the $FAO directives is described in the Description section.
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.
Table SYS-36 lists and describes the $FAO directives. Table SYS-37 shows the $FAO output field lengths and their fill characters.
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 and I64)

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 and I64 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 and I64)

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 and I64 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 and I64)

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 and I64 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.

Description

The Formatted ASCII Output ($FAO) service converts a binary value into an ASCII character string in decimal, hexadecimal, or octal notation and 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 way to specify input parameters for a call to the $FAO system service. The formats for both $FAO and $FAOL are shown in the Format section.
The $FAO_S macro form uses a PUSHL instruction for all parameters (p1 through p17) passed to the service; if you specify a symbolic address, it must be preceded with a number sign (#) or loaded into a register.
You can specify a maximum of 17 parameters on the $FAO macro. If more than 17 parameters are required, use the $FAOL macro.
This service does not check the length of the argument list and therefore cannot return the SS$_INSFARG (insufficient arguments) error status code. If the service does not receive a sufficient number of arguments (for example, if you omit required commas in the call), you might not get the desired result.
$FAO Directives

$FAO directives can appear anywhere in the control string. The general format of an $FAO directive is as follows:

!DD

The exclamation point (!) specifies that the following characters are to be interpreted as an $FAO directive, and the characters DD represent a 1- or 2-character $FAO directive.

Note
When the characters of the $FAO directive are alphabetic, they must be uppercase.

An $FAO directive can optionally specify the following:

A repeat count. The format is as follows:

!n(DD)

In this case n is a decimal value specifying the number of times that $FAO is to repeat the directive. If the directive requires a parameter or parameters, $FAO uses successive parameters from the parameter list for each repetition of the directive; it does not use the same parameters for each repetition. The parentheses are required syntax.
An output field length. The format is as follows:

!mDD

In this case m is a decimal value specifying the length of the field (within the output string) into which $FAO is to write the output resulting from the directive. The length is expressed as a number of characters.
Both a repeat count and output field length. In this case the format is as follows:

!n(mDD)

You can specify repeat counts and output field lengths as variables by using a number sign (#) in place of an absolute numeric value:

If you specify a number sign for a repeat count, the next parameter passed to $FAO must contain the count.
If you specify a number sign for an output field length, the next parameter must contain the length value.
If you specify a number sign for both the output field length and for the repeat count, only one length parameter is required; each output string will have the specified length.
If you specify a number sign for the repeat count, the output field length, or both, the parameters specifying the count, length, or both must precede other parameters required by the directive.

Numeric FAO output directives (B, W, L, Q, I, A, H, J) can include the indirect directive @. This immediately precedes the directive (@DD), and indicates that the next parameter is the address of the value instead of the value itself. This directive must be used with any directive that can produce a quadword output when using $FAOL; otherwise, $FAOL creates a 64-bit sign-extended value. This includes the Q, A, I, H, and J directives.

The indirect directive can be used with repeat counts and output field lengths. In this case the format is as follows:

!n(m@DD)

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 I64 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 (32 bits on VAX and 64-bits on Alpha and I64 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 (32 bits on VAX, but 64 bits on Alpha and I64, 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 both VAX and Alpha and I64 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 (32 bits on VAX, but 64 bits on Alpha and I64), 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-36 lists $FAO directives.

Table SYS-36 $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 and I64 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 and I64 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. It receives one parameter: the value to be converted. 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 and I64 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 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 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 and I64 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 and I64 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 or I64 systems, this is 32 bits.
²Determined by the hardware architecture. On VAX systems, this is 32 bits; on Alpha and I64 systems, this is 64 bits.

Contents

Index