hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


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:

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:
  1. 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.
  2. Coding and Using a Simple State Table --- Explains how to construct and use a simple state table.
  3. Using Advanced LIB$T[ABLE_]PARSE Features --- Explains how to use subexpressions, abbreviations, action routines, and other advanced features.
  4. 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. 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.
  2. 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.
  3. Performs one of the following operations:
  4. 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:

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:


Previous Next Contents Index