 |
HP OpenVMS System Services Reference Manual
$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!
|
| #3 |
/* 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.
| #4 |
/* 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.
| #5 |
/* 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.
| #6 |
/*
** 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.
| #7 |
/*
** 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.
| #8 |
/*
** 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.
| #9 |
/*
** 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.
| #10 |
/*
** 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.
| #11 |
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
|
$FAOL_64 (Alpha and Integrity servers)
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.
$FILESCAN
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
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Longword flag mask in which $FILESCAN sets a bit for each file
specification component found in the input string. The
fldflags argument is the address of this longword flag
mask.
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
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Auxiliary output buffer. The auxout argument is the
address of a character-string descriptor pointing to the auxiliary
buffer.
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.
|
