Library /sys$common/syshlp/helplib.hlb  —  LBR Routines, LBR$GET_INDEX
    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] [, 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
    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 on OpenVMS
    Alpha; and passes three arguments to the routine on OpenVMS
    Integrity servers:

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

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

       Flag Bits               Description

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

       This parameter is passed only on OpenVMS Integrity servers.

    The user routine must return a value to indicate success or
    failure. If the user 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.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    If present and non-zero, this argument specifies the type, or all
    types, of the key provided. The flag bits are:

    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 will be provided the key's type through an
    additional third parameter.

3  –  Description

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

    For example, if you call LBR$GET_INDEX on an object library 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.
Close Help