217 – LIB$TPARSE
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.
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
217.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
217.2 – 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.
LIB$T[ABLE_]PARSE supports the following argument blocks:
o 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.
o 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.
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.
218 – 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.
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
218.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
218.2 – 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.
LIB$T[ABLE_]PARSE supports the following argument blocks:
o 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.
o 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.
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.
219 – LIB$TRAVERSE_TREE
The Traverse a Balanced Binary Tree routine calls an action
routine for each node in a binary tree.
Format
LIB$TRAVERSE_TREE treehead ,user-action-procedure
[,user-data-address]
219.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
219.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: read only
mechanism: by reference
Tree head of the binary tree. The treehead argument is the
address of an unsigned longword that is the tree head in the
binary tree traversal.
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$TRAVERSE_TREE for each
node in the tree. The user-action-procedure argument must return
a success status for LIB$TRAVERSE_TREE to continue traversal.
user-data-address
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by reference
User data that LIB$TRAVERSE_TREE passes to your action routine.
The user-data-address argument contains the address of this user
data. This is an optional argument; the default value is 0.
220 – LIB$TRAVERSE_TREE_64
(Alpha and I64 only.) The Traverse a Balanced Binary Tree routine
calls an action routine for each node in a binary tree.
Format
LIB$TRAVERSE_TREE_64 treehead ,user-action-procedure
[,user-data-address]
220.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
220.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: read only
mechanism: by reference
Tree head of the binary tree. The treehead argument is the
address of an unsigned quadword that is the tree head in the
binary tree traversal.
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$TRAVERSE_TREE_64 for
each node in the tree. The user-action-procedure argument must
return a success status for LIB$TRAVERSE_TREE_64 to continue
traversal.
user-data-address
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by reference
User data that LIB$TRAVERSE_TREE_64 passes to your action
routine. The user-data-address argument contains the address of
this user data. This is an optional argument; the default value
is 0.
221 – LIB$TRA_ASC_EBC
The Translate ASCII to EBCDIC routine translates an ASCII string
to an EBCDIC string.
Format
LIB$TRA_ASC_EBC source-string ,byte-integer-dest-string
221.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
221.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string (ASCII) to be translated by LIB$TRA_ASC_EBC. The
source-string argument contains the address of a descriptor
pointing to this source string.
byte-integer-dest-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (EBCDIC). The byte-integer-dest-string
argument contains the address of a descriptor pointing to this
destination string.
222 – LIB$TRA_EBC_ASC
The Translate EBCDIC to ASCII routine translates an EBCDIC string
to an ASCII string.
Format
LIB$TRA_EBC_ASC byte-integer-source-string ,destination-string
222.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
222.2 – Arguments
byte-integer-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The
byte-integer-source-string argument contains the address of a
descriptor pointing to this source string.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (ASCII). The destination-string argument
contains the address of the descriptor of this destination
string.
The LIB$TRA_EBC_ASC routine uses the EBCDIC to ASCII translation
table, LIB$AB_EBC_ASC.
223 – LIB$TRIM_FILESPEC
The Fit Long File Specification into Fixed Field routine takes a
file specification, such as an OpenVMS RMS resultant name string,
and shortens it (if necessary) so that it fits into a field of
fixed width.
Format
LIB$TRIM_FILESPEC old-filespec ,new-filespec
[,word-integer-width] [,resultant-length]
223.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
223.2 – Arguments
old-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification to be trimmed. The old-filespec argument
contains the address of a descriptor pointing to this file
specification string.
The file specification should be an RMS resultant name string.
new-filespec
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Trimmed file specification. The new-filespec argument contains
the address of a descriptor pointing to this trimmed file
specification string. LIB$TRIM_FILESPEC writes the trimmed file
specification into new-filespec.
word-integer-width
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum field width desired. The word-integer-width argument is
the address of an unsigned word that contains this maximum field
width.
If omitted, the current length of new-filespec is used. If new-
filespec is not a fixed-length string, you should specify word-
integer-width to ensure that the desired width is used.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the trimmed file specification, not including any blank
padding or truncated characters. The resultant-length argument is
the address of an unsigned word that contains this length. This
is an optional argument.
224 – LIB$TRIM_FULLNAME
The Trim a Full Name to Fit into a Desired Output Field routine
trims a full name to fit into a desired output field. The
trimming preserves the most significant part of the full name.
Format
LIB$TRIM_FULLNAME fullname, trimmed-nodename [,output-width]
[,resultant-length]
224.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
224.2 – Arguments
fullname
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Full name to be trimmed. The fullname argument contains the
address of a descriptor pointing to this full name string.
The error LIB$_INVARG is returned if fullname contains an invalid
full name, points to a null string, or contains more than 1024
characters. The error LIB$_INVSTRDES is returned if fullname is
an invalid descriptor.
trimmed-nodename
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Trimmed node name. The trimmed-nodename argument contains the
address of a descriptor pointing to the trimmed node-name string.
LIB$TRIM_FULLNAME writes the trimmed node name into the buffer
pointed to by trimmed-nodename.
The error LIB$_INVSTRDES is returned if trimmed-nodename is an
invalid descriptor.
The length field of the trimmed-nodename descriptor is not
updated unless trimmed-nodename is a dynamic descriptor with a
length less than the resultant trimmed node name. Refer to the
OpenVMS RTL String Manipulation (STR$) Manual for dynamic string
descriptor usage.
The trimmed-nodename argument contains an unusable result when
LIB$TRIM_FULLNAME returns in error.
output-width
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Field width desired for the trimmed node name. The output-width
argument is the address of an unsigned word that contains this
field width in bytes.
If output-width is omitted, the current length of trimmed-
nodename is used. If trimmed-nodename is not a fixed-length
string, specify output-width to ensure that the desired width
is used.
If the lengths of both trimmed-nodename and output-width are
specified, the length in output-width is used. In this case, if
the current length of trimmed-nodename is smaller than the length
of output-width, the output trimmed node name is truncated at the
end, and the alternate successful status LIB$_STRTRU is returned.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the trimmed node name. The resultant-length argument
is the address of an unsigned word that contains this length in
bytes.
The resultant-length argument contains an unusable result when
LIB$TRIM_FULLNAME returns in error.
225 – LIB$UNLOCK IMAGE (Alpha and I64 Only)
Unlocks the specified image in the process's working set.
Format
LIB$UNLOCK_IMAGE address
225.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
225.2 – Arguments
address
OpenVMS usage:address
type: quadword
access: read only
mechanism: by value
Address of a byte within the image to be unlocked in the working
set. If the address argument is 0, the current image (which
contains the call to LIB$UNLOCK_IMAGE) is unlocked in the working
set.
226 – LIB$VERIFY_VM_ZONE
The Verify a Zone routine performs verification of a 32-bit zone.
Format
LIB$VERIFY_VM_ZONE zone-id
226.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
226.2 – Argument
zone-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier of the zone to be verified. The zone-id argument
is the address of an unsigned longword that contains this zone
identifier. A value of 0 indicates the 32-bit default zone.
227 – LIB$VERIFY_VM_ZONE_64
(Alpha and I64 only.) The Verify a Zone routine performs
verification of a 64-bit zone.
Format
LIB$VERIFY_VM_ZONE_64 zone-id
227.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
227.2 – Argument
zone-id
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Zone identifier of the zone to be verified. The zone-id argument
is the address of an unsigned quadword that contains this zone
identifier. A value of 0 indicates the 64-bit default zone.
228 – LIB$WAIT
The Wait a Specified Period of Time routine places the current
process into hibernation for the number of seconds specified in
its argument.
Format
LIB$WAIT seconds [,flags] [,float-type]
228.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
228.2 – Arguments
seconds
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by reference
The number of seconds to wait. The seconds argument contains the
address of an F-floating number that is this number.
The value is rounded to the nearest hundredth-second before use.
Seconds must be between 0.0 and 100,000.0.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Control flags. The flags argument is the address of a longword
integer that contains the control flags. The following flag is
defined:
Bit Value Description
0 LIB$K_NOWAKE LIB$WAIT will not wake in the case of an
interrupt.
This is an optional argument. If omitted, the default is 0, and
LIB$WAIT will wake in the case of an interrupt.
float-type
OpenVMS usage:longword-unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Float type. The float-type argument is the address of a longword
integer that determines the floating-point type of the seconds
argument. Use one of the following symbols:
Symbol Value Floating-Point Type
LIB$K_VAX_F 0 F_floating
LIB$K_VAX_D 1 D_floating
LIB$K_VAX_G 2 G_floating
LIB$K_VAX_H 3 H_floating
LIB$K_IEEE_S 4 IEEE_S_floating
LIB$K_IEEE_T 5 IEEE_T_floating
This is an optional argument. If omitted, the default is F_
floating. F_floating is the required float-type when LIB$WAIT
is called from a module written in a language that prototypes
functions.