VMS Help  —  LBR Routines, LBR$SEARCH
    The LBR$SEARCH routine finds index keys that point to specified
    data.

    Format

      LBR$SEARCH  library_index ,index_number ,rfa_to_find

                  ,routine_name [, flags]

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. 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
    Library index number. The index_number argument is the address of
    a longword containing the number of the index you want to search.

 rfa_to_find

    OpenVMS usage:vector_longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Record file address (RFA) of the module whose keys you are
    searching for. The rfa_to_find argument is the address of
    a 2-longword array containing the RFA (returned earlier by
    LBR$LOOKUP_KEY or LBR$PUT_RECORD) of the module header.

 routine_name

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    Name of a user-supplied routine to process the keys. The routine_
    name argument is the address of the procedure value of a user-
    supplied routine to call for each key entry containing the RFA
    (in other words, for each key that points to the same module
    header).

    This user-supplied routine cannot contain any calls to
    LBR$DELETE_KEY or LBR$INSERT_KEY.

 flags

    OpenVMS usage:mask_longword
    type:         longword unsigned
    access:       read only
    mechanism:    by reference
    If present and nonzero, the flags argument specifies the type, or
    all types, of the key provided. The flag bits are as follows:

    Flag Bits               Description

    LBR$M_SYM_WEAK = 0x1    UNIX-style weak symbol attribute
    LBR$M_SYM_GROUP = 0x2   Group symbol attribute
    LBR$M_SYM_ALL =         All symbols
    0x80000000

    The user routine is provided the symbol's type through an
    additional third parameter.

3  –  Description

    The LBR$SEARCH routine searches the library index for symbols
    with the given RFA and calls the supplied routine with those
    symbols.

    Use LBR$SEARCH to find index keys that point to the same module
    header. Generally, in index number 1 (the module name table),
    just one key points to any particular module; thus, you would
    probably use this routine only to search library indexes where
    more than one key points to a module. For example, you might call
    LBR$SEARCH to find all the symbols in the symbol index that are
    associated with an object module in an object library.

    If LBR$SEARCH finds an index key associated with the specified
    RFA, it calls a user-supplied routine with two arguments:

    o  The key argument, which is the address of either of the
       following items:

       -  A string descriptor for the key name (libraries with ASCII
          key names)

       -  An unsigned longword for the key value (libraries with
          binary keys)

    o  The RFA argument, which is the address of a 2-longword array
       containing the RFA of the module header

    o  The key's type, whose flag bits are as follows:

       Flag Bits               Description

       LBR$M_SYM_WEAK = 1      UNIX-style weak symbol attribute
       LBR$M_SYM_GROUP = 2     Group symbol attribute

    The user routine must return a value to indicate success or
    failure. If the specified user routine returns a false value
    (low bit = 0), then the index search terminates.

    Note that the key found by LBR$SEARCH is valid only during the
    call to the user-supplied routine. If you want to use the key
    later, you must copy it.

4  –  Condition Values Returned

    LBR$_ILLCTL        Specified library control index not valid.
    LBR$_ILLIDXNUM     Specified library index number not valid.
    LBR$_KEYNOTFND     Library routine did not find any keys with the
                       specified RFA.
    LBR$_LIBNOTOPN     Specified library not open.
Close Help