HP OpenVMS Systems Documentation

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

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.

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.

 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.

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.

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.

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.

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.

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:

1. Translate the logical name SYS$LP_LINES.
2. Convert the ASCII value obtained to a binary integer.
3. Verify that the resulting value is in the range [30:255].
4. 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

        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.

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.

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.