VMS Help LBR Routines, LBR$GET_INDEX  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The LBR$GET_INDEX routine calls a user-supplied routine for
    selected keys in an index.

    Format

      LBR$GET_INDEX  library_index ,index_number ,routine_name

                     [,match_desc]

1 - Returns

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

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2 - Arguments

 library_index

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Library control index returned by the LBR$INI_CONTROL routine.
    The library_index argument is the address of the longword that
    contains the index.

 index_number

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Number of the library index. The index_number argument is the
    address of a longword containing the index number. This is the
    index number associated with the keys you want to use as input to
    the user-supplied routine .

 routine_name

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    User-supplied routine called for each of the specified index
    keys. The routine_name argument is the address of the procedure
    value for this user-supplied routine.

    LBR$GET_INDEX passes two arguments to the routine:

    o  A key name.

       -  For libraries with ASCII keys, the key_name argument is the
          address of a string descriptor pointing to the key. Note
          that the string and the string descriptor passed to the
          routine are valid only for the duration of that call. The
          string must be copied privately if you need it again for
          more processing.

       -  For libraries with binary keys, the key_name argument is
          the address of an unsigned longword containing the key
          number.

    o  The record's file address (RFA) of the module's header for
       this key name. The RFA argument is the address of a 2-longword
       array that contains the RFA.

    The routine must return a value to indicate success or failure.
    If the routine returns a false value (low bit = 0), LBR$GET_INDEX
    stops searching the index and returns the status value of the
    user-specified routine to the calling program.

    The routine cannot contain calls to either LBR$DELETE_KEY or
    LBR$INSERT_KEY.

 match_desc

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Key matching identifier. The match_desc argument is the address
    of a string descriptor pointing to a string used to identify
    which keys result in calls to the user-supplied routine. Wildcard
    characters are allowed in this string. If you omit this argument,
    the routine is called for every key in the index. The match_desc
    argument is valid only for libraries that have ASCII keys.

3 - Description

    LBR$GET_INDEX searches through the specified index for a key that
    matches the argument match_desc. Each time it finds a match, it
    calls the routine specified by the routine_name argument. If you
    do not specify the match_desc argument, it calls the routine for
    every key in the index.

    For example, if you call LBR$GET_INDEX with match_desc equal to
    TR* and index_number set to 1 (module name table), then LBR$GET_
    INDEX calls routine_name for each module whose name begins with
    TR.

4 - Condition Values Returned

    LBR$_ILLCTL        Specified library control index not valid.
    LBR$_ILLIDXNUM     Specified index number not valid.
    LBR$_LIBNOTOPN     Specified library not open.
    LBR$_NULIDX        Specified library empty.