OpenVMS RTL Library (LIB$) Manual

Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$LOOKUP_KEY

The Look Up Keyword in Table routine scans a table of keywords to find one that matches the keyword or keyword abbreviation specified by search-string.

Format

LIB$LOOKUP_KEY search-string ,key-table-array [,key-value] [,keyword-string] [,resultant-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

search-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

String for which LIB$LOOKUP_KEY will search in the keyword table. The search-string argument is the address of a descriptor pointing to this string.
key-table-array

OpenVMS usage: unspecified

type: unspecified

access: read only

mechanism: by reference, array reference

Keyword table. The key-table-array argument contains the address of an array that is this keyword table.
key-value

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by reference

Associated value of the keyword found by LIB$LOOKUP_KEY. The key-value argument contains the address of an unsigned longword into which LIB$LOOKUP_KEY writes the associated value of the matched keyword.
keyword-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Full keyword string matched. The keyword-string argument contains the address of a character-string descriptor. LIB$LOOKUP_KEY writes the complete text of the matched keyword into the character string.
resultant-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

Number of characters copied into the character-string pointed to by keyword-string, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word integer that contains the number of characters in the matched keyword that were copied into the character-string.

Description

LIB$LOOKUP_KEY is intended to help programmers to write utilities that have command qualifiers with values.
LIB$LOOKUP_KEY locates a matching keyword or keyword abbreviation by comparing the first n characters of each keyword in the keyword table with the supplied string, where n is the length of the supplied string.
When a keyword match is found, the following information is optionally returned to the caller:

The longword value associated with the matched keyword
The full keyword string (any descriptor type)

An exact match is found if the length of the keyword found is equal to the length of the supplied string.
If an exact keyword match is found, no further processing is performed, and a normal return status is returned to the caller. Otherwise, after a match has been found, the rest of the keyword table is scanned. If an additional match is found, a "not enough characters" return status is returned to the caller. If the keyword table contains a keyword that is an abbreviation of another keyword in the table, an exact match can occur for short abbreviations.
Figure lib-5 shows the structure of the keyword table, which the calling program creates for this routine.
Figure lib-5 Keyword Table

Vector-count is the number of longwords that follow, and counted-ASCII-string starts with a byte that is the unsigned count of the number of ASCII characters that follow.

Because of the format of the keyword table, this routine cannot be called easily from high-level languages. The examples that follow show how to use a macro, $LIB_KEY_TABLE, to construct a keyword table from MACRO or BLISS. A separate example shows how a table could be constructed in Fortran.

Use of the $LIB_KEY_TABLE macro results in data that is not position-independent code (PIC). If your application requires PIC data, you must fill in the address of the keyword strings at execution time. See the Fortran example (example 3) for a demonstration of this technique.

Condition Values Returned

SS$_NORMAL Routine successfully completed. A unique keyword match was found.

LIB$_AMBKEY Multiple keyword match found. Not enough characters were specified to allow a unique match.

LIB$_INSVIRMEM Insufficient virtual memory to return keyword string. This is only possible if keyword-string is a dynamic string.

LIB$_INVARG Invalid arguments, not enough arguments, and/or bad keyword table.

LIB$_STRTRU String truncated.

LIB$_UNRKEY The keyword you specified does not appear in the keyword table you specified.

Examples

#1
KEYTABLE: $LIB_KEY_TABLE < - <ADD, 1>, - <DELETE, 2>, - <EXIT, 3>>

This VAX MACRO fragment defines a keyword table named KEYTABLE containing the three keywords ADD, DELETE, and EXIT with associated keyword values of 1, 2, and 3, respectively.
The $LIB_KEY_TABLE macro is supplied in the default macro library SYS$LIBRARY:STARLET.MLB. Because this library is automatically searched by the assembler, you do not have to specify it in the DCL command MACRO.

#2
LIBRARY 'SYS$LIBRARY:STARLET.L32'; OWN KEYTABLE: $LIB_KEY_TABLE ( (ADD, 1), (DELETE, 2), (EXIT, 3));

This BLISS code fragment specifies that SYS$LIBRARY:STARLET.L32 is to be searched to resolve references. It defines a keyword table named KEYTABLE containing the three keywords ADD, DELETE, and EXIT with associated keyword values of 1, 2, and 3, respectively.
The $LIB_KEY_TABLE macro is supplied in the BLISS library SYS$LIBRARY:STARLET.L32 and in the BLISS require file SYS$LIBRARY:STARLET.REQ. BLISS does not automatically search either of these files, so you must explicitly cause them to be searched by including the appropriate LIBRARY or REQUIRE statement in your module. You should use the precompiled library because it is more efficient for the compiler.

#3
PARAMETER ( 1 MAXKEYSIZE = 6, ! Maximum keyword size 2 NKEYS = 3) ! Number of keywords BYTE KEYWORDS (MAXKEYSIZE+1, NKEYS) INTEGER4 KEYTABLE (0:NKEYS2) DATA KEYWORDS / 1 3,'A','D','D',' ',' ',' ', ! Counted ASCII 'ADD' 2 6,'D','E','L','E','T','E', ! Counted ASCII 'DELETE' 3 4,'E','X','I','T',' ',' '/ ! Counted ASCII 'EXIT' KEYTABLE(0) = NKEYS*2 ! Number of longwords to follow KEYTABLE(1) = %LOC(KEYWORDS(1,1)) ! Address of keyword string KEYTABLE(2) = 1 ! Keyword value for 'ADD' KEYTABLE(3) = %LOC(KEYWORDS(1,2)) ! Address of keyword string KEYTABLE(4) = 2 ! Keyword value for 'DELETE' KEYTABLE(5) = %LOC(KEYWORDS(1,3)) ! Address of keyword string KEYTABLE(6) = 3 ! Keyword value for 'EXIT'

 PARAMETER ( 
1     MAXKEYSIZE = 6,         ! Maximum keyword size 
2     NKEYS = 3)              ! Number of keywords 
 BYTE KEYWORDS (MAXKEYSIZE+1, NKEYS) 
 INTEGER*4 KEYTABLE (0:NKEYS*2) 
 DATA KEYWORDS / 
1     3,'A','D','D',' ',' ',' ',           ! Counted ASCII 'ADD' 
2     6,'D','E','L','E','T','E',           ! Counted ASCII 'DELETE' 
3     4,'E','X','I','T',' ',' '/           ! Counted ASCII 'EXIT' 
 
 KEYTABLE(0) = NKEYS*2                     ! Number of longwords to follow 
 KEYTABLE(1) = %LOC(KEYWORDS(1,1))         ! Address of keyword string 
 KEYTABLE(2) = 1                           ! Keyword value for 'ADD' 
 KEYTABLE(3) = %LOC(KEYWORDS(1,2))         ! Address of keyword string 
 KEYTABLE(4) = 2                           ! Keyword value for 'DELETE' 
 KEYTABLE(5) = %LOC(KEYWORDS(1,3))         ! Address of keyword string 
 KEYTABLE(6) = 3                           ! Keyword value for 'EXIT'

This Fortran code fragment constructs a keyword table named KEYTABLE containing the three keywords ADD, DELETE, and EXIT with associated keyword values of 1, 2, and 3, respectively. This construction method results in position-independent coded data, although the generated code for the typical Fortran module contains other non-PIC values.

LIB$LOOKUP_TREE

The Look Up an Entry in a Balanced Binary Tree routine looks up an entry in a balanced binary tree.

Note
No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$LOOKUP_TREE treehead ,symbol ,user-compare-routine ,new-node

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

treehead

OpenVMS usage: address

type: address

access: read only

mechanism: by reference

Tree head for the binary tree. The treehead argument is the address of an unsigned longword that is this tree head.
symbol

OpenVMS usage: user_arg

type: longword (unsigned)

access: unspecified

mechanism: unspecified

Key to be looked up in the binary tree.
user-compare-routine

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied compare routine that LIB$LOOKUP_TREE calls to compare a symbol with a node. The value returned by the compare routine indicates the relationship between the symbol key and the current node.
For more information on the compare routine, see Call Format for a Compare Routine in the Description section.
new-node

OpenVMS usage: address

type: longword (unsigned)

access: write only

mechanism: by reference

Location where the new symbol was found. The new-node argument is the address of an unsigned longword that is the new node location.

Description

Call Format for a Compare Routine
The call format of a compare routine is as follows:
user-compare-routine symbol ,comparison-node [,user-data]
LIB$LOOKUP_TREE passes both the symbol and comparison-node arguments to the compare routine, using the same passing mechanism that was used to pass them to LIB$LOOKUP_TREE. The user-data argument is passed in the same way, but its use is optional.
The user-compare-routine argument in the call to LIB$LOOKUP_TREE specifies the compare routine. This argument is required. LIB$LOOKUP_TREE calls the compare routine for every node except the first node in the tree.
The value returned by the compare routine is the result of comparing the symbol key with the current node. The table below lists the possible values returned by the compare routine:

Return Value Meaning

Negative The symbol argument is less than the current node.

Zero The symbol argument is equal to the current node.

Positive The symbol argument is greater than the current node.

For an example of a user-supplied compare routine written in C, see the description of LIB$INSERT_TREE.

Return Value	Meaning
Negative	The symbol argument is less than the current node.
Zero	The symbol argument is equal to the current node.
Positive	The symbol argument is greater than the current node.

Condition Values Returned

LIB$_NORMAL Routine successfully completed. The key was found.

LIB$_KEYNOTFOU Error. The key was not found.

Example

The C example provided in the description of LIB$INSERT_TREE also demonstrates how to use LIB$LOOKUP_TREE. Refer to that example for assistance in using this routine.

LIB$LOOKUP_TREE_64 (Alpha Only)

The Look Up an Entry in a Balanced Binary Tree routine looks up an entry in a balanced binary tree.

Format

LIB$LOOKUP_TREE_64 treehead ,symbol ,user-compare-routine ,new-node

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

treehead

OpenVMS usage: address

type: address

access: read only

mechanism: by reference

Tree head for the binary tree. The treehead argument is the address of an unsigned quadword that is this tree head.
symbol

OpenVMS usage: user_arg

type: quadword (unsigned)

access: unspecified

mechanism: unspecified

Key to be looked up in the binary tree.
user-compare-routine

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied compare routine that LIB$LOOKUP_TREE_64 calls to compare a symbol with a node. The value returned by the compare routine indicates the relationship between the symbol key and the current node.
For more information on the compare routine, see Call Format for a Compare Routine in the Description section.
new-node

OpenVMS usage: address

type: quadword (unsigned)

access: write only

mechanism: by reference

Location where the new symbol was found. The new-node argument is the address of an unsigned quadword that is the new node location.

Description

Call Format for a Compare Routine
The call format of a compare routine is as follows:
user-compare-routine symbol ,comparison-node [,user-data]
LIB$LOOKUP_TREE_64 passes both the symbol and comparison-node arguments to the compare routine, using the same passing mechanism that was used to pass them to LIB$LOOKUP_TREE_64. The user-data argument is passed in the same way, but its use is optional.
The user-compare-routine argument in the call to LIB$LOOKUP_TREE_64 specifies the compare routine. This argument is required. LIB$LOOKUP_TREE_64 calls the compare routine for every node except the first node in the tree.
The value returned by the compare routine is the result of comparing the symbol key with the current node. The following table lists the possible values returned by the compare routine:

Return Value Meaning

Negative The symbol argument is less than the current node.

Zero The symbol argument is equal to the current node.

Positive The symbol argument is greater than the current node.

For an example of a user-supplied compare routine written in C, see the description of LIB$INSERT_TREE_64.

Return Value	Meaning
Negative	The symbol argument is less than the current node.
Zero	The symbol argument is equal to the current node.
Positive	The symbol argument is greater than the current node.

Condition Values Returned

LIB$_NORMAL Routine successfully completed. The key was found.

LIB$_KEYNOTFOU Error. The key was not found.

Example

The C example provided in the description of LIB$INSERT_TREE also demonstrates how to use LIB$LOOKUP_TREE. Refer to that example for assistance in using this routine.

LIB$LP_LINES

The Lines on Each Printer Page routine computes the default number of lines on a printer page. This routine can be used by native-mode OpenVMS utilities that produce listing files and paginate files.

Format

LIB$LP_LINES

RETURNS

OpenVMS usage: longword_signed

type: longword integer (signed)

access: write only

mechanism: by value

The default number of lines on a physical printer page. If the logical name translation or conversion to binary fails, a default value of 66 is returned.

Arguments

None.

Description

LIB$LP_LINES computes the default number of lines on a printer page. This routine can be used by native-mode OpenVMS utilities that produce listing files and paginate files. The algorithm used by LIB$LP_LINES is:

Translate the logical name SYS$LP_LINES.
Convert the ASCII value obtained to a binary integer.
Verify that the resulting value is in the range [30:255].
If any of the prior steps fail, return the default paper size of 66 lines.

You can use LIB$LP_LINES to monitor the current default length of the line printer page. You can also supply your own default length for the current process. United States standard paper stock permits 66 lines on each physical page.
If you are writing programs for a utility that formats a listing file to be printed on a line printer, you can use LIB$LP_LINES to make your utility independent of the default page length. Your program can use LIB$LP_LINES to obtain the current length of the page. It can then calculate the number of lines of text on each page by subtracting the lines used for margins and headings.
The following is one suggested format:

Three lines for the top margin
Three lines for the bottom margin
Three lines for listing heading information, consisting of:

A language-processor identification line
A source-program identification line
One blank line

Condition Values Returned

None.

Examples

#1
lplines = LIB$LP_LINES() PRINT 10, lplines 10 Format (' Line printer page = ',I5,' lines.') end

This Fortran program displays the current default length of the line printer page.

#2
100 EXTERNAL INTEGER FUNCTION LIB$LP_LINES 200 DECLARE INTEGER LPLINES 300 LPLINES = LIB$LP_LINES 400 PRINT "Line printer page = "; LPLINES 32767 END

This BASIC program displays the current default length of the line printer page.

#3
PROGRAM LINES(OUTPUT); FUNCTION LIB$LP_LINES : INTEGER; EXTERN; BEGIN WRITELN('Line printer page = ',LIB$LP_LINES,' lines.'); END.

This Pascal program displays the current default length of the line printer page.

Contents

Index

Legal

 
5932PRO_029.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	unspecified
type:	unspecified
access:	read only
mechanism:	by reference, array reference

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed. A unique keyword match was found.
LIB$_AMBKEY	Multiple keyword match found. Not enough characters were specified to allow a unique match.
LIB$_INSVIRMEM	Insufficient virtual memory to return keyword string. This is only possible if keyword-string is a dynamic string.
LIB$_INVARG	Invalid arguments, not enough arguments, and/or bad keyword table.
LIB$_STRTRU	String truncated.
LIB$_UNRKEY	The keyword you specified does not appear in the keyword table you specified.

OpenVMS usage:	address
type:	address
access:	read only
mechanism:	by reference

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	unspecified
mechanism:	unspecified

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

LIB$_NORMAL	Routine successfully completed. The key was found.
LIB$_KEYNOTFOU	Error. The key was not found.

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	write only
mechanism:	by value