1 LBR_Routines The Librarian (LBR) routines let you create and maintain libraries and their modules, and use the data stored in library modules. 2 LBR$CLOSE The LBR$CLOSE routine closes an open library. Format LBR$CLOSE library_index 3 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. 3 Argument 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. 3 Description When you are finished working with a library, you should call LBR$CLOSE to close it. Upon successful completion, LBR$CLOSE closes the open library and deallocates all of the memory used for processing it. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$DELETE_DATA The LBR$DELETE_DATA routine deletes module data from the library. Format LBR$DELETE_DATA library_index, txtrfa [,flags] 3 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. 3 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. txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Record's file address (RFA) of the module header for the module you want to delete. The txtrfa argument is the address of the 2- longword array that contains the RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_KEY or LBR$PUT_RECORD. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value The contents of the flag are ignored. The purpose of this argument is to indicate to this routine that the application knows about the new index structure for ELF object and ELF shareable image libraries. 3 Description To delete a library module, first call LBR$DELETE_KEY to delete all keys that point to it. If no library index keys are pointing to the module header, LBR$DELETE_DATA deletes the module header and associated data records; otherwise, this routine returns the error LBR$_STILLKEYS. Note that other library routines can reuse data blocks that contain no data. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_INVRFA Specified RFA not valid. LBR$_LIBNOTOPN Specified library not open. LBR$_STILLKEYS Keys in other indexes still point to the module header. Therefore, the specified module was not deleted. 2 LBR$DELETE_KEY The LBR$DELETE_KEY routine removes a key from the current library index. Format LBR$DELETE_KEY library_index, key_name[, txtrfa] [, flags] 3 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. 3 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 a longword that contains the index. key_name OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The key to be deleted from the library index. For libraries with binary keys, the key_name argument is the address of an unsigned longword containing the key number. For libraries with ASCII keys, the key_name argument is the address of the string descriptor pointing to the key with the following argument characteristics: Argument Characteristics Entry OpenVMS usage char_string type character string access read only mechanism by descriptor txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The txtrfa argument is the address of the 2-longword array that contains the record file address (RFA). If present and if the flags argument is not present, the routine scans for all types of the key for the specified txtrfa and delete those entries. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value If present, this argument indicates that a particular type of the key or all types of the key is to be deleted. The flags bits are as follows: Flag Bits Description LBR$M_SYM_WEAK = UNIX-style weak symbol attribute 0x1 LBR$M_SYM_GROUP = Group symbol attribute 0x2 LBR$M_SYM_ALL = All symbols 0x80000000 If the txtrfa argument is not present or if its value is zero, the type indicated by flags is deleted. If txtrfa specifies a nonzero value, the entry of the type indicated, with the txtrfa supplied, is removed. Note that only one type or all types can be specified. 3 Description If LBR$DELETE_KEY finds the key specified by key_name in the current index, it deletes the key. Note that if you want to delete a library module, you must first use LBR$DELETE_KEY to delete all the keys that point to it, then use LBR$DELETE_DATA to delete the module's header and associated data. You cannot call LBR$DELETE_KEY from within the user-supplied routine specified in LBR$SEARCH or LBR$GET_INDEX. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_KEYNOTFND Specified key not found. LBR$_LIBNOTOPN Specified library not open. LBR$_UPDIRTRAV Specified index update not valid in a user- supplied routine specified in LBR$SEARCH or LBR$GET_INDEX. 2 LBR$FIND The LBR$FIND routine sets the current internal read context for the library to the library module specified. Format LBR$FIND library_index ,txtrfa 3 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. 3 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. txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Record's file address (RFA) of the module header for the module you want to access. The txtrfa argument is the address of a 2- longword array containing the RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_KEY or LBR$PUT_RECORD. 3 Description Use the LBR$FIND routine to access a module that you had accessed earlier in your program. For example, if you look up several keys with LBR$LOOKUP_KEY, you can save the RFAs returned by LBR$LOOKUP_KEY and later use LBR$FIND to reaccess the modules. Thus, you do not have to look up the module header's key every time you want to access the module. If the specified RFA is valid, LBR$FIND initializes internal tables so you can read the associated data. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_INVRFA Specified RFA not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$FLUSH The LBR$FLUSH routine writes modified blocks back to the library file and frees the virtual memory the blocks had been using. Format LBR$FLUSH library_index ,block_type 3 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. 3 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. block_type OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Extent of the flush operation. The block_type argument contains the longword value that indicates how the flush operation proceeds. If you specify LBR$C_FLUSHDATA, the data blocks are flushed. If you specify LBR$C_FLUSHALL, first the data blocks and then the current library index are flushed. Each programming language provides an appropriate mechanism for accessing these symbols. 3 Description LBR$FLUSH cannot be called from other LBR routines that reference cache addresses or by routines called by LBR routines. 3 Condition_Values_Returned LBR$_NORMAL Operation completed successfully. LBR$_BADPARAM Error. A value passed to the LBR$FLUSH routine was either out of range or an illegal value. LBR$_WRITERR Error. An error occurred during the writing of the cached update blocks to the library file. 2 LBR$GET_HEADER The LBR$GET_HEADER routine returns information from the library's header to the caller. Format LBR$GET_HEADER library_index ,retary 3 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. 3 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. retary OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Array of 128 longwords that receives the library header. The retary argument is the address of the array that contains the header information. The information returned in the array is listed in the following table. Each programming language provides an appropriate mechanism for accessing this information. Offset in Longwords Symbolic Name Contents 0 LHI$L_TYPE Library type (see LBR$OPEN for possible values) 1 LHI$L_NINDEX Number of indexes 2 LHI$L_MAJORID Library format major identification 3 LHI$L_MINORID Library format minor identification 4 LHI$T_LBRVER ASCIC version of Librarian 12 LHI$L_CREDAT Creation date/time 14 LHI$L_UPDTIM Date/time of last update 16 LHI$L_UPDHIS Virtual block number (VBN) of start of update history 17 LHI$L_FREEVBN First logically deleted block 18 LHI$L_FREEBLK Number of deleted blocks 19 LHI$B_NEXTRFA Record file address (RFA) of end of library 21 LHI$L_NEXTVBN Next VBN to allocate at end of file 22 LHI$L_ Number of free preallocated index blocks FREIDXBLK 23 LHI$L_FREEIDX List head for preallocated index blocks 24 LHI$L_HIPREAL VBN of highest preallocated block 25 LHI$L_IDXBLKS Number of index blocks in use 26 LHI$L_IDXCNT Number of index entries (total) 27 LHI$L_MODCNT Number of entries in index 1 (module names) 28 LHI$L_MHDUSZ Number of bytes of additional information reserved in module header 29 LHI$L_ Maximum number of library update history MAXLUHREC records maintained 30 LHI$L_ Number of library update history records NUMLUHREC in history 31 LHI$L_ Library status (false if there was an LIBSTATUS error closing the library) 32-128 Reserved by HP 3 Description On successful completion, LBR$GET_HEADER places the library header information into the array of 128 longwords. Note that the offset is the byte offset of the value into the header structure. You can convert the offset to a longword subscript by dividing the offset by 4 and adding 1 (assuming that subscripts in your programming language begin with 1). 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$GET_HELP The LBR$GET_HELP routine retrieves help text from a help library, displaying it on SYS$OUTPUT or calling your routine for each record returned. Format LBR$GET_HELP library_index [,line_width] [,routine] [,data] [,key_1] [,key_2 . . . ,key_10] 3 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. 3 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. line_width OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Width of the help text line. The line_width argument is the address of a longword containing the width of the listing line. If you do not supply a line width or if you specify 0, the line width defaults to 80 characters per line. routine OpenVMS usage:procedure type: procedure value access: read only mechanism: by reference Routine called for each line of text you want output. The routine argument is the address of the procedure value for this user- written routine. If you do not supply a routine argument, LBR$GET_HELP calls the Run-Time Library procedure LIB$PUT_OUTPUT to send the help text lines to the current output device (SYS$OUTPUT). However, if you want SYS$OUTPUT for your program to be a disk file rather than the terminal, you should supply a routine to output the text. If the user-written routine returns an error status with low bit clear, the LBR$GET_HELP routine passes this status to the caller. If the user-written routine returns a success status with low bit set, the LBR$GET_HELP routine returns 1 to the caller. The routine you specify is called with an argument list of four longwords: 1. The first argument is the address of a string descriptor for the output line. 2. The second argument is the address of an unsigned longword containing flag bits that describe the contents of the text being passed. The possible flags are as follows: HLP$M_ Specified help text cannot be found. NOHLPTXT HLP$M_ Text contains key names of the printed text. KEYNAMLIN HLP$M_ Text is part of the information provided on OTHERINFO additional help available. Each programming language provides an appropriate mechanism for accessing these flags. Note that, if no flag bit is set, help text is passed. 3. The third argument is the address stipulated in the data argument specified in the call to LBR$GET_HELP (or the address of a 0 constant if the data argument is zero or was omitted). 4. The fourth argument is a longword containing the address of the current key level. The routine you specify must return with success or failure status. A failure status (low bit = 0) terminates the current call to LBR$GET_HELP. data OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Data passed to the routine specified in the routine argument. The data argument is the address of data for the routine. The address is passed to the routine specified in the routine argument. If you omit this argument or specify it as zero, then the argument passed in your routine will be the address of a zero constant. key_1,key_2, . . . ,key_10 OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by descriptor Level of the help text to be output. Each key_1,key_2, . . . ,key_ 10 argument is the address of a descriptor pointing to the key for that level. If the key_1 descriptor is 0 or if it is not present, LBR$GET_ HELP assumes that the key_1 name is HELP, and it ignores all the other keys. For key_2 through key_10, a descriptor address of 0, or a length of 0, or a string address of 0 terminates the list. The key argument may contain any of the following special character strings: String Meaning * Return all level 1 help text in the library. KEY . . .Return all help text associated with the specified key and its subkeys (valid for level 1 keys only). * . . . Return all help text in the library. 3 Description LBR$GET_HELP returns all help text in the same format as the output returned by the DCL command HELP; that is, it indents two spaces for every key level of text displayed. (Because of this formatting, you may want to make your help messages shorter than 80 characters, so they fit on one line on terminal screens with the width set to 80.) If you do not want the help text indented to the appropriate help level, you must supply your own routine to change the format. Note that most application programs use LBR$OUTPUT_HELP instead of LBR$GET_HELP. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. LBR$_NOTHLPLIB Specified library not a help library. 2 LBR$GET_HISTORY The LBR$GET_HISTORY routine returns each library update history record to a user-specified action routine. Format LBR$GET_HISTORY library_index ,action_routine 3 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. 3 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. action_routine OpenVMS usage:procedure type: procedure value access: modify mechanism: by reference User-supplied routine for processing library update history records. The action_routine argument is the address of the procedure value of this user-supplied routine. The routine is invoked once for each update history record in the library. One argument is passed to the routine, namely, the address of a descriptor pointing to a history record. 3 Description This routine retrieves the library update history records written by the routine LBR$PUT_HISTORY. 3 Condition_Values_Returned LBR$_NORMAL Normal exit from the routine. LBR$_EMPTYHIST History empty. This is an informational code, not an error code. LBR$_INTRNLERR Internal Librarian routine error occurred. LBR$_NOHISTORY No update history. This is an informational code, not an error code. 2 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] 3 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. 3 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. 3 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. 2 LBR$GET_RECORD The LBR$GET_RECORD routine returns the next data record in the module associated with a specified key. Format LBR$GET_RECORD library_index [,inbufdes] [,outbufdes] 3 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. 3 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. The library must be open and LBR$LOOKUP_KEY or LBR$FIND must have been called to find the key associated with the module whose records you want to read. inbufdes OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor User buffer to receive the record. The inbufdes argument is the address of a string descriptor that points to the buffer that receives the record from LBR$GET_RECORD. This argument is required when the Librarian subroutine record access is set to move mode (which is the default). This argument is not used if the record access mode is set to locate mode. The Description help topic contains more information about the locate and move modes. outbufdes OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String descriptor that receives the actual length and address of the data for the record returned. The outbufdes argument is the address of the string descriptor for the returned record. The length and address fields of the string descriptor are filled in by the LBR$GET_RECORD routine. This parameter must be specified when Librarian subroutine record access is set to locate mode. This parameter is optional if record access mode is set to move mode. The Description help topic contains more information about the locate and move modes. 3 Description Before calling LBR$GET_RECORD, you must first call LBR$LOOKUP_ KEY or LBR$FIND to set the internal library read context to the record's file address (RFA) of the module header of the module whose records you want to read. LBR$GET_RECORD uses two record access modes: locate mode and move mode. Move mode is the default. The LBR$SET_LOCATE and LBR$SET_MOVE subroutines set these modes. The record access modes are mutually exclusive; that is, when one is set, the other is turned off. If move mode is set, LBR$GET_RECORD copies the record to the user-specified buffer described by inbufdes. If you have optionally specified the output buffer string descriptor, outbufdes, the Librarian fills it with the actual length and address of the data. If locate mode is set, LBR$GET_RECORD returns the record by way of an internal subroutine buffer, pointing the outbufdes descriptor to the internal buffer. The second parameter, inbufdes, is not used when locate mode is set. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. LBR$_LKPNOTDON Requested key lookup not done. RMS$_EOF Error. An attempt has been made to read past the logical end of the data in the module. 2 LBR$INI_CONTROL The LBR$INI_CONTROL routine initializes a control structure, called a library control index, to identify the library for use by other LBR routines. Format LBR$INI_CONTROL library_index ,func [,type] [,namblk] 3 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. 3 Arguments library_index OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of a longword that is to receive the index. func OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Library function to be performed. The func argument is the address of the longword that contains the library function. Valid functions are LBR$C_CREATE, LBR$C_READ, and LBR$C_UPDATE. Each programming language provides an appropriate mechanism for accessing these symbols. type OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Library type. The type argument is the address of the longword containing the library type. Valid library types include the following: o LBR$C_TYP_EOBJ (Alpha object) o LBR$C_TYP_ESHSTB (Alpha shareable image) o LBR$C_TYP_MLB (macro) o LBR$C_TYP_HLP (help) o LBR$C_TYP_TXT (text) o LBR$C_TYP_UNK (unknown) o LBR$C_TYP_NCS (NCS library) o For user-developed libraries, a type in the range of LBR$C_ TYP_USRLW through LBR$C_TYP_USRHI. namblk OpenVMS usage:nam type: longword (unsigned) access: read only mechanism: by reference OpenVMS RMS name block (NAM). The namblk argument is the address of a variable-length data structure containing an RMS NAM block. The LBR$OPEN routine fills in the information in the NAM block so it can be used later to open the library. If the NAM block has this file identification in it from previous use, the LBR$OPEN routine uses the open-by-NAM block option. This argument is optional and should be used if the library will be opened many times during a single run of the program. For a detailed description of RMS NAM blocks, see the OpenVMS Record Management Services Reference Manual. 3 Description Except for the LBR$OUTPUT_HELP routine, you must call LBR$INI_ CONTROL before calling any other LBR routine. After you initialize the library control index, you must open the library or create a new one using the LBR$OPEN routine. You can then call other LBR routines that you need. After you finish working with a library, close it with the LBR$CLOSE routine. LBR$INI_CONTROL initializes a library by filling the longword referenced by the library_index argument with the control index of the library. Upon completion of the call, the index can be used to refer to the current library in all future routine calls. Therefore, your program must not alter this value. You can have up to 16 libraries open simultaneously in your program. 3 Condition_Values_Returned LBR$_NORMAL Library control index initialized successfully. LBR$_ILLFUNC Requested function not valid. LBR$_ILLTYP Specified library type not valid. LBR$_TOOMNYLIB Error. An attempt was made to allocate more than 16 control indexes. 2 LBR$INSERT_KEY The LBR$INSERT_KEY routine inserts a new key in the current library index. Format LBR$INSERT_KEY library_index ,key_name ,txtrfa [, flags] 3 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. 3 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 library routine. The library_index argument is the address of the longword that contains the index. key_name OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Name of the new key you are inserting. If the library uses binary keys, the key_name argument is the address of an unsigned longword containing the value of the key. If the library uses ASCII keys, the key_name argument is the address of a string descriptor of the key with the following argument characteristics: Argument CharacteristicsEntry OpenVMS char_string usage type character string access read only mechanism by descriptor txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: modify mechanism: by reference The record file address (RFA) of the module associated with the new key you are inserting. The txtrfa argument is the address of a 2-longword array containing the RFA. You can use the RFA returned by the first call to LBR$PUT_RECORD. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value If present, specifies the key's type. 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 If this argument is not present, the normal NonGroup-Global type is the assumed type. 3 Description The LBR$INSERT_KEY routine inserts a new key in the current library index. You cannot call LBR$INSERT_KEY within the user- supplied routine specified in LBR$SEARCH or LBR$GET_INDEX. 3 Condition_Values_Returned LBR$_DUPKEY Index already contains the specified key. LBR$_ILLCTL Specified library control index not valid. LBR$_INVRFA Specified RFA does not point to valid data. LBR$_LIBNOTOPN Specified library not open. LBR$_UPDURTRAV LBR$INSERT_KEY is called by the user-defined routine specified in LBR$SEARCH or LBR$GET_ INDEX. 2 LBR$LOOKUP_KEY The LBR$LOOKUP_KEY routine looks up a key in the library's current index and prepares to access the data in the module associated with the key. Format LBR$LOOKUP_KEY library_index ,key_name ,txtrfa [, flags] 3 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. 3 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. key_name OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Name of the library key. If the library uses binary keys, the key_name argument is the address of the unsigned longword value of the key. If the library uses ASCII keys, the key_name argument is the address of a string descriptor for the key with the following argument characteristics: Argument Characteristics Entry OpenVMS usage char_string type character string access read only mechanism by descriptor txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: write only mechanism: by reference The record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array that receives the RFA of the module header. flags OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference The flags argument, if present and not zero, receives the type of key returned. The flag bits are as follows: Flag Bits Description LBR$SYM_WEAK = 0x1 UNIX-style weak symbol attribute LBR$SYM_GROUP = 0x2 Group symbol attribute The key returned is the highest precedent definition type present. 3 Description If LBR$LOOKUP_KEY finds the specified key, it initializes internal tables so you can access the associated data. This routine returns the RFA to the 2-longword array referenced by txtrfa. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_INVRFA RFA obtained not valid. LBR$_KEYNOTFND Specified key not found. LBR$_LIBNOTOPN Specified library not open. 2 LBR$LOOKUP_TYPE The LBR$LOOK_TYPE routine searches the index for the key from a particular module (RFA) and returns that key's type for that module. Format LBR$LOOKUP_TYPE library_index, key_name, txtrfa, ret_types 3 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. key_name OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The key_name argument is the address of the string descriptor pointing to the key with the following argument characteristics: Argument Characteristics Entry OpenVMS usage char_string type character string access read only mechanism by descriptor txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array that specifies the RFA of the module header. ret_types OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference The address of a longword to receive the symbol types found for the specified module (txtrfa). The return type bits are as follows: LBR$M_SYM_NGG = 1 LBR$M_SYM_UXWK = 2 LBR$M_SYM_GG = 4 LBR$M_SYM_GUXWK = 8 3 Description This routine searches the index for the key from a particular module (RFA) and returns that key's type for that module, if present. Otherwise, it returns LBR$_KEYNOTFND. 2 LBR$MAP_MODULE The LBR$MAP_MODULE routine maps a module into process P2 space. Format LBR$MAP_MODULE library_index, ret_va_addr, ret_mod_len, txtrfa 3 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 library routine. The library_index argument is the address of the longword that contains the index. ret_va_addr OpenVMS usage:address type: quadword address access: write only mechanism: by 32-bit or 64-bit reference The 32-bit or 64-bit virtual address of a naturally aligned quadword into which the routine returns the virtual address at which the routine mapped the library module. ret_mod_len OpenVMS usage:byte_count type: quadword (unsigned) access: read only mechanism: by reference The address of a naturally aligned quadword into which the library routine returns the module length. txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array that specifies the RFA of the module header. 3 Description This routine maps a module, with the given txtrfa, into process P2 memory space and returns the virtual address where the module is mapped and the module size. Unlike other LBR services that use RMS services, LBR$MAP_MODULE also uses system services. Because of this, the secondary status for error returns is placed in LBR$$GL_SUBSTS. Use this secondary status to find additional status when an error is returned. 2 LBR$OPEN The LBR$OPEN routine opens an existing library or creates a new one. Format LBR$OPEN library_index [,fns] [,create_options] [,dns] [,rlfna] [,rns] [,rnslen] 3 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. 3 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 a longword containing the index. fns OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification of the library. The fns argument is the address of a string descriptor pointing to the file specification. Unless the OpenVMS RMS NAM block address was previously supplied in the LBR$INI_CONTROL routine and contained a file specification, this argument must be included. Otherwise, the Librarian returns an error (LBR$_NOFILNAM). create_options OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Library characteristics. The create_options argument is the address of an array of 20 longwords that define the characteristics of the library you are creating. If you are creating a library with LBR$C_CREATE, you must include the create_options argument. The following table shows the entries that the array must contain. Each programming language provides an appropriate mechanism for accessing the listed symbols. Offset in Longwords Symbolic Name Contents 0 CRE$L_TYPE Library type: LBR$C_TYP_UNK (0) Unknown/unspecified LBR$C_TYP_OBJ (1) VAX object LBR$C_TYP_MLB (2) Macro LBR$C_TYP_HLP (3) Help LBR$C_TYP_TXT (4) Text LBR$C_TYP_SHSTB (5) VAX shareable image LBR$C_TYP_NCS (6) NCS LBR$C_TYP_EOBJ (7) Alpha object LBR$C_TYP_ESHSTB Alpha shareable image (8) (9-127) Reserved by HP LBR$C_TYP_USRLW User library types - low end of (128) range LBR$C_TYP_USRHI User library types - high end of (255) range 1 CRE$L_KEYLEN Maximum length of ASCII keys or, if 0, indicates 32-bit unsigned keys (binary keys) 2 CRE$L_ALLOC Initial library file allocation 3 CRE$L_IDXMAX Number of library indexes (maximum of eight) 4 CRE$L_UHDMAX Number of additional bytes to reserve in module header 5 CRE$L_ENTALL Number of index entries to preallocate 6 CRE$L_LUHMAX Maximum number of library update history records to maintain 7 CRE$L_VERTYP Format of library to create: CRE$C_VMSV2 VMS Version 2.0 CRE$C_VMSV3 VMS Version 3.0 8 CRE$L_IDXOPT Index key casing option: CRE$C_HLPCASING Treat character case as it is for help libraries CRE$C_OBJCASING Treat character case as it is for object libraries CRE$C_MACTXTCAS Treat character case as it is for macro and text libraries 9-19 Reserved by HP The input of uppercase and lowercase characters is treated differently for help, object, macro, and text libraries. For details, see the HP OpenVMS Command Definition, Librarian, and Message Utilities Manual. dns OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Default file specification. The dns argument is the address of the string descriptor that points to the default file specification. See the OpenVMS Record Management Services Reference Manual for details about how defaults are processed. rlfna OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Related file name. The rlfna argument is the address of an RMS NAM block pointing to the related file name. You must specify rlfna for related file name processing to occur. If a related file name is specified, only the file name, type, and version fields of the NAM block are used for related name block processing. The device and directory fields are not used. See the OpenVMS Record Management Services Reference Manual for details on processing related file names. rns OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Resultant file specification returned. The rns argument is the address of a string descriptor pointing to a buffer that is to receive the resultant file specification string. If an error occurs during an attempt to open the library, the expanded name string is returned instead. rnslen OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Length of the resultant or expanded file name. The rnslen argument is the address of a longword receiving the length of the resultant file specification string (or the length of the expanded name string if there was an error in opening the library). 3 Description You can call this routine only after you call LBR$INI_CONTROL and before you call any other LBR routine except LBR$OUTPUT_HELP. When the library is successfully opened, the LBR routine reads the library header into memory and sets the default index to 1. If the library cannot be opened because it is already open for a write operation, LBR$OPEN retries the open operation every second for a maximum of 30 seconds before returning the RMS error, RMS$_ FLK, to the caller. 3 Condition_Values_Returned LBR$_ERRCLOSE Error. When the library was last modified while opened for write access, the write operation was interrupted. This left the library in an inconsistent state. LBR$_ILLCREOPT Requested create options not valid or not supplied. LBR$_ILLCTL Specified library control index not valid. LBR$_ILLFMT Specified library format not valid. LBR$_ILLFUNC Specified library function not valid. LBR$_LIBOPN Specified library already open. LBR$_NOFILNAM Error. The fns argument was not supplied or the RMS NAM block was not filled in. LBR$_OLDLIBRARY Success. The specified library has been opened; the library was created with an old library format. LBR$_OLDMISMCH Requested library function conflicts with old library type specified. LBR$_TYPMISMCH Library type does not match the requested type. 2 LBR$OUTPUT_HELP The LBR$OUTPUT_HELP routine outputs help text to a user-supplied output routine. The text is obtained from an explicitly named help library or, optionally, from user-specified default help libraries. An optional prompting mode is available that enables LBR$OUTPUT_HELP to interact with you and continue to provide help information after the initial help request has been satisfied. Format LBR$OUTPUT_HELP output_routine [,output_width] [,line_desc] [,library_name] [,flags] [,input_routine] 3 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. 3 Arguments output_routine OpenVMS usage:procedure type: procedure value access: write only mechanism: by reference Name of a routine that writes help text a line at a time. The output_routine argument is the address of the procedure value of the routine to call. You should specify either the address of LIB$PUT_OUTPUT or a routine of your own that has the same calling format as LIB$PUT_OUTPUT. output_width OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Width of the help-text line to be passed to the user-supplied output routine. The output_width argument is the address of a longword containing the width of the text line to be passed to the user-supplied output routine. If you omit output_width or specify it as 0, the default output width is 80 characters per line. line_desc OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Contents of the help request line. The line_desc argument is the address of a string descriptor pointing to a character string containing one or more help keys defining the help requested, for example, the HELP command line minus the HELP command and HELP command qualifiers. The default is a string descriptor for an empty string. library_name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the main library. The library_name argument is the address of a string descriptor pointing to the main library file specification string. The default is a null string, which means you should use the default help libraries. If you omit the device and directory specifications, the default is SYS$HELP. The default file type is .HLB. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Flags specifying help output options. Each programming language provides an appropriate mechanism for accessing these flags. The flags argument is the address of an unsigned longword that contains the following flags, when set: Flag Description HLP$M_PROMPT Interactive help prompting is in effect. HLP$M_ The process logical name table is searched for PROCESS default help libraries. HLP$M_GROUP The group logical name table is searched for group default help libraries. HLP$M_SYSTEM The system logical name table is searched for system default help libraries. HLP$M_ The list of default libraries available is output LIBLIST with the list of topics available. HLP$M_HELP The list of topics available in a help library is preceded by the major portion of the text on help. If you omit this longword, the default is for prompting and all default library searching to be enabled, but no library list is generated and no help text precedes the list of topics. input_routine OpenVMS usage:procedure type: procedure value access: read only mechanism: by reference Routine used for prompting. The input_routine argument is the address of the procedure value of the prompting routine. You should specify either the address of LIB$GET_INPUT or a routine of your own that has the same calling format as LIB$GET_INPUT. This argument must be supplied when the HELP command is run in prompting mode (that is, HLP$M_PROMPT is set or defaulted). 3 Description The LBR$OUTPUT_HELP routine provides a simple, one-call method to initiate an interactive help session. Help library bookkeeping functions, such as LBR$INI_CONTROL and LBR$OPEN, are handled internally. You should not call LBR$INI_CONTROL or LBR$OPEN before you issue a call to LBR$OUTPUT_HELP. LBR$OUTPUT_HELP accepts help keys in the same format as LBR$GET_ HELP, with the following qualifications: o If the keyword HELP is supplied, help text on HELP is output, followed by a list of HELP subtopics available. If no help keys are provided or if the line_desc argument is 0, a list of topics available in the root library is output. o If the line_desc argument contains a list of help keys, then each key must be separated from its predecessor by a slash (/) or by one or more spaces. o The first key can specify a library to replace the main library as the root library (the first library searched) in which LBR$OUTPUT_HELP searches for help. A key used for this purpose must have the form <@filespec>, where filespec is subject to the same restrictions as the library_name argument. If the specified library is an enabled user-defined default library, then filespec can be abbreviated as any unique substring of that default library's logical name translation. In default library searches, you can define one or more default libraries for LBR$OUTPUT_HELP to search for help information not contained in the root library. Do this by equating logical names (HLP$LIBRARY, HLP$LIBRARY_1, . . . ,HLP$LIBRARY_999) to the file specifications of the default help libraries. You can define these logical names in the process, group, or system logical name table. If default library searching is enabled by the flags argument, LBR$OUTPUT_HELP uses those flags to determine which logical name tables are enabled and then automatically searches any user default libraries that have been defined in those logical name tables. The library search order proceeds as follows: root library, main library (if specified and different from the root library), process libraries (if enabled), group libraries (if enabled), system libraries (if enabled). If the requested help information is not found in any of these libraries, LBR$OUTPUT_ HELP returns to the root library and issues a "help not found" message. To enter an interactive help session (after your initial request for help has been satisfied), you must set the HLP$M_PROMPT bit in the flags argument. You can encounter four different types of prompt in an interactive help session. Each type represents a different level in the hierarchy of help available to you. 1. If the root library is the main library and you are not currently examining HELP for a particular topic, the prompt Topic? is output. 2. If the root library is a library other than the main library and if you are not currently examining HELP for a particular topic, a prompt of the form @Topic? is output. 3. If you are currently examining HELP for a particular topic (and subtopics), a prompt of the form subtopic? is output. 4. A combination of 2 and 3. When you encounter one of these prompt messages, you can respond in any one of several ways. Each type of response and its effect on LBR$OUTPUT_HELP in each prompting situation is described in the following table: Action in the Current Prompt Environment Response (Keyed to the prompt in the preceding list) keyword [ . . . ] (1,2) Search all enabled libraries for these keys. (3,4) Search additional help for the current topic (and subtopic) for these keys. @filespec (1,2) Same as above, except that the root [keyword[ . . . ]] library is the library specified by filespec. If the specified library does not exist, treat @filespec as a normal key. (3,4) Same as above; treat @filespec as a normal key. ? (1,2) Display a list of topics available in the root library. (3,4) Display a list of subtopics of the current topic (and subtopics) for which help exists. Carriage Return (1) Exit from LBR$OUTPUT_HELP. (2) Change root library to main library. (3,4) Strip the last keyword from a list of keys defining the current topic (and subtopic) environment. Ctrl/Z (1,2,3,4) Exit from LBR$OUTPUT_HELP. 3 Condition_Values_Returned LBR$_ILLINROU Input routine improperly specified or omitted. LBR$_ILLOUTROU Output routine improperly specified or omitted. LBR$_NOHLPLIS Error. No default help libraries can be opened. LBR$_TOOMNYARG Error. Too many arguments were specified. LBR$_USRINPERR Error. An error status was returned by the user-supplied input routine. 2 LBR$PUT_END The LBR$PUT_END routine marks the end of a sequence of records written to a library by the LBR$PUT_RECORD routine. Format LBR$PUT_END library_index 3 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. 3 Argument 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 a longword containing the index. 3 Description Call LBR$PUT_END after you write data records to the library with the LBR$PUT_RECORD routine. LBR$PUT_END terminates a module by attaching a 3-byte logical end-of-file record (hexadecimal 77,00,77) to the data. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$PUT_HISTORY The LBR$PUT_HISTORY routine adds an update history record to the end of the update history list. Format LBR$PUT_HISTORY library_index ,record_desc 3 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. 3 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. record_desc OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Library history record. The record_desc argument is the address of a string descriptor pointing to the record to be added to the library update history. 3 Description LBR$PUT_HISTORY writes a new update history record. If the library already contains the maximum number of history records (as specified at creation time by CRE$L_LUHMAX; see LBR$OPEN for details), the oldest history record is deleted before the new record is added. 3 Condition_Values_Returned LBR$_NORMAL Normal exit from the routine. LBR$_INTRNLERR Internal Librarian error. LBR$_NOHISTORY No update history. This is an informational code, not an error code. LBR$_RECLNG Record length greater than that specified by LBR$C_MAXRECSIZ. The record was not inserted or truncated. 2 LBR$PUT_MODULE The LBR$PUT_MODULE routine puts an entire module, with the module's record file address (RFA), from memory space into the current library. Format LBR$PUT_MODULE library_index, mod_addr, mod_len, txtrfa 3 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 library routine. The library_index argument is the address of the longword that contains the index. mod_addr OpenVMS usage:address type: quadword address access: read only mechanism: by 32-bit or 64-bit reference The address from which the Library service obtains the 64-bit address of where the module is mapped in memory. The mod_addr argument is the 32- or 64-bit virtual address of a naturally aligned quadword containing the virtual address location of the module to write to the library. mod_len OpenVMS usage:byte_count type: quadword (unsigned) access: read only mechanism: by 32- or 64-bit reference The 64-bit virtual address of a naturally aligned quadword containing the length of the module that the Library service is to write into the library. txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: write only mechanism: by reference The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array receiving the RFA of the newly created module header. 3 Description The LBR$PUT_MODULE routine puts an entire module, with the module's record file address (RFA), from memory space into the current library. LBR$PUT_END is not required when you write an entire module to the current library. 2 LBR$PUT_RECORD The LBR$PUT_RECORD routine writes a data record beginning at the next free location in the library. Format LBR$PUT_RECORD library_index ,bufdes ,txtrfa [, mod_size] 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: 0 Longword condition value. Most utility routines return a condition value. Condition values that this routine can return are listed under Condition Values Returned. 3 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. bufdes OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Record to be written to the library. The bufdes argument is the address of a string descriptor pointing to the buffer containing the output record. On Integrity servers and Alpha libraries, the symbolic maximum record size is ELBR$_MAXRECSIZ. txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Record's file address (RFA) of the module header. The txtrfa argument is the address of a 2-longword array receiving the RFA of the newly created module header upon the first call to LBR$PUT_RECORD. mod_size OpenVMS usage:byte_count type: longword (unsigned) access: read only mechanism: by value The value from mod_size is read on the first call to this routine and ignored otherwise. The value specifies the size of the module to be entered so that contiguous space is allocated within the library for that module. This argument is ignored for non-ELF object libraries and for data-reduced ELF object libraries. The LBR$PUT_END routine is still required to terminate the byte stream and close off the module. 3 Description If this is the first call to LBR$PUT_RECORD, this routine first writes a module header and returns its RFA to the 2-longword array pointed to by txtrfa. LBR$PUT_RECORD then writes the supplied data record to the library. On subsequent calls to LBR$PUT_RECORD, this routine writes the data record beginning at the next free location in the library (after the previous record). The last record written for the module should be followed by a call to LBR$PUT_END. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$REPLACE_KEY The LBR$REPLACE_KEY routine modifies or inserts a key into the library. Format LBR$REPLACE_KEY library_index ,key_name ,oldrfa ,newrfa [, flags] 3 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. 3 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. key_name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor For libraries with ASCII keys, the key_name argument is the address of a string descriptor for the key. For libraries with binary keys, the key_name argument is the address of an unsigned longword value for the key. oldrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Old record file address (RFA). The oldrfa argument is the address of a 2-longword array containing the original RFA (returned by LBR$LOOKUP_KEY) of the module header associated with the key you are replacing. newrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference New RFA. The newrfa argument is the address of a 2-longword array containing the RFA (returned by LBR$PUT_RECORD) of the module header associated with the new key. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference If present, the flags argument specifies the type of key being replaced. The flag bits are as follows: Flag Bits Description LBR$SYM_WEAK = 0x1 UNIX-style weak symbol attribute LBR$SYM_GROUP = 0x2 Group symbol attribute If this argument is not present, NonGroup-Global is the assumed type. In this case, all type lists are searched and the entries removed. The new symbol is placed in the new NonGroup-Global definition with newrfa as the defining module. If this parameter is present, it represents the flags set for the type of symbol being replaced. The replacement is done in place without losing its position in the type list. If the symbol does not exist when the call to this routine is made, the new definition is placed at the end of the type list for the specified type. Because there are now different symbol definition types, HP advises using the LBR$DELETE_KEY routine followed by the LBR$INSERT_KEY routine when the old key and new key differ in definition type. 3 Description If LBR$REPLACE_KEY does not find the key in the current index, it calls the LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY does find the key, it modifies the key entry in the index so that it points to the new module header. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_INVRFA Specified RFA not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$RET_RMSSTV The LBR$RET_RMSSTV routine returns the status value of the last OpenVMS RMS function performed by any LBR subroutine. Format LBR$RET_RMSSTV 3 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. 3 Arguments None. 3 Description The LBR$RET_RMSSTV routine returns, as the status value, the status of the last RMS operation performed by the Librarian. Each programming language provides an appropriate mechanism for accessing RMS status values. 3 Condition_Values_Returned This routine returns any condition values returned by RMS routines. 2 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] 3 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. 3 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. 3 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. 2 LBR$SET_INDEX The LBR$SET_INDEX routine sets the index number to use when processing libraries that have more than one index. Format LBR$SET_INDEX library_index ,index_number 3 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. 3 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 Index number you want to establish as the current index number. The index_number argument is the address of the longword that contains the number of the index you want to establish as the current index. 3 Description When you call LBR$INI_CONTROL, the Librarian sets the current library index to 1 (the module name table, unless the library is a user-developed library). If you need to process another library index, you must use LBR$SET_INDEX to change the current library index. Note that macro, help, and text libraries contain only one index; therefore, you do not need to call LBR$SET_INDEX. Object libraries contain two indexes. If you want to access the global symbol table, you must call the LBR$SET_INDEX routine to set the index number. User-developed libraries can contain more than one index; therefore, you may need to call LBR$SET_INDEX to set the index number. Upon successful completion, LBR$SET_INDEX sets the current library index to the requested index number. LBR routines number indexes starting with 1. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_ILLIDXNUM Library index number specified not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$SET_LOCATE The LBR$SET_LOCATE routine sets the record access of LBR subroutines to locate mode. Format LBR$SET_LOCATE library_index 3 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. 3 Argument 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. 3 Description Librarian record access may be set to move mode (the default set by LBR$SET_MOVE) or locate mode. The setting affects the operation of the LBR$GET_RECORD routine. If move mode is set (the default), LBR$GET_RECORD copies the requested record to the specified user buffer. If locate mode is set, the record is not copied. Instead, the outbufdes descriptor is set to reference the internal LBR subroutine buffer that contains the record. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$SET_MODULE The LBR$SET_MODULE routine reads, and optionally updates, the module header associated with a given record's file address (RFA). Format LBR$SET_MODULE library_index ,rfa [,bufdesc] [,buflen] [,updatedesc] 3 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. 3 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. rfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Record's file address (RFA) associated with the module header. The rfa argument is the address of a 2-longword array containing the RFA returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY. bufdesc OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Buffer that receives the module header. The bufdesc argument is the address of a string descriptor pointing to the buffer that receives the module header. The buffer must be the size specified by the symbol MHD$B_USRDAT plus the value of the CRE$L_UHDMAX create option. The MHD$ and CRE$ symbols are defined in the modules $MHDDEF and $CREDEF, which are stored in SYS$LIBRARY:STARLET.MLB. buflen OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Length of the module header. The buflen argument is the address of a longword receiving the length of the returned module header. updatedesc OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Additional information to be stored with the module header. The updatedesc argument is the address of a string descriptor pointing to additional data that the Librarian stores with the module header. If you include this argument, the Librarian updates the module header with the additional information. 3 Description If you specify bufdesc, the LBR routine returns the module header into the buffer. If you specify buflen, the routine also returns the buffer's length. If you specify updatedesc, the routine updates the header information. You define the maximum length of the update information (by specifying a value for CRE$L_UHDMAX) when you create the library. The Librarian zero-fills the information if it is less than the maximum length or truncates it if it exceeds the maximum length. 3 Condition_Values_Returned LBR$_HDRTRUNC Buffer supplied to hold the module header was too small. LBR$_ILLCTL Specified library control index not valid. LBR$_ILLOP Error. The updatedesc argument was supplied and the library was a Version 1.0 library or the library was opened only for read access. LBR$_INVRFA Specified RFA does not point to a valid module header. LBR$_LIBNOTOPN Specified library not open. 2 LBR$SET_MOVE The LBR$SET_MOVE routine sets the record access of LBR subroutines to move mode. Format LBR$SET_MOVE library_index 3 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. 3 Argument 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. 3 Description Librarian record access may be set to move mode (the default, set by LBR$SET_MOVE) or locate mode. The setting affects the operation of the LBR$GET_RECORD routine. If move mode is set, LBR$GET_RECORD copies the requested record to the specified user buffer. For details, see the description of LBR$GET_RECORD. 3 Condition_Values_Returned LBR$_ILLCTL Specified library control index not valid. LBR$_LIBNOTOPN Specified library not open. 2 LBR$UNMAP_MODULE The LBR$UNMAP_MODULE routine unmaps a module from process P2 space. Format LBR$PUT_MODULE library_index, txtrfa 3 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 library routine. The library_index argument is the address of the longword that contains the index. txtrfa OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array that specifies the RFA of the module header. 3 Description The LBR$UNMAP_MODULE routine unmaps the module, with the record file address in txtrfa, from process P2 space. This action releases the resources used to map the module. Unlike other LBR services that use RMS services, LBR$UNMAP_MODULE also uses system services. Because of this, the secondary status for error returns is placed in LBR$GL_SUBSTS. Use this to find further status when an error is returned.