 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$SYS_FAOL
The Invoke $FAOL System Service to Format Output routine calls the
$FAOL system service, returning the string in the semantics you
provide. If called with other than a fixed-length string for output,
the length of the resultant string is limited to 256 bytes and
truncation occurs.
Format
LIB$SYS_FAOL character-string [,resultant-length] ,resultant-string
,directive-argument-address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
character-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
ASCII control string, consisting of the fixed text of the output string
and FAO directives. The character-string argument
contains the address of a descriptor pointing to this control string.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the output string. The resultant-length
argument contains the address of an unsigned word integer that is this
length.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Fully formatted output string returned by LIB$SYS_FAOL. The
resultant-string argument contains the address of a
descriptor pointing to this output string.
directive-argument-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
unspecified |
Directive arguments. The directive-argument-address
arguments are contained in an array of unsigned longword directive
arguments. Depending on the directive, a
directive-argument-address argument can be a value to
be converted, the address of the string to be inserted, or a length or
argument count. The passing mechanism for each of these arguments
should be the one expected by the $FAOL system service.
Description
See the HP OpenVMS System Services Reference Manual: A--GETUAI for a complete description of $FAOL.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_BADPARAM
|
An invalid directive was specified in the FAO control string.
|
|
SS$_BUFFEROVF
|
Successfully completed, but the formatted output string overflowed the
output buffer and was truncated.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory to allocate dynamic string.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
|
LIB$_STRTRU
|
Success, but the source string was truncated on copy.
|
LIB$SYS_FAOL_64 (Alpha and I64 Only)
The Invoke $FAOL_64 System Service to Format Output routine calls the
$FAOL_64 system service, returning the string in the semantics you
provide. If called with other than a fixed-length string for output,
the length of the resultant string is limited to 256 bytes and
truncation occurs.
Format
LIB$SYS_FAOL_64 character-string [,resultant-length] ,resultant-string
,directive-argument-address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
character-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
ASCII control string, consisting of the fixed text of the output string
and FAO directives. The character-string argument
contains the address of a descriptor pointing to this control string.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the output string. The resultant-length
argument contains the address of an unsigned word integer that is this
length.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Fully formatted output string returned by LIB$SYS_FAOL_64. The
resultant-string argument contains the address of a
descriptor pointing to this output string.
directive-argument-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
unspecified |
Directive arguments. The directive-argument-address
arguments are contained in an array of unsigned quadword directive
arguments. Depending on the directive, a
directive-argument-address argument can be a value to
be converted, the address of the string to be inserted, or a length or
argument count. The passing mechanism for each of these arguments
should be the one expected by the $FAOL_64 system service.
Description
See the HP OpenVMS System Services Reference Manual: A--GETUAI for a complete description of $FAOL_64.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_BADPARAM
|
An invalid directive was specified in the FAO control string.
|
|
SS$_BUFFEROVF
|
Successfully completed, but the formatted output string overflowed the
output buffer and was truncated.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory to allocate dynamic string.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
|
LIB$_STRTRU
|
Success, but the source string was truncated on copy.
|
LIB$SYS_GETMSG
The Invoke $GETMSG System Service to Get Message Text routine calls the
system service $GETMSG and returns a message string into
destination-string using the semantics of the caller's
string.
Format
LIB$SYS_GETMSG message-id [,message-length] ,destination-string
[,flags] [,unsigned-resultant-array]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
message-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Message identification to be retrieved by LIB$SYS_GETMSG. The
message-id argument contains the address of an
unsigned longword integer that is this message identification.
message-length
| OpenVMS usage: |
word_unsigned |
| type: |
word integer (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters written into destination-string,
not counting padding in the case of a fixed-length string. The
message-length argument contains the address of an
unsigned word integer that is this number.
If the input string is truncated to the size specified in the
destination-string descriptor,
message-length is set to this size. Therefore,
message-length can always be used by the calling
program to access a valid substring of
destination-string.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string. The destination-string argument
contains the address of a descriptor pointing to this destination
string. LIB$SYS_GETMSG writes the message that has been returned by
$GETMSG into destination-string.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Four flag bits for message content. The flags argument
is the address of an unsigned longword that contains these flag bits.
The default value is a longword with bits 0 through 3 set to 1. The
flags argument is passed to LIB$SYS_GETMSG by
reference and changed to value for use by $GETMSG.
The following table lists the bit numbers, their values, and
corresponding descriptions:
| Bit |
Value |
Description |
|
0
|
1
|
Include text of message.
|
|
|
0
|
Do not include text of message.
|
|
1
|
1
|
Include message identifier.
|
|
|
0
|
Do not include message identifier.
|
|
2
|
1
|
Include severity indicator.
|
|
|
0
|
Do not include severity indicator.
|
|
3
|
1
|
Include facility name.
|
|
|
0
|
Do not include facility name.
|
unsigned-resultant-array
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
write only |
| mechanism: |
by reference, array reference |
A 4-byte array to receive message-specific information. The
unsigned-resultant-array argument contains the address
of this array.
The contents of this 4-byte array are as follows:
| Byte |
Contents |
|
0
|
Reserved
|
|
1
|
Count of FAO arguments
|
|
2
|
User value
|
|
3
|
Reserved
|
Description
LIB$SYS_GETMSG calls the $GETMSG system service and returns a message
string using the semantics of the caller's string. Note that, in order
to retrieve a message string for a LIB$ facility message, you must
include the file $LIBDEF in your program.
See the HP OpenVMS System Services Reference Manual: A--GETUAI for a more complete description of $GETMSG.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_BUFFEROVF
|
Successfully completed, but the resultant string overflowed the buffer
provided and was truncated.
|
|
SS$_MSGNOTFND
|
Successfully completed, but the message code does not have an
associated message on file.
|
|
LIB$_STRTRU
|
Successfully completed, but the source string was truncated on copy.
|
|
LIB$_FATERRLIB
|
Fatal internal error.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
LIB$TPARSE/LIB$TABLE_PARSE
The Table-Driven Finite-State Parser routine is a general-purpose,
table-driven parser implemented as a finite-state automaton, with
extensions that make it suitable for a wide range of applications. It
parses a string and returns a message indicating whether or not the
input string is valid.
Note
No support for arguments passed by 64-bit address reference or the use
of 64-bit descriptors is planned for LIB$TPARSE. On Alpha and I64
systems, LIB$TABLE_PARSE supports arguments passed by 64-bit address
reference and the use of 64-bit descriptors.)
|
LIB$T[ABLE_]PARSE is called with the address of an argument block, the
address of a state table, and the address of a keyword table. The input
string is specified as part of the argument block.
The LIB$ facility supports the following two versions of the
Table-Driven Finite-State Parser:
|
LIB$TPARSE
|
Available on VAX systems.
|
|
|
LIB$TPARSE is available on Alpha and I64 systems in translated form. In
this form, it is applicable to translated VAX images only.
|
|
LIB$TABLE_PARSE
|
Available on VAX, Alpha, and I64 systems.
|
LIB$TPARSE and LIB$TABLE_PARSE differ mainly in the way they pass
arguments to action routines.
The term LIB$T[ABLE_]PARSE is used here to describe concepts that apply
to both LIB$TPARSE and LIB$TABLE_PARSE.
Format
LIB$TPARSE/LIB$TABLE_PARSE argument-block ,state-table ,key-table
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
argument-block
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
modify |
| mechanism: |
by reference |
LIB$T[ABLE_]PARSE argument block. The argument-block
argument contains the address of this argument block.
The LIB$T[ABLE_]PARSE argument block contains information about the
state of the parse operation. It is a means of communication between
LIB$T[ABLE_]PARSE and the user's program. It is passed as an argument
to all action routines.
You must declare and initialize the argument block. Section
1.4 describes the argument block in detail. Section
2.2 illustrates the coding for an argument block declaration
and discusses its initialization.
LIB$T[ABLE_]PARSE supports the following argument blocks:
- A 32-bit argument block that accommodates longword addresses,
values, and input tokens on VAX, Alpha, and I64 systems.
On Alpha
and I64 systems, this argument block also accommodates a numeric token
whose binary representation is less than or equal to 2**64.
- A 64-bit argument block that accommodates quadword addresses,
values, and input tokens on Alpha and I64 systems.
state-table
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
Starting state in the state table. The state-table
argument is the address of this starting state. Usually, the name
appearing as the first argument of the $INIT_STATE macro is used.
You must define the state table for your parser. LIB$T[ABLE_]PARSE
provides macros in the MACRO and BLISS languages for this purpose.
Section 1.3 describes these macros.
key-table
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
Keyword table. The key-table argument is the address
of this keyword table. This name must be the same as that which appears
as the second argument of the $INIT_STATE macro.
You must only assign a name to the keyword table. The LIB$T[ABLE_]PARSE
macros allocate and define the table. See Section 4 for
more information about the keyword table.
Description
The following sections explain in detail how LIB$T[ABLE_]PARSE works
and how to call it from both the MACRO assembly language and high-level
languages:
- How LIB$T[ABLE_]PARSE Works --- Describes the data structures used
by LIB$T[ABLE_]PARSE and how LIB$T[ABLE_]PARSE operates on them.
- Coding and Using a Simple State Table --- Explains how to
construct and use a simple state table.
- Using Advanced LIB$T[ABLE_]PARSE Features --- Explains how to use
subexpressions, abbreviations, action routines, and other advanced
features.
- Data Representation --- Includes information for the
low-level-language programmer, such as the binary representation of
state table data.
1 How LIB$T[ABLE_]PARSE Works
LIB$T[ABLE_]PARSE analyzes an input string according to a set of states
and transitions presented in a state table you define. It determines
whether the input string is valid according to the rules you define for
the input language.
There are three parts to any parsing operation:
- The set of symbol types, or alphabet, from which
you can choose the vocabulary of your language.
You specify a
symbol type for each transition you define. The symbol type specifies
what constitutes a matching substring from the input string.
LIB$T[ABLE_]PARSE recognizes the ASCII character set and provides
symbolic names for the most common combinations of ASCII characters,
such as alphabetic and alphanumeric strings, OpenVMS symbols, and
numbers. See Section 1.2 for a list of the symbol types that
comprise the LIB$T[ABLE_]PARSE alphabet.
- The rules that govern how the alphabet is used---in other words,
the language's grammar.
You specify the rules for a language in a
state table. A LIB$T[ABLE_]PARSE state table lists the possible states
for your language. Each state consists of a list of the transitions to
other states and the operations to be performed when a transition is
executed (see Section 1.3 ).
- The string to be parsed.
The argument block specifies the input
string. It also contains additional information about the state of the
parse---how much of the string has not been interpreted, what the
current token is, and so forth (see Section 1.4 ).
1.1 Overview
Before discussing the alphabet, the state table, and the argument block
in detail, this section provides an overview of how these three parts
work together.
1.1.1 Evaluating the Input String
LIB$T[ABLE_]PARSE evaluates the input string from left to right as it
transitions from state to state. For a particular transition in a
particular state, it evaluates the beginning of the unprocessed part of
the input string against the symbol type you specify for the transition
to determine whether there is a match.
LIB$T[ABLE_]PARSE compares each character of the remaining input
string, from left to right, against the transition's symbol type until
it encounters a character in the input string that does not match. It
takes the substring that matches the symbol type and stores a pointer
to it in the argument block as the current token. In
this way, any character in the input string that does not belong to the
symbol type's constituent character set effectively becomes a separator.
If LIB$T[ABLE_]PARSE finds a match, it executes the transition.
If the input string does not match, LIB$T[ABLE_]PARSE attempts to match
the next transition. It performs the comparison using the transitions
in the order in which you define them for the state.
1.1.2 Executing a Transition
When LIB$T[ABLE_]PARSE finds a match with a transition, it performs the
following steps:
- Stores a pointer to the current token in the argument block. If the
token matches one of the numeric symbol types, it also stores the
token's binary representation in the argument block.
- Calls the action routine, if any, specified by the transition and
passes it the argument block and any additional user-specified
arguments.
You can use an action routine to reject a transition. In
this case, LIB$T[ABLE_]PARSE performs none of the following steps. See
Section 3.1 for more information.
- Performs one of the following operations:
- Stores the mask, if any, specified by the transition in the
location specified by the transition.
- Stores the value of token in the program location specified by the
transition.
- Transfers control to the specified state, if any, or to the next
state in the state table.
1.1.3 Exiting LIB$T[ABLE_]PARSE
LIB$T[ABLE_]PARSE continues to match and execute transitions from state
to state until one of the following occurs:
- For a valid match, it executes a user-specified transition to
TPA$_EXIT at main level. It returns the value SS$_NORMAL.
- A transition requests that LIB$T[ABLE_]PARSE consider the string
invalid by specifying a transition to TPA$_FAIL at main level (rather
than at the level of a subexpression). LIB$T[ABLE_]PARSE returns with
the value LIB$_SYNTAXERR.
You can also request a transition to
TPA$_FAIL from an action routine. The action routine can provide an
alternate failure status.
- An error occurs at the main level. The error can be:
- A syntax error. All transitions in the current state fail to match
the remaining input string. LIB$T[ABLE_]PARSE returns LIB$_SYNTAXERR or
an alternate failure status returned by an action routine.
- A state table format error. One of your state table entries is
invalid. LIB$T[ABLE_]PARSE returns LIB$_INVTYPE.
Note
LIB$T[ABLE_]PARSE generates no signals and establishes no condition
handler; action routines can signal through LIB$T[ABLE_]PARSE back to
the calling program.
|
When LIB$T[ABLE_]PARSE cannot successfully parse the entire string, it
defines the current token, as follows, and stores it in the argument
block before returning:
- If LIB$T[ABLE_]PARSE fails to match a transition in the current
state, it attempts to define the current token as the beginning of the
remaining input string. You can incorporate this token in an error
message or use it to determine the logical flow of your program.
LIB$T[ABLE_]PARSE attempts to match the characters from the
beginning of the remaining input string, one at a time, against the
TPA$_SYMBOL alphabet symbol type until it encounters a character that
does not match. The TPA$_SYMBOL symbol type consists of all the
characters of the standard OpenVMS symbol constituent set.
- If LIB$T[ABLE_]PARSE successfully matches one or more consecutive
characters from the input string against TPA$_SYMBOL, then the
substring that matched TPA$_SYMBOL becomes the current token.
- If the first character of the remaining input string does not match
TPA$_SYMBOL, the first character becomes the current token.
- If LIB$T[ABLE_]PARSE matches the symbol type for a transition that
specifies TPA$_FAIL as the next state, it leaves the token that matched
the transition as the current token.
|
