|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
LIB$SYS_FAOL character-string [,resultant-length] ,resultant-string ,directive-argument-address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
See the HP OpenVMS System Services Reference Manual: A--GETUAI for a complete description of $FAOL.
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.
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.
LIB$SYS_FAOL_64 character-string [,resultant-length] ,resultant-string ,directive-argument-address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
See the HP OpenVMS System Services Reference Manual: A--GETUAI for a complete description of $FAOL_64.
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.
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.
LIB$SYS_GETMSG message-id [,message-length] ,destination-string [,flags] [,unsigned-resultant-array]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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
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.
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.
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.
LIB$TPARSE/LIB$TABLE_PARSE argument-block ,state-table ,key-table
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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:
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:
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:
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:
| Previous | Next | Contents | Index |