Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | 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)
     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.

### 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.

### 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:
> 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

#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.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_030.HTML