SGA API: A Database Statistics Application Programming Interface This guide describes the system global area (SGA) application programming interface (API) that you can use to retrieve database performance statistics. Revision/Update Information: Release 7.1 Copyright © Oracle Corporation, 1996. All rights reserved. This software contains proprietary information of Oracle Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error-free. Restricted Rights Legend Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the programs shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication and disclosure of the programs shall be subject to the restrictions in FAR 52.227-14, Rights in Data- General, including Alternate III (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood Shores, CA 94065. The programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It is the licensee's responsibility to take all appropriate fail-safe, back up, redundancy and other measures to ensure the safe use of such applications if the programs are used for such purposes, and Oracle disclaims liability for any damages caused by such use of the programs. Oracle is a registered trademark of Oracle Corporation, Redwood City, California. Oracle Rdb, Oracle RMU, Oracle RMUwin, Oracle SQL/Services, and Rdb7 are trademarks of Oracle Corporation, Redwood City, California. All other company or product names are used for identification purposes only, and may be trademarks of their respective owners. ii _______________________________________________________ Contents _________________________________________________ 1 PREFACE 1 1.1 Purpose _______________________ 1 1.2 Supported Oracle Rdb Releases _ 1 1.3 Sample Program ________________ 1 1.4 Files for the SGAAPI __________ 2 _______________________________________________________ CHAPTER 1 PROGRAMMING WITH THE SGA API 1-1 _________________________________________________ 1.1 SGA API DESIGN 1-1 1.1.1 Program Routines ______________ 1-1 1.1.2 Program Flow __________________ 1-2 1.1.3 Sample Program ________________ 1-4 1.1.3.1 Compiling and linking the sample program, 1-4 1.1.3.2 Running the sample program, 1-4 1.1.4 Database Context ______________ 1-6 1.1.5 Information and Result Buffer Formats _______________________ 1-6 1.1.5.1 Information Buffer, 1-7 1.1.6 Result Buffer _________________ 1-9 1.1.7 Continuation Context __________ 1-10 1.1.8 Error Tags ____________________ 1-12 1.1.9 General tags __________________ 1-13 1.1.10 Compiling and Linking _________ 1-14 _________________________________________________ 1.2 CLASS AND ITEM TAGS FOR ORACLE RDB DATABASES 1-14 iii Contents 1.2.1 Time and Date Tags (Oracle Rdb only) _________________________ 1-15 _________________________________________________ 1.3 RMUST_CT_AIJINFO - AIJ INFORMATION 1-17 1.3.1 Information Buffer Syntax _____ 1-18 1.3.2 Result Buffer Syntax __________ 1-19 1.3.3 Tag Descriptions ______________ 1-21 1.3.4 Version specific tags _________ 1-26 _________________________________________________ 1.4 RMUST_CT_AIJJNLS - AIJ JOURNAL CLASS 1-28 1.4.1 Information Buffer Syntax _____ 1-28 1.4.2 Tag Descriptions ______________ 1-31 _________________________________________________ 1.5 RMUST_CT_ARPMS_STATS - AREA PERFORMANCE STATISTICS 1-33 1.5.1 Buffer Syntax _________________ 1-33 1.5.2 Result Buffer Syntax __________ 1-34 1.5.3 Tag Descriptions ______________ 1-34 _________________________________________________ 1.6 RMUST_CT_DBINFO - DATABASE INFORMATION 1-34 1.6.1 Information Buffer Syntax _____ 1-35 1.6.2 Result Buffer Syntax __________ 1-36 1.6.3 Tag Descriptions ______________ 1-37 _________________________________________________ 1.7 RMUST_CT_DBR - DATABASE RECOVERY PROCESS INFORMATION 1-40 1.7.1 Information Buffer Syntax _____ 1-41 1.7.2 Result Buffer Syntax __________ 1-41 iv Contents 1.7.3 Tag Descriptions ______________ 1-42 _________________________________________________ 1.8 RMUST_CT_FILE - FILE INFORMATION 1-44 1.8.1 Information Buffer Syntax _____ 1-44 1.8.2 Result Buffer Syntax __________ 1-46 _________________________________________________ 1.9 RMUST_CT_FILE_NODUP - FILE INFORMATION 1-51 _________________________________________________ 1.10 RMUST_CT_PROCESS - PROCESS INFORMATION 1-51 1.10.1 Information Buffer Syntax _____ 1-51 1.10.2 Result Buffer Syntax __________ 1-52 1.10.3 Tag Descriptions ______________ 1-53 _________________________________________________ 1.11 RMUST_CT_STALL - STALLED PROCESS INFORMATION, RMUST_CT_STALL_ACT - STALLED PROCESS INFORMATION 1-54 1.11.1 Information Buffer Syntax _____ 1-55 1.11.2 Result Buffer Syntax __________ 1-55 1.11.3 Tag Descriptions ______________ 1-57 _________________________________________________ 1.12 RMUST_CT_RTPMS_STATS - RUN TIME PERFORMANCE STATISTICS 1-58 1.12.1 Buffer Syntax _________________ 1-59 1.12.2 Result Buffer Syntax __________ 1-59 1.12.3 Tag Descriptions ______________ 1-59 v Contents _______________________________________________________ CHAPTER 2 SGA API ENTRY POINT DESCRIPTIONS 2-1 _________________________________________________ 2.1 KUSCX_ALLOCATE 2-1 2.1.1 Interface _____________________ 2-1 2.1.2 Description ___________________ 2-1 2.1.3 Parameters ____________________ 2-1 2.1.4 Condition Values Returned _____ 2-2 2.1.5 Example _______________________ 2-2 _________________________________________________ 2.2 KUSCX_FREE_HANDLE 2-2 2.2.1 Interface _____________________ 2-2 2.2.2 Description ___________________ 2-2 2.2.3 Parameters ____________________ 2-2 2.2.4 Condition Values Returned _____ 2-2 2.2.5 Example _______________________ 2-3 _________________________________________________ 2.3 KUSCX_INIT 2-3 2.3.1 Interface _____________________ 2-3 2.3.2 Description ___________________ 2-3 2.3.3 Parameters ____________________ 2-3 2.3.4 Condition Values Returned _____ 2-4 2.3.5 Example _______________________ 2-4 _________________________________________________ 2.4 KUSDB_ALLOCATE 2-4 2.4.1 Interface _____________________ 2-4 2.4.2 Description ___________________ 2-4 2.4.3 Parameters ____________________ 2-5 2.4.4 Condition Values Returned _____ 2-5 2.4.5 Example _______________________ 2-5 vi Contents _________________________________________________ 2.5 KUSDB_CONNECT 2-5 2.5.1 Interface _____________________ 2-5 2.5.2 Description ___________________ 2-6 2.5.3 Parameters ____________________ 2-6 2.5.4 Condition Values Returned _____ 2-7 2.5.5 Example _______________________ 2-7 _________________________________________________ 2.6 KUSDB_DISCONNECT 2-7 2.6.1 Interface _____________________ 2-7 2.6.2 Description ___________________ 2-8 2.6.3 Parameters ____________________ 2-8 2.6.4 Condition Values Returned _____ 2-8 2.6.5 Example _______________________ 2-8 _________________________________________________ 2.7 KUSDB_FREE 2-8 2.7.1 Interface _____________________ 2-8 2.7.2 Description ___________________ 2-9 2.7.3 Parameters ____________________ 2-9 2.7.4 Condition Values Returned _____ 2-9 2.7.5 Example _______________________ 2-9 _________________________________________________ 2.8 KUSDB_ERROR_TEXT 2-9 2.8.1 Interface _____________________ 2-9 2.8.2 Description ___________________ 2-10 2.8.3 Parameters ____________________ 2-10 2.8.4 Condition Values Returned _____ 2-10 2.8.5 Example _______________________ 2-10 _________________________________________________ 2.9 KUSDB_GET_INFO 2-11 vii Contents 2.9.1 Interface _____________________ 2-11 2.9.2 Description ___________________ 2-11 2.9.3 Parameters ____________________ 2-12 2.9.4 Condition Values Returned _____ 2-13 2.9.5 Example _______________________ 2-13 _________________________________________________ 2.10 KUSTV_ALLOCATE_HANDLE 2-14 2.10.1 Interface _____________________ 2-14 2.10.2 Description ___________________ 2-15 2.10.3 Parameters ____________________ 2-15 2.10.4 Condition Values Returned _____ 2-15 2.10.5 Example _______________________ 2-16 _________________________________________________ 2.11 KUSTV_DUMP 2-16 2.11.1 Interface _____________________ 2-16 2.11.2 Description ___________________ 2-16 2.11.3 Parameters ____________________ 2-17 2.11.4 Example _______________________ 2-18 _________________________________________________ 2.12 KUSTV_FREE_HANDLE 2-18 2.12.1 Interface _____________________ 2-18 2.12.2 Description ___________________ 2-18 2.12.3 Parameters ____________________ 2-18 2.12.4 Condition Values Returned _____ 2-19 2.12.5 Example _______________________ 2-19 _________________________________________________ 2.13 KUSTV_GET 2-19 2.13.1 Interface _____________________ 2-19 2.13.2 Description ___________________ 2-19 2.13.3 Parameters ____________________ 2-20 viii Contents 2.13.4 Condition Values Returned _____ 2-20 2.13.5 Example _______________________ 2-21 _________________________________________________ 2.14 KUSTV_OFFSET 2-21 2.14.1 Interface _____________________ 2-21 2.14.2 Description ___________________ 2-21 2.14.3 Parameters ____________________ 2-21 2.14.4 Condition Values Returned _____ 2-22 2.14.5 Example _______________________ 2-22 _________________________________________________ 2.15 KUSTV_PUT 2-22 2.15.1 Interface _____________________ 2-22 2.15.2 Description ___________________ 2-22 2.15.3 Parameters ____________________ 2-23 2.15.4 Condition Values Returned _____ 2-23 2.15.5 Example _______________________ 2-24 _________________________________________________ 2.16 KUSTV_REINIT_HANDLE 2-24 2.16.1 Interface _____________________ 2-24 2.16.2 Description ___________________ 2-24 2.16.3 Parameters ____________________ 2-24 2.16.4 Condition Values Returned _____ 2-25 2.16.5 Example _______________________ 2-25 _________________________________________________ 2.17 KUSTVP1_PUT_ONE_BYTE 2-25 2.17.1 Interface _____________________ 2-25 2.17.2 Description ___________________ 2-25 2.17.3 Parameters ____________________ 2-26 2.17.4 Condition Values Returned _____ 2-26 2.17.5 Example _______________________ 2-26 ix Contents _________________________________________________ 2.18 KUSTVP2_PUT_TWO_BYTES 2-27 2.18.1 Interface _____________________ 2-27 2.18.2 Description ___________________ 2-27 2.18.3 Parameters ____________________ 2-27 2.18.4 Condition Values Returned _____ 2-27 2.18.5 Example _______________________ 2-28 _________________________________________________ 2.19 KUSTVP4_PUT_FOUR_BYTES 2-28 2.19.1 Interface _____________________ 2-28 2.19.2 Description ___________________ 2-28 2.19.3 Parameters ____________________ 2-29 2.19.4 Condition Values Returned _____ 2-29 2.19.5 Example _______________________ 2-29 _________________________________________________ 2.20 KUSTVPTG_PUT_TAG 2-30 2.20.1 Interface _____________________ 2-30 2.20.2 Description ___________________ 2-30 2.20.3 Parameters ____________________ 2-30 2.20.4 Condition Values Returned _____ 2-30 2.20.5 Example _______________________ 2-31 _______________________________________________________ TABLES 1 SGAAPI Files __________________ 2 1-1 SGA API Routines ______________ 1-1 1-2 Program Flow __________________ 1-2 1-3 Error Tags ____________________ 1-13 1-4 General Tags __________________ 1-13 1-5 Classes for Oracle Rdb Databases _____________________ 1-15 1-6 Date and Time Return Value Types _________________________ 1-16 x Contents 1-7 Formatted Date and Time Fields ________________________ 1-16 1-8 RMUST_CT_AIJINFO Tags _________ 1-21 1-9 AIJ Operator Notification Tags __________________________ 1-24 1-10 Status values for hot standby log servers ___________________ 1-25 1-11 Lowest version of Oracle Rdb required for tag support ______ 1-27 1-12 AIJ File Information Tags _____ 1-31 1-13 AIJ File State Tags ___________ 1-32 1-14 RMUST_CT_STATS Tags ___________ 1-34 1-15 RMUST_CT_DBINFO Tags __________ 1-37 1-16 RMUST_CT_DBR Tags _____________ 1-42 1-17 DBR Activity Phase Tags _______ 1-43 1-18 RMUST_CT_FILE Tags ____________ 1-47 1-19 File Access Mode Tags _________ 1-50 1-20 RMUST_CT_PROCESS Tags _________ 1-53 1-21 RMUST_CT_STALL Tags ___________ 1-57 1-22 RMUST_CT_RTPMS_STATS Tags _____ 1-59 xi __________________________________________________________________ 1 Preface Oracle Rdb maintains an extensive set of online performance statistics that provide valuable dynamic information regarding the status of an active database. The system global area (SGA) application programming interface (API) described in this document provides a way to retrieve these database performance statistics.________________ 1.1 Purpose The SGA API automates retrieving database statistics available only through the RMU Show Statistics command. The SGA API provides the only way to retrieve statistics for Oracle Rdb databases from an application. Using the SGA API provides fast access to the data without effecting the execution of the server. In addition, the information in the database global areas is protected from corruption by the user.______________________ 1.2 Supported Oracle Rdb Releases The SGA API supports Oracle Rdb Releases 6.0, 6.1, 7.0 and_7.1.___________________ 1.3 Sample Program Refer to the $$$RDBSGA_API.README file included with the software kit for information about the RDBSGA_ SAMPLE.C program. The sample program provides a working example of how to code the API. Information about compiling, linking, and running the program are included in the README file. 1 ___________________________ 1.4 Files for the SGAAPI The SGAAPI files are supplied by the Rdb installation procedure. Primarily they are stored in the RDM$DEMO directory though the KUSRMUSHRxx image is located in SYS$COMMON:[SYSLIB] (which is SYS$LIBRARY). Table_1__SGAAPI_Files__________________________________ Location_______File_Name______Description______________ RDM$DEMO KUSAPI.H Header file containing interfaces to API entry points. KUSRMUAPI.H Primary header file for Rdb V70 implementation of the API. This is the only file you need to include in your source code. KUSRMUSHRxx.OPTOptions file for linking your programs. RDBSGA_ Sample file showing how SAMPLE.C to use the API. KUSTAGS.H Header file containing tag values passed to the API. RMUST_ Rdb7 specific header file RTPMS.H containing the RTPMS_t data structure returned from a request for RMUST_ CT_RTPMS_STATS data. Also contains the FIOVEC_t structure returned from a RMUST_CT_ARPMS_STATS request. ORATYPES.H Standard data types. 2 Table_1_(Cont.)__SGAAPI_Files__________________________ Location_______File_Name______Description______________ SGAAPI.PS, Documentation for the SGAAPI.TXT, API. SGAAPI.HTML SYS$LIBRARY KUSRMUSHRxx.EXEVMS shareable image containing API ______________________________implementation.__________ 3 _______________________________________________________ 1 Programming with the SGA API __________________________________________________________________ 1.1 SGA_API_Design_____________ 1.1.1 Program Routines Table 1 shows a list of routines supplied by the SGA API. Table_1-1__SGA_API_Routines____________________________ Routine____________Purpose_____________________________ kuscx_allocate Allocate continuation context kuscx_free_handle Free continuation context kuscx_init Initialize continuation context kusdb_allocate Allocate resources for a database handle kusdb_connect Connect to a database kusdb_disconnect Disconnect from a database kusdb_error_text Format an error message kusdb_free Free resources for a database handle kusdb_get_info Collect statistics for the database kustv_allocate_ Allocate and initialize resource handle for a TLV handle kustv_dump Diagnostic dump routine for debugging purposes kustv_free_handle Free resources for a TLV handle kustv_get Retrieve next TLV from buffer 1-1 Programming with the SGA API Table_1-1_(Cont.)__SGA_API_Routines____________________ Routine____________Purpose_____________________________ kustv_offset Return current offset of read/write pointer kustv_put Insert a TLV triplet into buffer kustv_reinit_ Reset offset for TLV handle handle kustvp1_put_one_ Insert a TLV with associated byte byte passed by value kustvp2_put_two_ Insert a TLV with associated 2 bytes bytes passed by value kustvp4_put_four_ Insert a TLV with associated 4 bytes bytes passed by value kustvptg_put_tag Insert a TLV consisting of tag only ___________________(0_length)__________________________ ___________________________ 1.1.2 Program Flow The following table describes the order in which a program typically calls the SGA API functions: Table_1-2__Program_Flow________________________________ StepTask___________________API_Routine_________________ 1 Connect to the kusdb_connect database 2 Build a tag length kustvptg_put_tag or value (TLV) buffer, kustvp4_put_four_bytes indicating the statistics you want to retrieve and allocate the input TLV handle 1-2 Programming with the SGA API Table_1-2_(Cont.)__Program_Flow________________________ StepTask___________________API_Routine_________________ 3 Allocate the kuscx_allocate "wildcard context" (use this when the buffer might be too small for the data) 4 Gather the requested kusdb_get_info statistics 5 Initialize context kustv_allocate_handle or for reading the TLV kustv_reinit_handle buffer 6 Loop-over call to get kustv_get next TLV entry in the TLV buffer 7 Program flow kusdb_get_info kustvptg_ continues as follows: put_tag kusdb_disconnect o If the TLV buffer continues, program processing returns to step 4 to read the next buffer full of data o If the TLV buffer does not continue, the program either: o Returns to step 2 to build a new request o Disconnects _______________________________________________________ 1-3 Programming with the SGA API ___________________________ 1.1.3 Sample Program You can get a feel for how to code against the API by looking at RDBSGA_SAMPLE.C in the RDM$DEMO directory. _____________________ 1.1.3.1 Compiling and linking the sample program When writing your own application, include kusrmuapi.h in any modules which use the API. To compile rdbsga_sample.c use a command similar to: $ CC/DECC/INCLUDE=(RDM$DEMO) RDBSGA_SAMPLE.C To link the rdbsga_sample program, use a command similar to: LINK RDBSGA_ SAMPLE,RDM$DEMO:KUSRMUSHRxx.OPT/OPTIONS _____________________ 1.1.3.2 Running the sample program The sample program must be run as a foreign command. This is some example output from RDBSGA_SAMPLE when run against the MF_PERSONNEL.RDB sample database: 1-4 Programming with the SGA API $ rdbsga_sample == "$mydisk:[mydir]rdbsga_sample.exe $ rdbsga_sample MF_PERSONNEL.RDB ============================================================== = = = Class RMUST_CT_DBINFO = = = ============================================================== ----- Beginning of group ----- Max user count: 50 Creation date: 25-OCT-1995 16:24:19.69 ----- End of group ----- * Buffer ended normally * ============================================================== = = = Class RMUST_CT_ARPMS = = = ============================================================== ----- Beginning of group ----- Storage area ID: 4 ARPMS file I/O syread 0 ----- End of group ----- * Buffer ended normally * ============================================================== = = = Class RMUST_CT_RTPMS = = = ============================================================== ----- Beginning of group ----- RTPMS stats root reads: 23 ----- End of group ----- * Buffer ended normally * . . . 1-5 Programming with the SGA API ___________________________ 1.1.4 Database Context A database handle is used to maintain context information for the database being examined. All routine names that begin with kusdb require a database handle as one of their arguments. The kusdb_allocate routine is used to allocate resources and initialize the handle so that it can be used by other routines. Typically, kusdb_connect is called to connect to a database. Once a handle has been used to successfully connect to a database, kusdb_get_info can be called to retrieve information from the database. When no more data is needed for the database, kusdb_disconnect can be called to disconnect from the database. When the handle is no longer needed, kusdb_free is called to free resources used by the handle. If kusdb_connect, kusdb_get_info or kusdb_disconnect ever return an error, then kusdb_error_text can be called to retrieve a text message associated with the error as well as any_additional_messages_associated with the error. 1.1.5 Information and Result Buffer Formats The most important structures used to communicate between the API and the caller of the API are two buffers that are called the information buffer and the result buffer. They are both structured as series of tag-length-value (TLV) entries. The tag and length are both unsigned words, ub2 (see the section titled Compiling and Linking on page 10 for more information on data types and header files). The length indicates the size, in bytes, of the value portion of the triplet. In many cases, a TLV entry will have a length of zero. For example, TLV entries in an information buffer usually have a length of 0. 1-6 Programming with the SGA API _____________________ 1.1.5.1 Information Buffer The information buffer is a buffer that is created and initialized by the code calling the API. This buffer contains TLVs that describe the information to be returned. Along with identifying fields to be returned, it also can specify how much data to return (for example, one TLV can specify that information for one process is to be returned while another TLV can specify that information for all active processes is to be returned). The syntax of the information buffer is shown below: ::= ... ::= [] ::= ::= ub2, see below ::= ub2, see below ::= ub2 ::= byte buffer of size "length" ::= KUSGTBEND The class TLV is used to indicate the type of fields that will be requested in subsequent item TLVs in this information buffer. In general terms, the class TLV specifies the underlying data structure that contains the data to be retrieved and the entries for each item TLV indicate a field to be returned from the underlying table. No value is specified for an item TLV in the information buffer (that is, the length field is zero). If data from different classes are desired, then separate information buffers will have to be created and separate calls will have be made for each class. The documentation for each of the classes describe in more detail the format of the information buffer for that class. 1-7 Programming with the SGA API Most classes have multiple rows of information. The class TLV for these classes have an optional value which is a key value that identifies a subset of rows (usually only one row) in the class. If this value is specified, then only the data for the specified row are returned. If no value is specified (the length field is 0), then all rows for the class are returned. The example below shows an information buffer requesting the username and Oracle Rdb process ID of all Rdb7 processes. It is followed by an example of an information buffer requesting information for the Oracle Rdb process with PID 20. Note that TLV buffers usually contain data of different types, and therefore, the TLV maintenance functions should be used to create and read the buffers. In this case, all data is of the same type, so an array is created to contain the data. /* information buffer to return Oracle Rdb process ID and user name for all Oracle Rdb processes attached to an Rdb database */ ub2 proc_info[] = { RMUST_CT_PROCESS, 0, RMUST_T_PID, 0, RMUST_T_USERNAME, 0, KUSGTBEND, 0}; /* information buffer to return user name for Rdb process with PID 20 */ ub2 proc_20_info[] = ( RMUST_CT_PROCESS, 4, 20, RMUST_T_USERNAME, 0, KUSGTBEND, 0}; 1-8 Programming with the SGA API The valid classes and tags for Oracle Rdb databases are listed in the section titled Class and Item Tags for Oracle Rdb Databases on page 11. ___________________________ 1.1.6 Result Buffer The result buffer is a buffer allocated by the caller but filled in by the API with the data items specified by the information buffer. If the information buffer requests multiple rows of the same data (for example, return information for all active processes using the database), then all data for the first process is stored followed by data for the second process, and so on until all data for all processes have been stored. Tags are not guaranteed to appear in the result buffer in the same order they were specified in the information buffer. Specific information about the format of the result buffer for each possible class is documented as part of the class description. The syntax for the result buffer is shown below: ::= ... ::= KUSGTBOG 0 ... [[] | KUSGTEOG 0] ::= [] ::= two unsigned bytes ::= two unsigned bytes ::= byte buffer of size "length" ::= {KUSGTTRN 0 | KUSGTBCON 0} ::= { KUSGTBEND 0 | } The KUSGTBOG and KUSGTEOG tags are used to mark the beginning and end of a group of related data. Another way of looking at KUSGTBOG and KUSGTEOG is to view them as delimiting rows of data. For example, if an information buffer requested the user name, terminal name and PID of every Oracle process, then the result buffer would contain KUSGTBOG and KUSGTEOG tags around 1-9 Programming with the SGA API the set of fields for each Oracle process. Note that the KUSGTBOG and KUSGTEOG are used even if only one group of related fields is returned. An example of an output buffer with two 'rows' of data is shown below. KUSGTBOG, 0, /* start of 1st row */ RMUST_CT_USERNAME, 10, "RDB_USER_1", RMUST_CT_IMAGENAME, 7, "SQL.EXE", RMUST_CT_PID, 4, 20, KUSGTEOG, 0, /* end of 1st row */ KUSGTBOG, 0, /* start of 2nd row */ RMUST_CT_USERNAME, 10, "RDB_USER_2", RMUST_CT_IMAGENAME, 7, "SQL.EXE", RMUST_CT_PID, 4, 12, KUSGTEOG, 0, /* end of 2nd row */ KUSGTBEND, 0 /* end of buffer */ If a buffer is too small for the amount of data to be returned, the end of the buffer will containing the KUSGTBCNT or KUSGTBTRN TLVs. KUSGTBCNT is used when the user specified a continuation context in the call to kusdb_get_info and the remaining data can be returned in a subsequent call (see the following section titled Continuation Context for more information.) If no continuation context was specified by the caller and the data does not fit into the buffer, then KUSGTBTRN TLV is returned. If all requested data fits in the buffer, then KUSGTBEND is returned. Note that KUSTVBTRN and KUSTVBCONT can occur in the middle of a group of fields. ___________________________ 1.1.7 Continuation Context Because the calling program cannot predict how much data will be returned by the API, the API provides a mechanism that allows the caller to make multiple calls to return information for one request. To enable this mechanism, the caller must first allocate a continuation context variable (with the kuscx_allocate function). Then, the continuation context variable is 1-10 Programming with the SGA API passed as an argument to the function that retrieves data (the kusdb_get_info function). When that function returns, the caller can determine if the buffer was too small by looking for the "continuation tag", KUSGTBCNT at the end of the result buffer. If the buffer was continued, then the caller can execute the call again to retrieve statistics (the kusdb_get_ info function) being sure to specify the continuation context variable. The caller continues to call kusdb_ get_info until a buffer is returned that is not continued. When this happens, the caller then frees the continuation context information by calling kuscx_ free_handle or reinitializes the continuation context information for reuse by calling kuscx_init. As an example, consider what might happen if the caller specified a 40 byte buffer when retrieving data for the example above and the caller used a continuation context variable. The first call to kusdb_get_info might return the following result buffer (note that contents of the buffers may vary due to different alignment rules for data alignment on different platforms and compilers): KUSGTBOG, 0, /* total 4 bytes */ RMUST_T_USERNAME, 13, "ORARDB_USER_1", /* total 21 bytes */ RMUST_T_IMAGENAME, 10, "MY_PRG.EXE", /* total 35 bytes */ KUSGTBCON, 0 /* total 39 bytes */ No more TLVs can be inserted after the KUST39_TERMINAL TLV because there is not enough space in the buffer. Instead, a KUSGTBCON TLV is written. Because a continuation context variable was passed in by the caller, the rest of the data can still be retrieved. If the caller passes a 40 byte buffer to kusdb_get_ info again, it would look like the following: RMUST_T_PID, 4, 20, /* total 8 bytes */ KUSGTEOG, 0, /* total 12 bytes */ KUSGTBOG, 0, /* total 16 bytes */ RMUST_T_USERNAME, 13, "ORARDB_USER_2", /* total 33 bytes */ KUSGTBCON 0 /* total 37 bytes */ 1-11 Programming with the SGA API Another call to kusdb_get_info with another 40 byte buffer would return the following: RMUST_T_IMAGENAME, 11, "MY_PRG2.EXE", /* total 15 bytes */ RMUST_T_PID, 4, 12, /* total 23 bytes */ KUSGTEOG, 0, /* total 27 bytes */ KUSGTBEND, 0 /* total 31 bytes */ KUSGTBEND indicates that all requested data has been returned. It is possible for a TLV entry to not fit inside of the empty TLV buffer passed in by the caller. If the caller had specified a buffer size of 10 in the above example, the TLV for the user name field (KUST32_ USERNAME) would not fit even if no other TLVs had been inserted into the buffer. If a TLV entry will not fit into a buffer and the buffer is empty, the KUSDB_GET_ INFO call will return status KUSSTBFSML. ___________________________ 1.1.8 Error Tags If an unsupported or invalid tag is encountered by the kusdb_get_info routine while reading the information buffer, then a special error tag will be returned in the result buffer. An error tag will also be returned if the value for a class tag does not identify any rows. A list of the special error tags and the circumstances under which they are returned is listed in Table 2: Error Tags. 1-12 Programming with the SGA API Table_1-3__Error_Tags__________________________________ tar________________returned_when...____________________ KUSGTBDTG this tag is not a known tag. The value for KUSGTBDTG is the unknown tag from the information buffer. Note that if an invalid class tag is specified. an error status is returned and the result buffer is empty. KUSGTUNST the tag is valid for this class, but not for the version of the connected database. The value of this tag is the unknown tag from the information buffer KUSGTNP the tag is not supported on the ___________________requested_platform._________________ ___________________________ 1.1.9 General tags The SGA API defines a number of tags which are used in result buffers. These tags are described in Table 3: General Tags. The use of these tags has been discussed in previous sections. Table_1-4__General_Tags________________________________ tag_code___________meaning_____________________________ KUSGTBEND Indicates the end of both the request and result buffer. KUSGTBTRN Indicates that the result buffer was not large enough to contain the result. All information in the result buffer is valid, but one or more requested items is missing. 1-13 Programming with the SGA API Table_1-4_(Cont.)__General_Tags________________________ tag_code___________meaning_____________________________ KUSGTBOG Indicates the beginning of a set of related data items. Used with KUSGTEOG to delimit rows of data for classes that return multiple rows. KUSGTEOG Indicates the end of a set of related data items. KUSGTBOG is used to indicate the beginning of the set. KUSGTBCON Indicates that the result buffer contains a partial result. This tag can be returned only when a continuation context handle was specified in the kusdb_get_info ___________________call._______________________________ ___________________________ 1.1.10 Compiling and Linking For Oracle Rdb databases, a version varianted shareable image is generated for Version 6.0 through Version 7.1. The SGA API calls and API specific types are described in kusapi.h while the more generic types are described in oratypes.h. __________________________________________________________________ 1.2 Class and Item Tags for Oracle Rdb Databases The valid class tags for Oracle Rdb classes and a description of the class are listed in Table 4: Classes for Oracle Rdb Databases. The table is followed by a description of the item tags that are valid for each class name. 1-14 Programming with the SGA API Table_1-5__Classes_for_Oracle_Rdb_Databases____________ Class_Name_________Description_________________________ RMUST_CT_AIJINFO General information on the state of the after-image journal subsystem RMUST_CT_AIJJNL Information on individual after image journals RMUST_CT_DBINFO General database information such as number of buffers, max number of users, database flags, etc. RMUST_CT_DBR Information on database recovery processes RMUST_CT_FILE Storage area file information; i.e. names, number of pages, blocks per page, etc. RMUST_CT_FILE_ Storage area info, duplicate data NODUP removed for subsequent requests for info. RMUST_CT_PROCESS Information on database user processes RMU_CT_STALL_ACT Stall message information RMUST_CT_STALL RMUST_CT_ARPMS_ Storage area statistics STATS RMUST_CT_RTPMS_ Run time statistics for users. STATS__________________________________________________ ___________________________ 1.2.1 Time and Date Tags (Oracle Rdb only) There are four suffixes for certain time and date item tags for Oracle Rdb. The suffix indicates the format to be returned for the date and time field. The suffixes and their descriptions are listed in Table 5: Date and Time Return Value Types. 1-15 Programming with the SGA API Table_1-6__Date_and_Time_Return_Value_Types____________ Suffix_____________Meaning_____________________________ ADT Operating system specific binary date and time format. FDT Formatted Date and Time. The time and date are formatted into an ASCII result buffer in YYYYNNDDHHMMSSGG format as described in Table 6. RT Relative Time. The time is specified in 1/100 second increments specified in an unsigned longword. The relative time is used as both an information and result buffer tag. TDT Text Date and Time. Returns the date and time in an operating system specific form which can be used for display. TT Text Time. Returns the time component of the time and date stamp in an operating system specific form which can be used ___________________for_display.________________________ Descriptions of the date and time field components used in Table 5 are listed in Table 6. Table_1-7__Formatted_Date_and_Time_Fields______________ String_____________Meaning_____________________________ YYYY Four digits of the year, between 1857 and 9999 1-16 Programming with the SGA API Table_1-7_(Cont.)__Formatted_Date_and_Time_Fields______ String_____________Meaning_____________________________ NN Two digits of month, including leading zero for months between January through September. Valid range is 01 - 12 DD Two digits for day of month, 01 through 31, right-justified and zero-filled HH Two digits for hour of day, 00 through 23, right-justified and zero-filled MM Two digits for minute of hour, 00 through 59, right-justified and zero-filled SS Two digits for second of minute, 00 through 59, right-justified and zero-filled GG Two digits for hundredths of second, 00 through 99, right- ___________________justified_and_zero-filled___________ __________________________________________________________________ 1.3 RMUST_CT_AIJINFO - AIJ Information The AIJ information class provides information on the after-image journaling subsystem. 1-17 Programming with the SGA API ___________________________ 1.3.1 Information Buffer Syntax ::= RMUST_CT_AIJINFO 0 ... KUSGTBEND ::= { RMUST_T_AIJ_AUTO_SYNC 0 | RMUST_T_AIJ_CUR_MSN 0 | RMUST_T_AIJ_DATA_SYNC 0 | RMUST_T_AIJ_ENABLED_FLG 0 | RMUST_T_AIJ_LEOF 0 | RMUST_T_AIJ_PEOF 0 | RMUST_T_AIJ_STALLED_MSN 0 | RMUST_T_AIJ_STATUS 0 | RMUST_T_AIJ_VNO 0 | RMUST_T_AUTO_BKUP_FLG 0 | RMUST_T_CACHE_FILENAME 0 | RMUST_T_CACHE_STATUS 0 | RMUST_T_CUR_ACTIVE_AIJ 0 | RMUST_T_CUR_BKUP_VNO 0 | RMUST_T_CUR_RCVR_VNO 0 | RMUST_T_DATA_CMIT_FLG 0 | RMUST_T_DB_BKUP_VNO 0 | RMUST_T_DEF_ALLOCATION 0 | RMUST_T_DEF_BKUP_FILENAME 0 | RMUST_T_DEF_EXTENSION 0 | RMUST_T_GOVERNOR_ENABLED 0 | RMUST_T_HARD_DATA_LOSS_FLG 0 | RMUST_T_JOURNAL_CNT 0 | RMUST_T_LCS_ACTIVE 0 | RMUST_T_LRS_ACTIVE 0 | RMUST_T_LRS_STATE 0 | RMUST_T_LSS_ACTIVE 0 | RMUST_T_LSS_AIJ_VBN 0 | RMUST_T_LSS_AIJ_VNO 0 | RMUST_T_LSS_LAG_FDT 0 | RMUST_T_LSS_REF_COUNT 0 | RMUST_T_LSS_STATE 0 | RMUST_T_NEW_VERSION_FLG 0 | RMUST_T_OPER_CLASS 0 1-18 Programming with the SGA API | RMUST_T_OVERWRITE_FLG 0 | RMUST_T_OVERWRITTEN_FLG 0 | RMUST_T_SHUTDOWN_TIME 0 | RMUST_T_STBY_RT_FILNAM 0 } ___________________________ 1.3.2 Result Buffer Syntax ::= KUSGTBOG KUSGTEOG ::= { RMUST_T_AIJ_AUTO_SYNC 4 | RMUST_T_AIJ_CUR_MSN 4 | RMUST_T_AIJ_DATA_SYNC 4 | RMUST_T_AIJ_ENABLED_FLG 4 | RMUST_T_AIJ_LEOF 4 | RMUST_T_AIJ_PEOF 4 | RMUST_T_AIJ_STALLED_MSN 4 | RMUST_T_AIJ_STATUS 4 | RMUST_T_AIJ_VNO 4 | RMUST_T_AUTO_BKUP_FLG 4 | RMUST_T_CACHE_FILENAME | RMUST_T_CACHE_STATUS 4 | RMUST_T_CUR_ACTIVE_AIJ 4 | RMUST_T_CUR_BKUP_VNO 4 | RMUST_T_CUR_RCVR_VNO 4 | RMUST_T_DATA_CMIT_FLG 4 | RMUST_T_DB_BKUP_VNO 4 | RMUST_T_DEF_ALLOCATION 4 | RMUST_T_DEF_BKUP_FILENAME | RMUST_T_DEF_EXTENSION 4 | RMUST_T_GOVERNOR_ENABLED 4 | RMUST_T_HARD_DATA_LOSS_FLG 4 | RMUST_T_JOURNAL_CNT 4 | RMUST_T_LCS_ACTIVE 4 | RMUST_T_LRS_ACTIVE 4 | RMUST_T_LRS_STATE 4 | RMUST_T_LSS_ACTIVE 4 | RMUST_T_LSS_AIJ_VBN 4 1-19 Programming with the SGA API | RMUST_T_LSS_AIJ_VNO 4 | RMUST_T_LSS_LAG_FDT | RMUST_T_LSS_REF_COUNT 4 | RMUST_T_LSS_STATE 4 | RMUST_T_NEW_VERSION_FLG 4 | RMUST_T_OPER_CLASS 4 | RMUST_T_OVERWRITE_FLG 4 | RMUST_T_OVERWRITTEN_FLG 4 | RMUST_T_SHUTDOWN_TIME 4 | RMUST_T_STBY_RT_FILNAM } ::= { RMUST_K_AIJ_NORMAL | RMUST_K_AIJ_ CORRUPT | RMUST_K_UNKNOWN} ::= { RMUST_K_SYNC_COLD | RMUST_K_SYNC_COMMIT | RMUST_K_SYNC_HOT | RMUST_K_SYNC_WARM | RMUST_K_UNKNOWN } ::= { RMUST_K_LRS_COMPLETION | RMUST_K_LRS_RESTART | RMUST_K_LRS_RESUMPTION | RMUST_K_LRS_SUSPENDED | RMUST_K_LRS_SYNC_REDO | RMUST_K_LSS_ACTIVATE | RMUST_K_LSS_CONNECT | RMUST_K_LSS_DB_BIND | RMUST_K_LSS_DB_UNBIND | RMUST_K_LSS_DB_SYNC | RMUST_K_LSS_INACTIVE | RMUST_K_LSS_NET_BIND | RMUST_K_LSS_NET_UNBIND | RMUST_K_LSS_RECOVERY | RMUST_K_LSS_REPLICATE | RMUST_K_LSS_SHUTDOWN } 1-20 Programming with the SGA API ___________________________ 1.3.3 Tag Descriptions Descriptions of the item tags for class RMUST_CT_ AIJINFO are shown in Table 7. Table_1-8__RMUST_CT_AIJINFO_Tags_______________________ Tar________________Meaning_____________________________ RMUST_T_AIJ_ If TRUE AIJ is enabled, FALSE ENABLED_FLG otherwise. RMUST_T_AIJ_AUTO_ Hot standby - database replication SYNC sync mode. RMUST_T_AIJ_CUR_ Hot standby - current message MSN sequence number. RMUST_T_AIJ_DATA_ Hot standby - database replication SYNC sync mode. RMUST_T_AIJ_LEOF Current AIJ logical EOF. RMUST_T_AIJ_PEOF Current AIJ physical EOF. RMUST_T_AIJ_SRV_ Hot Standby: name if replication NAME server connection RMUST_T_AIJ_ Hot standby - stalled message STALLED_MSN sequence number. RMUST_T_AIJ_ If not RMUST_T_AIJDB_NORMAL, then STATUS some process failed writing to the AIJ file; AIJ DATA LOSS HAS OCCURRED. Accordingly, ALL active processes will detach from the database, and DBR will not attempt to access the AIJ file. Also new BINDs will be prevented. This field can be cleared by disabling or modifying the AIJ file. RMUST_T_AIJ_VNO Current AIJ sequence number. RMUST_T_AUTO_ If TRUE backup is automatic, FALSE BKUP_FLG otherwise. 1-21 Programming with the SGA API Table_1-8_(Cont.)__RMUST_CT_AIJINFO_Tags_______________ Tar________________Meaning_____________________________ RMUST_T_CACHE_ This field contains the electronic FILENAME "non-volatile" after-image journal cache (ACE) filename (if any) associated with the database. RMUST_T_CACHE_ If not RMUST_K_ACE_NORMAL, some STATUS process has failed writing to the ACE. AIJ data loss has NOT occurred. RMUST_T_CUR_ current active AIJ journal index. ACTIVE_AIJ RMUST_T_CUR_BKUP_ AIJ current backup version number. VNO RMUST_T_CUR_RCVR_ AIJ current recovery version VNO number. RMUST_T_DATA_ If TRUE DB changes have been CMIT_FLG made when AIJ was disabled, FALSE otherwise. RMUST_T_DB_BKUP_ Full Database backup version VNO number. RMUST_T_DEF_ default AIJ allocation in blocks. ALLOCATION RMUST_T_DEF_BKUP_ This field contains the default FILENAME after-image journal backup filename (if any) associated with the database. RMUST_T_DEF_ default AIJ extension in blocks. EXTENSION RMUST_T_GOVERNOR_ Hot standby - TRUE if replication ENABLED governor enabled. RMUST_T_HARD_ If TRUE hard data loss resulted DATA_LOSS_FLG from a failover, FALSE otherwise. 1-22 Programming with the SGA API Table_1-8_(Cont.)__RMUST_CT_AIJINFO_Tags_______________ Tar________________Meaning_____________________________ RMUST_T_JOURNAL_ number of allocated AIJ File CNT Blocks. RMUST_T_LCS_ Hot standby - TRUE if AIJ log ACTIVE catch-up server started. RMUST_T_LRS_ Hot standby - TRUE if AIJ log roll- ACTIVE forward server started. RMUST_T_LRS_STATE Hot standby - LRS state. Refer to Table 9 for valid return values. RMUST_T_LSS_ Hot standby - TRUE if AIJ log ship ACTIVE server started. RMUST_T_LSS_AIJ_ Hot standby - Master/standby AIJ VBN VBN. RMUST_T_LSS_AIJ_ Hot standby - Master/standby AIJ VNO VNO. RMUST_T_LSS_LAG_ Hot standby - Master/standby lag FDT time. RMUST_T_LSS_REF_ Hot standby - Master/standby # of COUNT LSS participants. RMUST_T_LSS_STATE Hot standby - LSS state. Refer to Table 9 for valid return values. RMUST_T_NEW_ If TRUE backup creates a new VERSION_FLG journal version, FALSE otherwise. RMUST_T_OPER_ OpenVMS operator notification CLASS classes. Refer to Table 8: AIJ Operator Notification Tags for valid values RMUST_T_ If TRUE journals are overwritten on OVERWRITE_FLG wraparound, FALSE otherwise. RMUST_T_ If TRUE one or more journals have OVERWRITTEN_ been overwritten, FALSE otherwise. FLG 1-23 Programming with the SGA API Table_1-8_(Cont.)__RMUST_CT_AIJINFO_Tags_______________ Tar________________Meaning_____________________________ RMUST_T_SHUTDOWN_ Time (minutes) to database TIME shutdown after the AIJ subsystem becomes stalled. i.e. all journals consumed. RMUST_T_STBY_RT Live or standby database filename. FILNAM_________________________________________________ The valid values for tag RMUST_T_OPER_CLASS are shown in Table 8. Table_1-9__AIJ_Operator_Notification_Tags______________ Tag____________Value______Meaning______________________ RMUST_K_AIJ_ 0 No operator class activated. OPR_DISABLED RMUST_K_AIJ_ 1 Central operator. OPR_CENTRAL RMUST_K_AIJ_ 8 Disk operator. OPR_DISKS RMUST_K_AIJ_ 128 Cluster operator. OPR_CLUSTER RMUST_K_AIJ_ 256 Security operator. OPR_SECURITY RMUST_K_AIJ_ 4096 User operator #1. OPR_OPER1 RMUST_K_AIJ_ 8192 User operator #2. OPR_OPER2 RMUST_K_AIJ_ 16384 User operator #3. OPR_OPER3 RMUST_K_AIJ_ 32768 User operator #4. OPR_OPER4 1-24 Programming with the SGA API Table_1-9_(Cont.)__AIJ_Operator_Notification_Tags______ Tag____________Value______Meaning______________________ RMUST_K_AIJ_ 65536 User operator #5. OPR_OPER5 RMUST_K_AIJ_ 131072 User operator #6. OPR_OPER6 RMUST_K_AIJ_ 262144 User operator #7. OPR_OPER7 RMUST_K_AIJ_ 524288 User operator #8. OPR_OPER8 RMUST_K_AIJ_ 1048576 User operator #9. OPR_OPER9 RMUST_K_AIJ_ 2097152 User operator #10. OPR_OPER10 RMUST_K_AIJ_ 4194304 User operator #11. OPR_OPER11 RMUST_K_AIJ_ 8388608 User operator #12. OPR_OPER12_____________________________________________ The valid values for tag RMUST_T_LRS_STATUS, RMUST_T_ LSS_STATUS are shown in Table 9. Table_1-10__Status_values_for_hot_standby_log_servers__ Tag________________Meaning_____________________________ RMUST_K_LRS_ Replication completion. COMPLETION RMUST_K_LRS_ Replication restart activity. RESTART RMUST_K_LRS_ Replication resumed (catch-up). RESUMPTION RMUST_K_LRS_ Replication suspended. SUSPENDED 1-25 Programming with the SGA API Table 1-10 (Cont.) Status values for hot standby log ____________________servers____________________________ Tag________________Meaning_____________________________ RMUST_K_LRS_SYNC_ LRS synchronization redo REDO completion. RMUST_K_LSS_ LSS server activation. ACTIVATE RMUST_K_LSS_ Waiting for LCS to connect. CONNECT RMUST_K_LSS_DB_ Binding to database. BIND RMUST_K_LSS_DB_ Unbinding from database. UNBIND RMUST_K_LSS_DB_ Database synchronization. SYNC RMUST_K_LSS_ Inactive (server not running). INACTIVE RMUST_K_LSS_NET_ Binding to network. BIND RMUST_K_LSS_NET_ Unbinding from network. UNBIND RMUST_K_LSS_ Recovering from failure. RECOVERY RMUST_K_LSS_ Database replication. REPLICATE RMUST_K_LSS_ Replication cleanup. SHUTDOWN_______________________________________________ ___________________________ 1.3.4 Version specific tags 1-26 Programming with the SGA API Table 1-11 Lowest version of Oracle Rdb required for ____________tag_support________________________________ Tag________________Version_of_Oracle_Rdb_required______ RMUST_T_AIJ_AUTO_ 7.0 SYNC RMUST_T_AIJ_DATA_ 7.0 SYNC RMUST_T_AIJ_CUR_ 7.0 MSN RMUST_T_AIJ_DATA_ 7.0 SYNC RMUST_T_AIJ_SRV_ 7.0 NAME RMUST_T_AIJ_ 7.0 STALLED_MSN RMUST_T_GOVERNOR_ 7.0 ENABLED RMUST_T_LCS_ 7.0 ACTIVE RMUST_T_LRS_ 7.0 ACTIVE RMUST_T_LRS_STATE 7.0 RMUST_T_LSS_ 7.0 ACTIVE RMUST_T_LSS_AIJ_ 7.0 VBN RMUST_T_LSS_AIJ_ 7.0 VNO RMUST_T_LSS_LAG_ 7.0 FDT RMUST_T_LSS_REF_ 7.0 COUNT RMUST_T_LSS_STATE 7.0 1-27 Programming with the SGA API Table 1-11 (Cont.) Lowest version of Oracle Rdb ____________________required_for_tag_support___________ Tag________________Version_of_Oracle_Rdb_required______ RMUST_T_STBY_RT_ 7.0 FILNAM RMUST_T_AIJ_VNO 6.1 RMUST_T_CACHE_ 6.1 STATUS_________________________________________________ __________________________________________________________________ 1.4 RMUST_CT_AIJJNLS - AIJ Journal Class The AIJ journal class provides information about after-image journal instances. This class has multiple rows. All rows will be returned if a length of 0 is specified for the TLV entry containing the class tag. A single row can be retrieved by specifying the AIJFB index for the AIJ journal file of interest as the value of the TLV entry for the class tag. ___________________________ 1.4.1 Information Buffer Syntax ::= RMUST_CT_AIJJNLS{0 | {4, }} ... KUSGTBEND ::= { RMUST_T_ACTIVE_FLG 0 | RMUST_T_AIJFB_INDEX 0 | RMUST_T_ALLOCATION 0 | RMUST_T_BACKUP_DATE_ADT 0 | RMUST_T_BACKUP_DATE_FDT 0 | RMUST_T_BACKUP_DATE_TDT 0 | RMUST_T_BKUP_ACTIVE_FLG 0 | RMUST_T_BKUP_VNO 0 | RMUST_T_CUR_AIJ_FILENAME 0 | RMUST_T_CUR_BKUP_FILENAME 0 | RMUST_T_DEF_AIJ_FILENAME 0 | RMUST_T_EXTENSION 0 | RMUST_T_HARD_DATA_LOSS_FLG 0 | RMUST_T_INIT_ACTIVE_FLG 0 | RMUST_T_JOURNAL_NAME 0 | RMUST_T_JOURNAL_STATUS 0 | RMUST_T_LAST_BKUP_VNO 0 | RMUST_T_MODIFIED_FLG 0 | RMUST_T_NEW_VERSION_FLG 0 | RMUST_T_OVERWRITTEN_FLG 0 | RMUST_T_RESTORED_FLG 0 | RMUST_T_SOFT_DATA_LOSS_FLG 0 } Result Buffer Syntax 1-29 Programming with the SGA API ::= {KUSGTBOG ... KUSGTEOG } ... ::= { RMUST_T_ACTIVE_FLG 4 | RMUST_T_AIJFB_INDEX 4 | RMUST_T_ALLOCATION 4 | RMUST_T_BACKUP_DATE_ADT 8 | RMUST_T_BACKUP_DATE_FDT | RMUST_T_BACKUP_DATE_TDT | RMUST_T_BKUP_ACTIVE_FLG 4 | RMUST_T_BKUP_VNO 4 | RMUST_T_CUR_AIJ_FILENAME | RMUST_T_CUR_BKUP_FILENAME | RMUST_T_DEF_AIJ_FILENAME | RMUST_T_EXTENSION 4 | RMUST_T_HARD_DATA_LOSS_FLG 4 | RMUST_T_INIT_ACTIVE_FLG 4 | RMUST_T_JOURNAL_NAME | RMUST_T_JOURNAL_STATUS 4 | RMUST_T_LAST_BKUP_VNO 4 | RMUST_T_MODIFIED_FLG 4 | RMUST_T_NEW_VERSION_FLG 4 | RMUST_T_OVERWRITTEN_FLG 4 | RMUST_T_RESTORED_FLG 4 | RMUST_T_SOFT_DATA_LOSS_FLG 4 } ::= { RMUST_K_JNL_NORMAL | RMUST_K_JNL_FILACCERR | RMUST_K_JNL_CORRUPT | RMUST_K_JNL_EMPTY | RMUST_K_JNL_OPCODE | RMUST_K_JNL_FULL | RMUST_K_JNL_DISABLED | RMUST_K_JNL_NOT_EMPTY | RMUST_K_JNL_DBR | RMUST_K_UNKNOWN } 1-30 Programming with the SGA API ___________________________ 1.4.2 Tag Descriptions Descriptions of the valid item tags for the RMUST_ CT_AIJJNL class are shown in Table 11: AIJ File Information Tags. Table_1-12__AIJ_File_Information_Tags__________________ Tag________________Meaning_____________________________ RMUST_T_ACTIVE_ AIJ file block has been assigned. FLG RMUST_T_AIJFB_ Unique 0-based integer index to INDEX identify each journal file RMUST_T_ AIJ journal allocation in blocks. ALLOCATION RMUST_T_BACKUP_ TAD of last AIJ backup. (ADT DATE_ADT Format) RMUST_T_BACKUP_ TAD of last AIJ backup. (FDT DATE_FDT Format) RMUST_T_BACKUP_ TAD of last AIJ backup. (TDT TIME_TDT Format) RMUST_T_BKUP_ AIJ Backup in-progress. DATE_FLG RMUST_T_BKUP_VNO AIJ current backup version number. RMUST_T_CUR_AIJ_ Name of after-image journal file FILENAME for database. RMUST_T_CUR_BKUP_ This field contains the resultant FILENAME filename of the after-image journal backup file (if any) associated with this journal entry. RMUST_T_DEF_AIJ_ This field contains the default FILENAME after-image journal filename associated with this journal entry. RMUST_T_EXTENSION journal extension in blocks. AIJ 1-31 Programming with the SGA API Table_1-12_(Cont.)__AIJ_File_Information_Tags__________ Tag________________Meaning_____________________________ RMUST_T_HARD_ Hard data loss resulted from DATA_LOSS_FLG failover. RMUST_T_INIT_ AIJ Initialization in-progress. ACTIVE_FLG RMUST_T_JOURNAL_ This field contains the symbolic NAME name of the after-image journal file (if any) associated with the database. RMUST_T_JOURNAL_ Refer to Table 12, AIJ File State STATUS Tags for valid values RMUST_T_LAST_ Last version number backed up. BKUP_VNO RMUST_T_MODIFIED_ AIJ file needs to be backed up. FLG RMUST_T_NEW_ Backup creates new journal version. VERSION_FLG RMUST_T_ Journal has been overwritten. OVERWRITTEN_ FLG RMUST_T_RESTORED_ restored from existing file. FLG AIJFB RMUST_T_SOFT_ Soft data loss resulted from DATA_LOSS_FLG______failover.___________________________ Table_1-13__AIJ_File_State_Tags________________________ Tag________________Meaning_____________________________ RMUST_K_JNL_ Journal file is corrupt. CORRUPT RMUST_K_JNL_ invoked during suspended DBRDBR switchover. 1-32 Programming with the SGA API Table_1-13_(Cont.)__AIJ_File_State_Tags________________ Tag________________Meaning_____________________________ RMUST_K_JNL_ Journal entry has been disabled. DISABLED RMUST_K_JNL_EMPTY Journal file is empty. RMUST_K_JNL_ Journal has been possibly deleted FILACCERR or moved. RMUST_K_JNL_FULL Journal file is full. RMUST_K_JNL_ Journal status is normal. NORMAL RMUST_K_JNL_NOT_ Journal file contains transaction EMPTY data. RMUST_K_JNL_ Journal contains unknown opcode. OPCODE_________________________________________________ __________________________________________________________________ 1.5 RMUST_CT_ARPMS_STATS - Area Performance Statistics The RMUST_CT_ARPMS_STATS class is used to return run- time statistics maintained by Oracle Rdb for databases on a particular node. This request can be used to return the statistics buffer maintained for each storage area. ___________________________ 1.5.1 Buffer Syntax arpms_stats_request ::= RMUST_CT_ARPMS {0 | {4, }} KUSGTBEND ::= { RMUST_T_ARPMS 0 | RMUST_T_DBID 0 } 1-33 Programming with the SGA API ___________________________ 1.5.2 Result Buffer Syntax arpms_stats_response ::= ... ::= { KUSGTBEND | KUSGTBTRN | KUSGTBCON } ::= {KUSGTBOG ... KUSGTEOG}... ::= { RMUST_T_DBID 4 | RMUST_T_ARPMS } ::= 16 longwords ::= Pointer to an FIOVEC_t structure for the area. ___________________________ 1.5.3 Tag Descriptions Table_1-14__RMUST_CT_STATS_Tags________________________ Tag_Code___________Meaning_____________________________ RMUST_T_ARPMS Storage area performance measurement statistics returned in FIOVEC_t structure. Look in RMUST_RTPMS.H for a declaration of the structure. RMUST_T_DBID_______Storage_area_ID_____________________ __________________________________________________________________ 1.6 RMUST_CT_DBINFO - Database Information The database information class provides access to data stored in the KODA root (KROOT) structure. 1-34 Programming with the SGA API ___________________________ 1.6.1 Information Buffer Syntax ::= RMUST_CT_DBINFO 0 ... KUSGTBEND ::= { RMUST_T_AIJ_COMMIT_FLG 0 | RMUST_T_AIJ_SHUTDOWN 0 | RMUST_T_ALARM_ENABLED_FLG 0 | RMUST_T_ALS_ACTIVE 0 | RMUST_T_ALS_MODE_FLG 0 | RMUST_T_AUDIT_ENABLED_FLG 0 | RMUST_T_AUDIT_FIRST_FLG 0 | RMUST_T_AUDIT_FLUSH_FLG 0 | RMUST_T_BACKUP_DATE_ADT 0 | RMUST_T_BACKUP_DATE_FDT 0 | RMUST_T_BACKUP_DATE_TDT 0 | RMUST_T_BUF_BLOCK_CNT 0 | RMUST_T_CKPT_BLOCKS 0 | RMUST_T_CKPT_TIME 0 | RMUST_T_CREATE_DATE_ADT 0 | RMUST_T_CREATE_DATE_FDT 0 | RMUST_T_CREATE_DATE_TDT 0 | RMUST_T_DBR_BUF_CNT 0 | RMUST_T_DEF_BUF_CNT 0 | RMUST_T_DEFERRED_SNAP_FLG 0 | RMUST_T_DELTA_HSEC 0 | RMUST_T_FAST_COMMIT_FLG 0 | RMUST_T_FILID_CNT 0 | RMUST_T_FULL_BACKUP_TSN 0 | RMUST_T_GB_CNT 0 | RMUST_T_GB_ENABLED_FLG 0 | RMUST_T_LCKOPT_ENABLED_FLG 0 | RMUST_T_LOCK_TIMEOUT 0 | RMUST_T_MAX_GB_PER_USER 0 | RMUST_T_MAX_NODE_CNT 0 | RMUST_T_MAX_USER_CNT 0 | RMUST_T_OPEN_MODE_FLG 0 | RMUST_T_PLATFORM 0 | RMUST_T_SFDB_FLG 0 1-35 Programming with the SGA API | RMUST_T_STATS_ENABLED_FLG 0 | RMUST_T_TSN_INTERVAL 0 } ___________________________ 1.6.2 Result Buffer Syntax ::= KUSGTBOG ... KUSGTEOG ::= { RMUST_T_AIJ_COMMIT_FLG 4 | RMUST_T_AIJ_SHUTDOWN 4 | RMUST_T_ALARM_ENABLED_FLG 4 | RMUST_T_ALS_ACTIVE 4 | RMUST_T_ALS_MODE_FLG 4 | RMUST_T_AUDIT_ENABLED_FLG 4 | RMUST_T_AUDIT_FIRST_FLG 4 | RMUST_T_AUDIT_FLUSH_FLG 4 | RMUST_T_BACKUP_DATE_ADT 8 | RMUST_T_BACKUP_DATE_FDT | RMUST_T_BUF_BLOCK_CNT | RMUST_T_CKPT_BLOCKS 4 | RMUST_T_CKPT_TIME 4 | RMUST_T_CREATE_DATE_ADT 8 | RMUST_T_CREATE_DATE_FDT | RMUST_T_CREATE_DATE_TDT | RMUST_T_DBR_BUF_CNT 4 | RMUST_T_DEF_BUF_CNT 4 | RMUST_T_DEFERRED_SNAP_FLG 4 | RMUST_T_DELTA_HSEC 4 | RMUST_T_FAST_COMMIT_FLG 4 | RMUST_T_FILID_CNT 4 | RMUST_T_FULL_BACKUP_TSN 4 | RMUST_T_GB_CNT 4 | RMUST_T_GB_ENABLED_FLG 4 | RMUST_T_LCKOPT_ENABLED_FLG 4 | RMUST_T_LOCK_TIMEOUT 4 | RMUST_T_MAX_GB_PER_USER 4 | RMUST_T_MAX_NODE_CNT 4 1-36 Programming with the SGA API | RMUST_T_MAX_USER_CNT 4 | RMUST_T_OPEN_MODE_FLG 4 | RMUST_T_PLATFORM 4 | RMUST_T_SFDB_FLG 4 | RMUST_T_STATS_ENABLED_FLG 4 | RMUST_T_TSN_INTERVAL 4 } ___________________________ 1.6.3 Tag Descriptions Descriptions of the valid item tags for the RMUST_CT_ DBINFO class are shown below. Table_1-15__RMUST_CT_DBINFO_Tags_______________________ Tag________________Meaning_____________________________ RMUST_T_AIJ_ If TRUE then Commit to Journal is COMMIT_FLG enabled for the database. FALSE otherwise. RMUST_T_AIJ_ Number of minutes until AIJ SHUTDOWN shutdown. RMUST_T_ALARM_ If TRUE then security alarms are ENABLED enabled for the database. FALSE otherwise. RMUST_T_ALS_ if AIJ log server started. ACTIVETRUE RMUST_T_ALS_MODE_ 0 = ALS mode is AUTOMATIC. 1 = ALS FLG mode is MANUAL. RMUST_T_AUDIT_ If TRUE then security auditing is ENABLED_FLG enabled for the database. FALSE otherwise. RMUST_T_AUDIT_ If TRUE then audits and/or alarms FIRST_FLG are generated only for the first access to a security object. If FALSE, all accesses to security objects generate audits or alarms. 1-37 Programming with the SGA API Table_1-15_(Cont.)__RMUST_CT_DBINFO_Tags_______________ Tag________________Meaning_____________________________ RMUST_T_AUDIT_ If TRUE then security audits are FLUSH_FLG flushed immediately to the security audit log file. RMUST_T_BACKUP_ TAD of last completed full backup. DATE_ADT RMUST_T_BACKUP_ Formatted Date/Time of last DATE_FDT completed full backup. RMUST_T_BACKUP_ Text Date/Time of last completed DATE_TDT full backup. RMUST_T_BUF_BLK_ Length in blocks of each page CNT buffer. RMUST_T_CKPT_ This field contains the number of BLOCKS blocks the AIJ file must increase in size before a user is forced to perform another checkpoint. RMUST_T_CKPT_TIME This field contains the number of seconds which pass before a user is forced to perform another checkpoint. RMUST_T_CREATE_ Time and date the database was DATE_ADT created. RMUST_T_CREATE_ Formatted time and date the DATE_FDT database was created. RMUST_T_CREATE_ Text time and date the database was DATE_TDT created. RMUST_T_DBR_BUF_ This field contains the default CNT number of page buffers to be allocated to each DBR process. 1-38 Programming with the SGA API Table_1-15_(Cont.)__RMUST_CT_DBINFO_Tags_______________ Tag________________Meaning_____________________________ RMUST_T_DEF_BUF_ This field contains the default CNT number of page buffers to be allocated to each bound user. This can be overridden by a logical name bind parameter. RMUST_T_DEFERRED_ If TRUE, then snapshots will SNAP_FLG only be written when necessary (a snapshot transaction is in progress). If FALSE, snapshots are always written. RMUST_T_DELTA_ Hundredths of seconds since start HSEC of statistics collection. RMUST_T_FAST_ _FLGIf TRUE then Fast Commit is COMMIT enabled for the database. FALSE otherwise. RMUST_T_FILID_CNT Number of storage area slots allocated. RMUST_T_FULL_ TSN of last completed full backup. BACKUP_TSN RMUST_T_GB_CNT number of global buffers per node. RMUST_T_GB_ If TRUE then global buffers are ENABLED_FLG enabled. If FALSE global buffers are disabled. RMUST_T_LCKOPT_ If TRUE then carry over lock ENABLED optimization is enabled. FALSE otherwise. RMUST_T_LOCK_ lock timeout interval in seconds. TIMEOUT RMUST_T_MAX_GB_ max # of allocate set blocks per PER_USER user. 1-39 Programming with the SGA API Table_1-15_(Cont.)__RMUST_CT_DBINFO_Tags_______________ Tag________________Meaning_____________________________ RMUST_T_MAX_NODE_ This field contains the maximum CNT number of nodes that can be bound to the database at one time. RMUST_T_MAX_USER_ This field contains the maximum CNT number of users that can be bound to the database (cluster wide) at one time. RMUST_T_OPEN_ 0 = Database Open mode is MODE_FLG AUTOMATIC. 1 = Open mode is MANUAL. RMUST_T_PLATFORM Current platform - RMUST_K_VMS or RMUST_K_OSF RMUST_T_SFDB If TRUE, this is an ORACLE RDB single-file database. If FALSE, this is an ORACLE RDB multi-file database. RMUST_T_STATS_ If TRUE then statistics are ENABLED_FLG maintained for the database. FALSE otherwise. RMUST_T_TSN_ AIJ commit optimization TSN INTERVAL___________interval.___________________________ __________________________________________________________________ 1.7 RMUST_CT_DBR - Database Recovery Process Information This class returns information regarding active database recovery processes. This class can return multiple rows. If information for all recovery processes is desired, then the TLV for the class tag should contain no value. If information for only one recovery process is desired, then the TLV for the class tag should contain the DBR index for the recovery process. 1-40 Programming with the SGA API ___________________________ 1.7.1 Information Buffer Syntax ::= RMUST_CT_DBR{0 | {4, }} ... KUSGTBEND ::= { RMUST_T_ASCII_STALL 0 | RMUST_T_DBR_ACTIVITY 0 | RMUST_T_DBR_INDEX 0 | RMUST_T_LKID 0 | RMUST_T_PID 0 | RMUST_T_VBN 0 } ___________________________ 1.7.2 Result Buffer Syntax ::= {KUSGTBOG ... KUSGTEOG}... ::= { RMUST_T_ASCII_STALL | RMUST_T_DBR_ACTIVITY 4 | RMUST_T_DBR_INDEX 4 | RMUST_T_LKID 4 | RMUST_T_PID 4 | RMUST_T_VBN 4 } 1-41 Programming with the SGA API ::= { | RMUST_K_DBR_AIJ_RCVR | RMUST_K_DBR_BIND | RMUST_K_DBR_FLUSH | RMUST_K_DBR_GB_RCVR | RMUST_K_DBR_INACTIVE | RMUST_K_DBR_OPT_CMT | RMUST_K_DBR_RDC_RELOAD | RMUST_K_DBR_REDO | RMUST_K_DBR_REFETCH | RMUST_K_DBR_SETUP | RMUST_K_DBR_TSN_UPDT | RMUST_K_DBR_UNBIND | RMUST_K_DBR_UNDO | RMUST_K_UNKNOWN} ::= process ID ::= lock ID ::= virtual block number ::= length, in bytes, of text ::= zero- based index into RTUPB table for this process ___________________________ 1.7.3 Tag Descriptions Description of the valid item tags for the RMUST_CT_ DBR class is shown in Table 15. Table_1-16__RMUST_CT_DBR_Tags__________________________ Tag_Code___________Meaning_____________________________ RMUST_T_ASCII_ Stall text. STALL RMUST_T_DBR_ Activity code associated with ACTIVITY DBR state. Refer to Table 16: DBR Activity Phase Tags for valid values. 1-42 Programming with the SGA API Table_1-16_(Cont.)__RMUST_CT_DBR_Tags__________________ Tag_Code___________Meaning_____________________________ RMUST_T_DBR_INDEX Index for this DBR process. RMUST_T_LKID Lock ID DBR is waiting on (0 if not blocked on lock). RMUST_T_PID Process ID of DBR process. RMUST_T_VBN Current Virtual Block Number (VBN) ___________________in_RUJ_file.________________________ An enumeration of the valid values for RMUST_T_DBR_ ACTIVITY is shown in Table 16. Note that not all values are returned for all versions of Oracle Rdb. Table_1-17__DBR_Activity_Phase_Tags____________________ Tag_Code___________Meaning_____________________________ RMUST_K_DBR_AIJ_ DBR is performing AIJ recovery. RCVR RMUST_K_DBR_BIND DBR is binding to database. RMUST_K_DBR_FLUSH DBR is performing buffer flush. RMUST_K_DBR_GB_ DBR is recovering global buffer RCVR context. RMUST_K_DBR_ DBR is initializing. INACTIVE RMUST_K_OPT_CMT DBR is scanning AIJ for optimistic commit. RMUST_K_RDC_ DBR is rebuilding the cache. RELOAD RMUST_K_DBR_REDO DBR is performing transaction REDO. RMUST_K_DBR_ DBR is refetching transferred REFETCH pages. RMUST_K_DBR_SETUP DBR is setting up for recovery. 1-43 Programming with the SGA API Table_1-17_(Cont.)__DBR_Activity_Phase_Tags____________ Tag_Code___________Meaning_____________________________ RMUST_K_DBR_TSN_ DBR is updating root structures. UPDT RMUST_K_DBR_ DBR is unbinding. UNBIND RMUST_K_DBR_UNDO is performing transaction UNDO. DBR____________________________________________________ __________________________________________________________________ 1.8 RMUST_CT_FILE - File Information The file information class provide data from the FILID block which contains attributes of storage area. This class can return multiple rows of data. If information about all storage areas is desired, then the length field in the TLV entry for this class should be zero. If information for a specific storage area is desired, then the value of the TLV for this class should be the DBID for that storage area. (DBIDs are returned by the RMUST_T_DBID tag.) ___________________________ 1.8.1 Information Buffer Syntax ::= RMUST_CT_FILE {0 | {4, }}... KUSGTBEND ::= { RMUST_T_ACCESS_MODE 0 | RMUST_T_ACTIVE_FLG 0 | RMUST_T_BACKUP_DATE_ADT 0 | RMUST_T_BACKUP_DATE_FDT 0 | RMUST_T_BACKUP_DATE_TDT 0 | RMUST_T_CALC_PNO 0 | RMUST_T_CORRUPT_FLG 0 | RMUST_T_DBID 0 | RMUST_T_EXT_COUNT 0 | RMUST_T_EXT_ENABLED_FLG 0 | RMUST_T_EXT_PERCENT 0 | RMUST_T_FILENAME 0 | RMUST_T_FILID_SLOTNUM 0 | RMUST_T_INC_RES_DATE_ADT 0 | RMUST_T_INC_RES_DATE_FDT 0 | RMUST_T_INC_RES_DATE_TDT 0 | RMUST_T_INCONSISTENT_FLG 0 | RMUST_T_LINKAGE_DBID 0 | RMUST_T_MAX_EXT_PAGCNT 0 | RMUST_T_MAX_PNO 0 | RMUST_T_MIN_EXT_PAGCNT 0 | RMUST_T_MIXED_FMT_FLG 0 | RMUST_T_PAG_BLKCNT 0 | RMUST_T_SNAPS_ALLOWED_FLG 0 | RMUST_T_SNAPS_ENABLED_FLG 0 | RMUST_T_SNAPSHOT_FLG 0 | RMUST_T_SPAMS_ENABLED_FLG 0 | RMUST_T_SPAMS_FLG 0 | RMUST_T_STAREA_NAME 0 | RMUST_T_THRESHOLD 0 } 1-45 Programming with the SGA API ___________________________ 1.8.2 Result Buffer Syntax ::= {KUSGTBOG ... KUSGTEOG}... ::= { RMUST_T_ACCESS_MODE 4 | RMUST_T_ACTIVE_FLG 4 | RMUST_T_BACKUP_DATE_ADT 8 | RMUST_T_BACKUP_DATE_FDT | RMUST_T_BACKUP_DATE_TDT | RMUST_T_CALC_PNO 4 | RMUST_T_CORRUPT_FLG 4 | RMUST_T_DBID 4 | RMUST_T_EXT_COUNT 4 | RMUST_T_EXT_ENABLED_FLG 4 | RMUST_T_EXT_PERCENT 4 | RMUST_T_FILENAME | RMUST_T_FILID_SLOTNUM 4 | RMUST_T_INC_RES_DATE_ADT 8 | RMUST_T_INC_RES_DATE_FDT | RMUST_T_INC_RES_DATE_TDT | RMUST_T_INCONSISTENT_FLG 4 | RMUST_T_LINKAGE_DBID 4 | RMUST_T_MAX_EXT_PAGCNT 4 | RMUST_T_MAX_PNO 4 | RMUST_T_MIN_EXT_PAGCNT 4 | RMUST_T_MIXED_FMT_FLG 4 | RMUST_T_PAG_BLKCNT 4 | RMUST_T_SNAPS_ALLOWED_FLG 4 | RMUST_T_SNAPS_ENABLED_FLG 4 | RMUST_T_SNAPSHOT_FLG 4 | RMUST_T_SPAMS_ENABLED_FLG 4 | RMUST_T_SPAMS_FLG 4 | RMUST_T_STAREA_NAME | RMUST_T_THRESHOLD 1-46 Programming with the SGA API ::= 32 bit unsigned DBID of storage area. This value should be used to specify an area number for the area statistics request. ::= { RMUST_K_ACCESS_READ_WRITE | RMUST_K_ACCESS_READ_ONLY | RMUST_K_ACCESS_WORM } ::= array of three bytes The descriptions of the valid item tags for the RMUST_ CT_FILE class are listed in Table 17. Table_1-18__RMUST_CT_FILE_Tags_________________________ Tag_Code___________Meaning_____________________________ RMUST_T__ACCESS_ This field specifies the access MODE mode of the area. Valid values are defined in Table 18: File Access Mode Tags. RMUST_T_ACTIVE_ If TRUE, this area is valid and can FLG be accessed. RMUST_T_BACKUP_ If this field contains zero, then DATE_ADT area has not been backed up. RMUST_T_BACKUP_ Backup time and date (FDT Format) DATE_FDT RMUST_T_BACKUP_ Backup time and date (TDT Format) DATE_TDT RMUST_T_CALC_PNO Number of pages in the CALC range for this storage area. RMUST_T_CORRUPT_ If true, then this storage area may FLG have been corrupted by an aborted batch update transaction. RMUST_T_DBID Storage area DBID of the storage area described by this FILID block. DBIDs are always one-based. 1-47 Programming with the SGA API Table_1-18_(Cont.)__RMUST_CT_FILE_Tags_________________ Tag_Code___________Meaning_____________________________ RMUST_T_EXT_COUNT This field contains the number of times that a storage area has been extended. This field is set back to zero during a restore operation. RMUST_T_EXT_ If true, then this storage area ENABLED_FLG may be extended. If false, then an exception is raised when the storage area becomes full. RMUST_T_EXT_ This field contains a percentage PERCENT factor by which the storage area is to be extended. RMUST_T_FILENAME This field contains the resultant filename of the storage area file. If the storage area is COUPLED or RELATED, then this field contains a zero-length name. RMUST_T_FILID_ Index for this area into the filid SLOTNUM vector. RMUST_T_INC_RES_ This field contains the time- DATE_ADT and-date stamp of the most recent incremental area restore that was applied to this area. RMUST_T_INC_RES_ This field contains the time- DATE_FDT and-date stamp of the most recent incremental area restore that was applied to this area. (FDT Format) RMUST_T_INC_RES_ This field contains the time- DATE_TDT and-date stamp of the most recent incremental area restore that was applied to this area. (TDT Format) 1-48 Programming with the SGA API Table_1-18_(Cont.)__RMUST_CT_FILE_Tags_________________ Tag_Code___________Meaning_____________________________ RMUST_T_ If TRUE, this area is inconsistent INCONSISTENT_ with the last commit TSN of the FLG database. RMUST_T_LINKAGE_ Linkage DBID. If this is a live DBID storage area that has snapshots allowed, then this field contains the DBID of the snapshot area for this live storage area. If this is a snapshot area, then this field contains the DBID of the live storage area for this snapshot area. RMUST_T_MAX_EXT_ This field contains the maximum PAGCNT number of pages by which the storage area is to be extended. RMUST_T_MAX_PNO Page number of the highest initialized page in the storage area. RMUST_T_MIN_EXT_ This field contains the minimum PAGCNT number of pages by which the storage area is to be extended. RMUST_T_MIXED_ If true, this is an Oracle Rdb FMT_FLG mixed page format area. RMUST_T_PAG_ Length of each area page in blocks. BLKCNT RMUST_T_SNAPS_ If true, then this is a live ALLOWED_FLG storage area that has a corresponding snapshot file. RMUST_T_SNAPS_ If true, then this is a live ENABLED_FLG storage area that has snapshots enabled. 1-49 Programming with the SGA API Table_1-18_(Cont.)__RMUST_CT_FILE_Tags_________________ Tag_Code___________Meaning_____________________________ RMUST_T_SNAPSHOT_ If true, then this is a snapshot FLG area. If false, then this is a live storage area. RMUST_T_SPAMS_ If TRUE, then this area has space ENABLED_FLG management pages and they are enabled. Spams can only be disabled for mixed format areas. RMUST_T_SPAMS_FLG If true, then this is a live storage area that has space management pages. RMUST_T_STAREA_ This field contain a name by NAME which this storage area can be referenced. This eliminates the need of having to reference the area by name by its full file-spec. RMUST_T_THRESHOL If this area has space management pages, this field contains the percentage factors for the space ___________________management_thresholds.______________ Table_1-19__File_Access_Mode_Tags______________________ File Access Constant___________Meaning_____________________________ RMUST_K_ACCESS_ Storage area is marked READ-WRITE READ_WRITE RMUST_K_ACCESS_ Storage area is marked READ-ONLY READ_ONLY RMUST_K_ACCESS_ Storage area is marked as Write WORM_______________Once_Read_Many______________________ 1-50 Programming with the SGA API __________________________________________________________________ 1.9 RMUST_CT_FILE_NODUP - File Information The RMUST_CT_FILE_NODUP class provides the same information as the RMUST_CT_FILE class. However, the RMUST_CT_FILE class returns all the data requested, no matter how many times the kusdb_get_info call is made. RMUST_CT_FILE_NODUP returns all the data requested on the first call to kusdb_get_info. On subsequent calls to kusdb_get_info, only data for those storage areas which have changed are returned. Also, data for any storage areas which have been added or dropped are returned. Note that a request for data for a single storage area is not allowed for the RMUST_CT_FILE_ NODUP class. __________________________________________________________________ 1.10 RMUST_CT_PROCESS - Process Information The process information class provide information about currently active database users. This class can return multiple rows of data. To return information for all active process, specify a length of zero in the class TLV. To return information for one process, specify the process index for the process of interest. Note that the RMUST_CT_PROCESS class is only valid for OpenVMS. ___________________________ 1.10.1 Information Buffer Syntax 1-51 Programming with the SGA API ::= RMUST_CT_PROCESS{0 | {4 }} ... KUSGTBEND ::= { RMUST_T_BIOCNT 0 | RMUST_T_CPUTIM_RT 0 | RMUST_T_DIOCNT 0 | RMUST_T_ENQCNT 0 | RMUST_T_IMAGENAME 0 | RMUST_T_NUMBIO 0 | RMUST_T_NUMDIO 0 | RMUST_T_PGFCNT 0 | RMUST_T_PGFLTS 0 | RMUST_T_PID 0 | RMUST_T_PROC_INDEX 0 | RMUST_T_PROCNAME 0 | RMUST_T_PSTATE 0 | RMUST_T_STID 0 | RMUST_T_USERNAME 0 | RMUST_T_VMSIZE 0 | RMUST_T_WSSIZE 0 } ___________________________ 1.10.2 Result Buffer Syntax 1-52 Programming with the SGA API ::= {KUSGTBOG ... KUSGTEOG} ... | ::= { RMUST_T_BIOCNT 4 } | RMUST_T_CPUTIM_RT 4 | RMUST_T_DIOCNT 4 | RMUST_T_ENQCNT 4 | RMUST_T_IMAGENAME | RMUST_T_NUMBIO 4 | RMUST_T_NUMDIO 4 | RMUST_T_PGFCNT 4 | RMUST_T_PGFLTS 4 | RMUST_T_PID 4 | RMUST_T_PROC_INDEX 4 | RMUST_T_PROCNAME | RMUST_T_PSTATE 4 | RMUST_T_STID 4 | RMUST_T_USERNAME | RMUST_T_VMSIZE 4 | RMUST_T_WSSIZE 4 } ::= zero- based index into RTUPB table for this process ___________________________ 1.10.3 Tag Descriptions Description of the item tags for the RMUST_CT_PROCESS class is shown in Table 19. Table_1-20__RMUST_CT_PROCESS_Tags______________________ Tag________________Meaning_____________________________ RMUST_T_BIOCNT Remaining buffered I/O quota. RMUST_T_CPUTIM_RT OS Specific CPU time consumed in 1/100 seconds. RMUST_T_DIOCNT Remaining direct I/O quota. RMUST_T_ENQCNT Remaining lock request quota. 1-53 Programming with the SGA API Table_1-20_(Cont.)__RMUST_CT_PROCESS_Tags______________ Tag________________Meaning_____________________________ RMUST_T_IMAGENAME OS specific name of user program. RMUST_T_NUMBIO Number of buffered I/O’s incurred by process. RMUST_T_NUMDIO Number of direct I/O’s incurred by process. RMUST_T_PGFCNT Remaining page file quota. RMUST_T_PGFLTS Number of page faults incurred by process. RMUST_T_PID OS specific process ID. RMUST_T_PROC_ index. INDEXProcess RMUST_T_PROCNAME OS specific process name. RMUST_T_PSTATE OS Specific process state string. RMUST_T_STID Stream ID of user process. RMUST_T_USERNAME OS specific user name. RMUST_T_VMSIZE Current virtual memory size. RMUST_T_WSSIZE_____Current_working_set_size.___________ __________________________________________________________________ 1.11 RMUST_CT_STALL - Stalled Process Information, RMUST_CT_STALL_ACT - Stalled Process Information The RMUST_CT_STALL class is used to return information about database processes which are stalled in the database. RMUST_CT_STALL and RMUST_CT_STALL_ACT do the same work, only RMUST_CT_STALL_ACT returns information only for those processes that are currently stalled. RMUST_CT_STALL returns information for a process regardless of whether it is stalled. These classes can return information about multiple processes. To retrieve information about all users, specify a length of zero in the TLV for the class tag. To retrieve 1-54 Programming with the SGA API information for a specific stalled process, specify the stall index for that process. ___________________________ 1.11.1 Information Buffer Syntax ::= RMUST_CT_STALL{0 | {4 }} ... KUSGTBEND ::= { RMUST_T_ASCII_DEADLOCK 0 | RMUST_T_ASCII_STALL 0 | RMUST_T_ASCII_TIMEOUT 0 | RMUST_T_DEADLOCK_SEQ 0 | RMUST_T_DEADLOCK_SINCE_ADT 0 | RMUST_T_DEADLOCK_SINCE_TT 0 | RMUST_T_DEADLOCK_SINCE_RT 0 | RMUST_T_IS_STALLED 0 | RMUST_T_LKID 0 | RMUST_T_PID 0 | RMUST_T_STALL_INDEX 0 | RMUST_T_STALL_SINCE_ADT 0 | RMUST_T_STALL_SINCE_TT 0 | RMUST_T_STALL_SINCE_RT 0 | RMUST_T_STID 0 | RMUST_T_TIMEOUT_SEQ 0 | RMUST_T_TIMEOUT_SINCE_ADT 0 | RMUST_T_TIMEOUT_SINCE_TT 0 | RMUST_T_TIMEOUT_SINCE_RT 0 } ___________________________ 1.11.2 Result Buffer Syntax ::= { KUSGTBOG ... KUSGTEOG }... ::= { RMUST_T_ASCII_DEADLOCK | RMUST_T_ASCII_STALL | RMUST_T_ASCII_TIMEOUT | RMUST_T_DEADLOCK_SEQ 4 | RMUST_T_DEADLOCK_SINCE_ADT 8 | RMUST_T_DEADLOCK_SINCE_TT | RMUST_T_DEADLOCK_SINCE_RT | RMUST_T_IS_STALLED 4 | RMUST_T_LKID 4 | RMUST_T_PID 4 | RMUST_T_STALL_INDEX 4 | RMUST_T_STALL_SINCE_ADT 8 | RMUST_T_STALL_SINCE_TT | RMUST_T_STALL_SINCE_RT 4 | RMUST_T_STID 4 | RMUST_T_TIMEOUT_SEQ 4 | RMUST_T_TIMEOUT_SINCE_ADT 8 | RMUST_T_TIMEOUT_SINCE_TT | RMUST_T_TIMEOUT_SINCE_RT 4 } ::= zero- based index into RTUPB table for this process ::= process ID ::= lock ID ::= timeout sequence number ::= deadlock sequence number ::= TRUE (1) or FALSE (0) ::= length, in bytes of subsequent data ::= ASCII text string of bytes ::= Time value, expressed in 1/100’s of seconds. _::= QUADWORD time in VMS system format. _::= Formatted ASCII time string. 1-56 Programming with the SGA API ___________________________ 1.11.3 Tag Descriptions Table_1-21__RMUST_CT_STALL_Tags________________________ Tag_Code___________Meaning_____________________________ RMUST_T_ASCII_ String indicating the lock resource DEADLOCK for the last deadlocked lock request. RMUST_T_ASCII_ String indicating the last reason STALL that the associated process was stalled for or the current stall reason if the RMUST_T_IS_ flag is TRUE. STALLED RMUST_T_ASCII_ String indicating the lock resource TIMEOUT for the last lock timeout. RMUST_T_DEADLOCK_ Indicates the number of deadlocks SEQ that have occurred against the corresponding process since it attached to the database. RMUST_T_DEADLOCK_ Time and date of the last deadlock SINCE_ADT for the associated process. RMUST_T_DEADLOCK_ Time string of the last deadlock SINCE_TT for the associated process. RMUST_T_DEADLOCK_ Relative Time of the last deadlock SINCE_RT for the associated process. RMUST_T_IS_ Boolean value indicating whether STALLED the associated process is actively blocked waiting for a database resource. RMUST_T_LKID Indicates the lock ID number associated with the stall, deadlock or lock timeout. 1-57 Programming with the SGA API Table_1-21_(Cont.)__RMUST_CT_STALL_Tags________________ Tag_Code___________Meaning_____________________________ RMUST_T_PID Specifies the process ID of the process involved in the stall, deadlock or lock timeout. RMUST_T_STALL_ index. INDEXStall RMUST_T_STALL_ Time and date of the start of the SINCE_ADT active stall. RMUST_T_STALL_ Relative time of the start of the SINCE_RT active stall. RMUST_T_STALL_ Time string of the start of the SINCE_TT active stall. RMUST_T_ ID of the process. STIDStream RMUST_T_TIMEOUT_ Indicates the number of lock SEQ timeouts that have occurred against the corresponding process since it attached to the database. RMUST_T_TIMEOUT_ Time and date of the last lock SINCE_ADT timeout for the associated process. RMUST_T_TIMEOUT_ Time string of the last lock SINCE_TT timeout for the associated process. RMUST_T_TIMEOUT_ Relative time of the last lock SINCE_RT___________timeout_for_the_associated_process._ __________________________________________________________________ 1.12 RMUST_CT_RTPMS_STATS - Run Time Performance Statistics The RMUST_CT_RTPM_STATS class is used to return run-time statistics maintained by Oracle Rdb for databases on a particular node. This request is used to return the complete run-time performance measurement statistics (RTPMS) data structure. 1-58 Programming with the SGA API ___________________________ 1.12.1 Buffer Syntax rtpms_stats_request ::= RMUST_T_RTPMS {0} KUSGTBEND ___________________________ 1.12.2 Result Buffer Syntax rtpms stats_response ::= KUSGTBOG RMUST_T_RTPMS {4096} KUSTGTEOG ::= { KUSGTBEND | KUSGTBTRN | KUSGTBCON } ::= buffer containing RTPMS values. ___________________________ 1.12.3 Tag Descriptions Table_1-22__RMUST_CT_RTPMS_STATS_Tags__________________ Tag_Code___________Meaning_____________________________ RMUST_T_RTPMS Tag used to indicate the complete RTPMS data structure is to be returned. The data returned is a 4096 byte data structure. The file RMUST_RTPMS.H contains a declaration for the RTPMS_t ___________________structure.__________________________ 1-59 _______________________________________________________ 2 SGA API Entry Point Descriptions This section describes the entry points that comprise the SGA API. Each call contains a short example. A more extensive example that uses many of the calls presented in this section can be found in the sample program listing. The README file provides further instructions about obtaining the sample program. __________________________________________________________________ 2.1 kuscx_allocate_____________ 2.1.1 Interface kusst kuscx_allocate ( kuscx_handle *ctx_handle /* (in/out) context handle */) ) ___________________________ 2.1.2 Description This routine allocates and initializes a continuation context handle which is used to maintain a context across multiple calls to kusdb_get_info to receive groups of logical records such as process information records. Handles are released with the kuscx_free_ handle call. A handle can also be reinitialized for use_with_the_kuscx_init_call. 2.1.3 Parameters ctx_handle - Address to contain the handle. 2-1 SGA API Entry Point Descriptions ___________________________ 2.1.4 Condition Values Returned KUSSTOK - Normal successful completion. KUSSTALLC - Error allocating memory. ___________________________ 2.1.5 Example kuscx_handle ctx_handle; kusst status; status = kuscx_allocate (&ctx_handle); if (status != KUSSTOK)) /* Do error handling... */ __________________________________________________________________ 2.2 kuscx_free_handle__________ 2.2.1 Interface kusst kuscx_free_handle ( kuscx_handle *ctx_ handle /* (in/out) continuation handle */ ) ___________________________ 2.2.2 Description Releases a continuation context handle previously allocated_through_a_call_to kuscx_init. 2.2.3 Parameters ctx_handle - Address of the handle to be freed. ___________________________ 2.2.4 Condition Values Returned KUSSTOK - Normal successful completion. KUSSTICH - Invalid context handle supplied 2-2 SGA API Entry Point Descriptions ___________________________ 2.2.5 Example kusst status; kuscx_handle ctx_handle; status = kuscx_free_handle (&ctx_handle) if (status != KUSSTOK) /* Do error handling ... */ __________________________________________________________________ 2.3 kuscx_init_________________ 2.3.1 Interface kusst kuscx_init ( kuscx_handle *ctx_ handle /* (in/out) continuation handle */ ) ___________________________ 2.3.2 Description Reinitializes a continuation context handle previously allocated through a call to kuscx_allocate. A call to kuscx_init prepares a continuation context handle for a subsequent use in a continuation context operation. It is semantically equivalent to issuing a call to kuscx_free_handle on a valid continuation context handle followed by a call to kuscx_allocate. However calling kuscx_init instead avoids the overhead of freeing_memory_and_reallocating it. 2.3.3 Parameters ctx_handle - Address of the handle to be initialized. 2-3 SGA API Entry Point Descriptions ___________________________ 2.3.4 Condition Values Returned KUSSTOK - Normal successful completion. KUSSTICH - Invalid context handle supplied. ___________________________ 2.3.5 Example kuscx_handle ctx_handle; kusst status; status = kuscx_allocate (&ctx_handle); . . . status = kuscx_init (&ctx_handle); if (status != KUSSTOK) /* Do error handling ... */ __________________________________________________________________ 2.4 kusdb_allocate_____________ 2.4.1 Interface kusst kusdb_allocate ( kusdb_ handle *handle /* (in/out) Database Handle */ ) ___________________________ 2.4.2 Description This routine allocates memory for a DB handle. This handle is used in other kusdb calls. Typically, after calling kusdb_allocate, the caller will next call kusdb_connect. When a user is finished with the DB handle, kusdb_free must be called to free resources used by the handle. 2-4 SGA API Entry Point Descriptions ___________________________ 2.4.3 Parameters o handle - Address of a database handle This handle is updated by kusdb_connect and should be passed in subsequent calls to functions that should use this connection. ___________________________ 2.4.4 Condition Values Returned o KUSSTOK - Normal successful value o KUSSTALLC - Error allocating memory ___________________________ 2.4.5 Example kusdb_handle db_handle; kusst status; status = kusdb_allocate (&db_handle); if (status != KUSSTOK) ... __________________________________________________________________ 2.5 kusdb_connect______________ 2.5.1 Interface kusst kusdb_connect ( kusdb_ handle handle, /* (in/out) Database Handle */ ub4 database_name_ length, /* (in) Length of db name */ char *database_ name, /* (in) Name of database */ ub4 security_ length, /* (in, opt) Len of security */ /* info 0 if not supplied */ char *security_ 2-5 SGA API Entry Point Descriptions info /* (in, opt) Security info */ /* NULL if not supplied */ } Note: The ub4 (security length) and char (security info) are ignored for Oracle Rdb. ___________________________ 2.5.2 Description This routine connects to the specified database and then allocates and initializes the resources necessary to support gathering of statistics. The companion routine, kusdb_disconnect should be used to deallocate and release resources seized by this routine. If an error status is returned, kusdb_error_text can be called to get more information about the error. Note: The specified database must be local to the node running the process calling kusdb_connect. Connecting to remote databases is not supported. For Oracle Rdb databases, this call performs a “utility bind” to the database. This process does not become a user of the database as far as Oracle Rdb is concerned. ___________________________ 2.5.3 Parameters o handle - Database handle This handle must have been allocated by kusdb_allocate. o database_name_length - Name and length of the name of the database to connect. o database_name - A database name must be specified for an Oracle Rdb database. 2-6 SGA API Entry Point Descriptions o security_length, security_info - Length and value of security information. If no security information is specified (the value of security_info_length is 0), then kusdb_connect uses the user name of the process. These fields must be 0. The Oracle Rdb API uses the name of the user running the program to access the database. ___________________________ 2.5.4 Condition Values Returned o KUSSTOK - Normal successful value o KUSSTALLC - Unable to allocate memory o KUSSTIDH - Invalid database handle supplied ___________________________ 2.5.5 Example kusdb_handle db_handle; kusst status; char db_name = "mf_personnel"; status = kusdb_connect (&db_ handle, (dbname *)NULL, 0, strlen(dbname), strlen(0_info)); if (status != KUSSTOK) ... __________________________________________________________________ 2.6 kusdb_disconnect___________ 2.6.1 Interface kusst kusdb_disconnect ( kusdb_handle db_handle /* (in/out) database handle */ } 2-7 SGA API Entry Point Descriptions ___________________________ 2.6.2 Description This routine disconnects from a database that had been connected with a call to kusdb_connect. If the handle is no longer needed after this call, kusdb_free should be_called_to_free_resources used by the handle. 2.6.3 Parameters o db_handle - The handle of the database that is no longer needed. ___________________________ 2.6.4 Condition Values Returned o KUSSTOK - Normal successful completion o KUSSTIDH - Invalid handle ___________________________ 2.6.5 Example kusdb_handle db_handle; kusst status; status = kusdb_disconnect (db_handle); __________________________________________________________________ 2.7 kusdb_free_________________ 2.7.1 Interface kusst kusdb_free ( kusdb_ handle *handle /* (in/out) Database Handle */ } 2-8 SGA API Entry Point Descriptions ___________________________ 2.7.2 Description This routine frees memory associated with a DB handle as_a_result_of_calling_kusdb_allocate. 2.7.3 Parameters o handle - Address of a database handle ___________________________ 2.7.4 Condition Values Returned o KUSSTOK - Normal successful value o KUSSTIDH - Invalid database handle supplied ___________________________ 2.7.5 Example kusdb_handle db_handle; kusst status; status = kusdb_free (&db_handle); if (status != KUSSTOK) ... __________________________________________________________________ 2.8 kusdb_error_text___________ 2.8.1 Interface kusst kusdb_error_text ( kusdb_handle db_handle /* (IN) handle of database */ char *text_buf, /* (IN) Ptr to user- supplied buffer */ ub4 text_buf_ len /* (IN) Length of supplied buffer */ ub4 *text_len_ out /* (OUT) Number of bytes written */ ) 2-9 SGA API Entry Point Descriptions ___________________________ 2.8.2 Description Formats the status of the last kusdb_get_info or kusdb_connect call into text and inserts it into a user_supplied_buffer.______ 2.8.3 Parameters o db_handle - Handle of the database whose last error is to be displayed. o text_buf - Address of an allocated piece of memory that will contain the formatted message. o text_buf_len - The number of bytes allocated in text_buf. o text_len_out - The number of bytes written into text_buf. ___________________________ 2.8.4 Condition Values Returned o KUSSTOK - Normal successful completion o KUSSTALLC - Unable to allocate memory o KUSSTIDH - Invalid database handle supplied ___________________________ 2.8.5 Example text err_buffer [512]; ub4 err_buffer_len, err_buffer_len; kusst status; if (KUSSTOK != kusdb_get_info (db_handle…); { if (KUSSTOK == kusdb_error_text (db_handle, err_buffer, sizeof (err_buffer),&err_ buffer_len)) fprintf (stderr, "ERROR: %.*s\n", err_buffer_len, err_ 2-10 SGA API Entry Point Descriptions buffer); else fprintf (stderr, "ERROR FORMATTING STATUS\n"); } __________________________________________________________________ 2.9 kusdb_get_info_____________ 2.9.1 Interface kusst kusdb_get_info { kusdb_handle db_ handle, /* (in)database handle */ kuscx_handle cont_ handle, /* (in,opt) Continuation handle */ /* NULL if not supplied */ ub1 *info_ buffer, /* (in) address of info buffer */ ub4 info_buffer_length, /* (in) bytes in info buffer */ ub1 *result_ buffer, /* (in/out) address of result buffer*/ ub4 *result_buffer_length, /* (in/out) bytes in result buffer */ kustvs *tlv_ state /* (out) termination tag for */ /* result buffer */ ) ___________________________ 2.9.2 Description This call implements the main statistics gathering interface. Communication with the statistics interface is performed by building a request buffer to specify the information items you’re interested in retrieving. The kusdb_get_info call uses the information buffer to determine what information to return in the result buffer. Information on the request and response buffer 2-11 SGA API Entry Point Descriptions formats is presented on page 6, Information and Result Buffer_Formats.____________ 2.9.3 Parameters o db_handle - An initialized handle returned by a call to kusdb_connect. o cont_handle - An initialized continuation context handle returned by a call to either kuscx_allocate or kuscx_init. o info_buffer - Address of an allocated and initialized buffer that indicates the type of information to be retrieved. o info_buffer_length - Number of valid bytes in info_ buffer. o result_buffer - Address of a caller allocated before that kusdb_get_info uses to return information to the caller. o result_buffer_length - When kusdb_get_info is called, this parameter contains the number of bytes allocates by the caller for the return_buf parameter. When the routine has completed execution, this parameter contains the number of bytes that were written by the routine into return_buf. o tlv_state - Address of a variable to hold the state of the termination of the result buffer. Valid values are: KUSTVS_CONTBuffer ended with KUSGTBCNT tag. Returned only if cont_handle was specified and there is more data to be returned for the request. To get more of the requested data, call kusdb_get_info again specifying the same info_ buffer and cont_handle. KUSTVS_ENDBuffer ended with KUSGTBEND tag. Returned if all requested data fit in the result_buffer. KUSTVS_TRUNCBuffer ended with KUSGTTRNC tag. Returned only if cont_handle was not specified and there was more data to be returned for the request. KUSTVS_UNKBuffer not terminated or 2-12 SGA API Entry Point Descriptions TLV handle has not been used to read or write the last tag. This value is returned if an error occured while processing the request. ___________________________ 2.9.4 Condition Values Returned o KUSSTOK - Normal successful completion o KUSSTALLC - Unable to allocate memory o KUSSTBDKY - Bad index value for class tag o KUSSTBFSML - Buffer too small for data o KUSSTBINF - Information buffer contains a bad tag o KUSSTDIS - Statistics collection disabled for this database o KUSSTIBE - Information buffer is empty o KUSSTICH - Invalid context handle supplied o KUSSTIDH - Invalid database handle supplied o KUSSTUNKC - Unknown class tag specified ___________________________ 2.9.5 Example #define INFO_BUFFER_LEN 1000 #define RESULT_BUFFER_LEN 10000 kusdb_handle db_handle; kuscx_handle cont_handle; kusst status; kustv_handle info_tlv_handle; kustvs tlv_state = KUSTVS_CONT; ub1 info_buffer[INFO_BUFFER_LEN], data_buffer[RESULT_BUFFER_LEN]; ub4 result_buffer_length=RESULT_BUFFER_LEN /* allocate a db handle and connect to the database */ status = kusdb_allocate (&db_handle); status = kusdb_connect (db_handle...); 2-13 SGA API Entry Point Descriptions /* initialize the context handle */ status = kuscx_allocate (&cont_handle); /* initialize TLV handle for info buffer and call kustv_ put to load it */ status = kustv_allocate_handle (&info_tlv_handle, info_buffer, INFO_BUFFER_LEN); status = kustv_put (info_tlv_handle...); ... /* collect information */ while (tlv_state == KUSTVS_CONT) { status = kusdb_get_info (db_handle, cont_handle, info_buffer, INFO_BUFFER_LEN, data_buffer, &result_buffer_len, &tlv_state); /* process data_buffer */ . . . } __________________________________________________________________ 2.10 kustv_allocate_handle______ 2.10.1 Interface kusst kustv_allocate_handle ( kustv_handle *tlv_ handle, /* (in/out) handle to init */ ub1 *tlv_ buffer, /* (in) TLV buffer */ ub4 buf_ size) /* (in) bytes in buffer */ ) 2-14 SGA API Entry Point Descriptions ___________________________ 2.10.2 Description Associates a TLV handle with a TLV buffer allocated by the user. kustv_allocate_handle must be called to initialize the handle prior to using any other TLV support routine. kustv_reinit_handle can be used to reinitialize a handle so that it points to the beginning of the buffer. If the size is not known, specify a value of -1 for buf_size. This should be done only with buffers that are known to have been terminated with a valid termination tag (KUSGTBEND, KUSGTBTRN, or KUSGTBCNT) such as result buffers written by calls to kusdb_get_ info. If -1 is specified for buf_size, then tlv_handle can be used only to read from the buffer. Any attempt to write to such a buffer will fail with a status of KUSSTNWR. ___________________________ 2.10.3 Parameters o tlv_handle - Handle to be initialized for this TLV buffer. This handle is passed in other calls to manipulate the TLV. o tlv_buffer - Address of the TLV buffer to be associated with tlv_handle. o buf_size - Number of bytes in tlv_buffer. ___________________________ 2.10.4 Condition Values Returned o KUSSTOK - Success o KUSSTALLC - Error allocating memory 2-15 SGA API Entry Point Descriptions ___________________________ 2.10.5 Example char ret_buf [8192]; kustv_handle ret_tlv; kusst status; status = kustv_allocate_handle (&ret_tlv, ret_buf, sizeof (ret_ buf)); __________________________________________________________________ 2.11 kustv_dump_________________ 2.11.1 Interface kusst kustv_dump ( kustv_handle *tlv_ handle, /* (in) TLV buffer to dump */ CONST char *header, /* (in, opt) header */ int data_ flg, /* (in) print values? */ int *append_ flg, /* (in) append to output file */ CONST char *directory_ name, /* (in) directory for file */ CONST char *file_ name /* (in) File to dump into */ ) ___________________________ 2.11.2 Description Prints a formatted display of the specified TLV buffer described by tlv_handle to the file specified by file_ name in the directory specified by directory_name. The parameters file_name and directory_name are both optional. If file_name is not specified, the output is sent to stderr. If the append_flg parameter is true, then the output is appended to an existing file. Otherwise, a new file is created. If the append_flag 2-16 SGA API Entry Point Descriptions is non-zero and the file specified by file_name does not exist, then the KUSSTDMPOP status is returned. This routine is useful for debugging purposes. The optional header argument can be used to display a descriptive title in the header output. If data_flg is non-zero, a hex dump of the values associated with each TLV entry will be displayed along with the buffer format. ___________________________ 2.11.3 Parameters o tlv_handle - Handle of the TLV buffer whose contents are to be dumped. o header - Pointer to ASCIZ string containing text to be printed before the dump is performed. o data_flg - Flag used to indicate if the data in each TLV entry should be displayed along with the tag and the length. If set to a non-zero value, the data for each TLV is displayed. If set to zero, only the tag and length are displayed. o append_flg - Flag to indicate if an existing instance of the output file should be appended to (or replaced) o directory - ASCIZ string containing a directory specification for the output file. If an empty string is specified, the current default directory is used. o file_name - ASCIZ string containing a file name for the output file. If absent, stderr is used and append_flg and directory are ignored. If specified without an extension, the Oracle extension for an output file on the given platform is used. 2-17 SGA API Entry Point Descriptions ___________________________ 2.11.4 Example kustv_handle tlv_handle; kusst status; ub1 tlv_buff[1000]; status = kustv_allocate_handle (&tlv_handle, tlv_buff, 1000); status = kustv_put (tlv_handle, . . .); status = kustv_dump (tlv_ handle, "Dump of TLV buffer just filled", 1, 1, "", NULL); __________________________________________________________________ 2.12 kustv_free_handle__________ 2.12.1 Interface kusst kustv_free_handle ( kustv_handle *tlv_ handle, /* (in/out) handle to initialize*/ ) ___________________________ 2.12.2 Description Frees resources used by a TLV handle. This routine is called when the buffer described by a handle is no longer needed. Note that calling kustv_reinit_ handle is the semantic equivalent of calling kustv_ free_followed_by_kustv_allocate. 2.12.3 Parameters o tlv_handle - Handle whose resources are to be freed. 2-18 SGA API Entry Point Descriptions ___________________________ 2.12.4 Condition Values Returned o KUSSTOK - Success o KUSSTITH - Invalid TLV handle ___________________________ 2.12.5 Example char ret_buf [8192]; kustv_handle ret_tlv; kusst status; status = kustv_allocate_handle (&ret_tlv, ret_buf, sizeof (ret_ buf)); . . . status = kustv_free_handle (&ret_tlv); __________________________________________________________________ 2.13 kustv_get__________________ 2.13.1 Interface kusst kustv_get ( kustv_handle tlv_ hndl, /* (in) handle for TLV structure */ ub2 *tag, /* (out) Tag of next entry */ ub2 *length, /* (out) Length of value field in bytes */ dvoid *value /* (out) Pointer to value field */ ) ___________________________ 2.13.2 Description Returns the next TLV set associated with the TLV handle and updates tlv_hndl to point to the next TLV in the buffer. If the return value is not KUSSTOK, then the output variables (tag, length, and value) do not contain valid data. 2-19 SGA API Entry Point Descriptions Note that kustv_get should be used only on TLV buffers that have been terminated by TLVs with tags KUSGTBEND, KUSGTBTRN, or KUSGTBCNT. These tags are the only way for kustv_get to know when the last TLV has been read. The kusdb_get_info function always ends the results buffer with one of these tags, unless an error occurred. ___________________________ 2.13.3 Parameters o tlv_hndl - Handle for TLV whose offset is to be returned. o tag - Value of tag field in next TLV entry. o length - Value of length field in next TLV entry. o value - Pointer to value in the TLV entry. If value returned for length is 0, then value should not be used (it may not point to valid memory.) ___________________________ 2.13.4 Condition Values Returned o KUSSTOK - Success o KUSSTCONT - Buffer continuation tag was read by a previous get o KUSSTEOB - End of buffer encountered by a previous get o KUSSTITH - Illegal tag handle o KUSSTTRNC - Buffer truncation tag was read by a previous get 2-20 SGA API Entry Point Descriptions ___________________________ 2.13.5 Example kustv_handle ret_tlv; unsigned short tag; unsigned short length; dvoid *pvalue; kusst status; status = kustv_get (ret_tlv, &tag, &length, &pvalue); __________________________________________________________________ 2.14 kustv_offset_______________ 2.14.1 Interface kusst kustv_offset ( kustv_handle tlv_ hndl; /* (in) handle for TLV structure */ ub4 *offset; /* (out) current offset for tlv_ hndl*/ ) ___________________________ 2.14.2 Description Returns the current offset of tlv_hndl into the TLV structure. The current offset is the byte offset at which the next read or write operation will occur. The current offset can be reinitialized by calling kustv_reinit_handle. This routine can be useful for debugging_purposes.________ 2.14.3 Parameters o tlv_hndl - Handle for TLV whose offset is to be returned o offset - Offset into the TLV buffer of the next TLV entry 2-21 SGA API Entry Point Descriptions ___________________________ 2.14.4 Condition Values Returned o KUSSTOK - Success o KUSSTITH - Illegal tag handle ___________________________ 2.14.5 Example ub4 offset; text buff[10000]; kustv_handle tlv_hndl; kusst status; ... status = kustv_offset (tlv_hndl, &offset); __________________________________________________________________ 2.15 kustv_put__________________ 2.15.1 Interface kusst kustv_put ( kustv_handle tlv_ handle, /* (in/out) handle */ ub2 tag, /* (in) Tag */ ub2 length /* (in) length of value buffer */ dvoid *value /* (in) address of value */ ) ___________________________ 2.15.2 Description Adds a TLV into a TLV buffer. Before this TLV entry is written, kustv_put makes sure there is enough room for this TLV (plus enough room for a TLV containing a termination tag if this TLV does not contain a termination tag). If there is no room for this TLV entry, then a TLV with tag KUSGTBTRN is written into the buffer. If a termination tag has already been 2-22 SGA API Entry Point Descriptions written to the TLV, then the TLV data is not added and the return status indicates how the buffer was terminated.________________ 2.15.3 Parameters o tlv_handle - Handle of the TLV buffer that gets this TLV entry o tag - tag for the new TLV entry o length - length of the value to be inserted into the TLV o value - address of value to be copied into the TLV buffer. If length is zero, then value is ignored. ___________________________ 2.15.4 Condition Values Returned o KUSSTOK - Success o KUSSTBFSML - Buffer is empty and this TLV is too large to fit into it. No TLV was written into the buffer. o KUSSTCONT - Buffer is terminated with KUSGTBCNT. TLV was not added. o KUSSTEOB - Buffer is terminated with KUSGTBEND. TLV was not added. o KUSSTNWR - TLV put operation attempted on a TLV buffer that doesn't have a length associated with it. o KUSSTTRNC - Buffer is terminated with KUSGTBTRN. TLV was not added. 2-23 SGA API Entry Point Descriptions ___________________________ 2.15.5 Example kusst status; kustv_handle info_tlv; char *area_name = “Area1”; char info_buf[1000]; status = kustv_allocate (&info_tlv, info_buf, 1000); status = kustv_put (info_tlv, RMUST_T_STAREA_NAME, strlen (area_name), area_name); __________________________________________________________________ 2.16 kustv_reinit_handle________ 2.16.1 Interface kusst kustv_reinit_handle ( kustv_handle tlv_ handle,/* (in/out) handle to initialize */ ub1 *buffer, /* (in) buffer for the handle */ ub4 buf_ size /* (in) size of buffer */ ) ___________________________ 2.16.2 Description Reset the handle so that the offset points to the beginning of the specified buffer. This is useful when rereading_or_reusing_a_buffer. 2.16.3 Parameters o tlv_handle - Handle of the TLV buffer to be reset o buffer - address of user allocated buffer for this handle o buf_size - number of bytes in buffer 2-24 SGA API Entry Point Descriptions ___________________________ 2.16.4 Condition Values Returned o KUSSTOK - Success o KUSSTITH - Invalid TLV handle ___________________________ 2.16.5 Example kustv_handle ret_tlv; ub1 tlv_buff[1000]; kusst status; status = kustv_reinit_handle (ret_tlv, tlv_buff, 1000); __________________________________________________________________ 2.17 kustvp1_put_one_byte_______ 2.17.1 Interface kusst kustvp1_put_one_byte ( kustv_handle tlv_ handle, /* (in/out) TLV handle */ ub2 tag, /* (in) Tag */ ub1 value /* (in) Value */ ) ___________________________ 2.17.2 Description Adds a TLV with a value field of a single byte into a TLV buffer. See documentation for kustv_put for information about what happens when the TLV to be added will not fit into the buffer. 2-25 SGA API Entry Point Descriptions ___________________________ 2.17.3 Parameters o tlv_handle - handle of the TLV buffer that gets this TLV entry added o tag - tag for the new TLV entry o value - 1-byte value of the new TLV entry ___________________________ 2.17.4 Condition Values Returned o KUSSTOK - Success o KUSSTBFSML - Buffer is empty and this TLV is too large to fit into it. No TLV was written into the buffer. o KUSSTCONT - Buffer is terminated with KUSGTBCNT. TLV was not added. o KUSSTEOB - Buffer is terminated with KUSGTBEND. TLV was not added. o KUSSTNWR - TLV put operation attempted on a TLV buffer that doesn't have a length associated with it. o KUSSTTRNC - Buffer is terminated with KUSGTBTRN. TLV was not added. ___________________________ 2.17.5 Example ub1 my_c; ub2 tag; kustv_handle tlv_hndl; kusst status; ... status = kustvp1_put_one_byte (tlv_hndl, tag, my_c); 2-26 SGA API Entry Point Descriptions __________________________________________________________________ 2.18 kustvp2_put_two_bytes______ 2.18.1 Interface kusst kustvp2_put_two_bytes ( kustv_handle tlv_ handle, /* (in/out) TLV handle */ ub2 tag, /* (in)Tag */ ub2 value /* (in) value to place in the TLV */ ) ___________________________ 2.18.2 Description Adds a TLV with a value field of two bytes into a TLV buffer. See documentation for kustv_put for information about what happens when the TLV to be added_will_not_fit_into_the buffer. 2.18.3 Parameters o tlv_handle - handle of the TLV buffer that gets this TLV entry added o tag - tag for the new TLV entry o value - 2-byte value of the new TLV entry ___________________________ 2.18.4 Condition Values Returned o KUSSTOK - Success o KUSSTBFSML - Buffer is empty and this TLV is too large to fit into it. No TLV was written into the buffer. o KUSSTCONT - Buffer is terminated with KUSGTBCNT. TLV was not added. o KUSSTEOB - Buffer is terminated with KUSGTBEND. TLV was not added . 2-27 SGA API Entry Point Descriptions o KUSSTNWR - TLV put operation attempted on a TLV buffer that doesn't have a length associated with it. o KUSSTTRNC - Buffer is terminated with KUSGTBTRN. TLV was not added. ___________________________ 2.18.5 Example ub2 my_w; ub2 tag; kustv_handle tlv_hndl; kusst status; ... status = kustvp2_put_two_bytes (tlv_hndl, tag, my_w); __________________________________________________________________ 2.19 kustvp4_put_four_bytes_____ 2.19.1 Interface kusst kustvp4_put_four_bytes ( kustv_handle tlv_ handle,/* (in/out) TLV handle */ ub2 tag, /* (in) Tag */ ub4 value /* (in) Value */ ) ___________________________ 2.19.2 Description Adds a TLV entry with a value field of 4 bytes into a TLV buffer. See documentation for kustv_put for information about what happens when the TLV to be added will not fit into the buffer. 2-28 SGA API Entry Point Descriptions ___________________________ 2.19.3 Parameters o tlv_handle - handle of the TLV buffer that gets this TLV entry added o tag - tag for the new TLV entry o value - 4-byte value of the new TLV entry ___________________________ 2.19.4 Condition Values Returned o KUSSTOK - Success o KUSSTBFSML - Buffer is empty and this TLV is too large to fit into it. No TLV was written into the buffer. o KUSSTCONT - Buffer is terminated with KUSGTBCNT. TLV was not added. o KUSSTEOB - Buffer is terminated with KUSGTBEND. TLV was not added. o KUSSTNWR - TLV put operation attempted on a TLV buffer that doesn't have a length associated with it. o KUSSTTRNC - Buffer is terminated with KUSGTBTRN. TLV was not added. ___________________________ 2.19.5 Example ub4 my_c; ub2 tag; kustv_handle tlv_hndl; kusst status; ... status = kustvp4_put_four_bytes (tlv_hndl, tag, my_c); 2-29 SGA API Entry Point Descriptions __________________________________________________________________ 2.20 kustvptg_put_tag___________ 2.20.1 Interface kusst kustvptg_put_tag ( kustv_handle tlv_ handle, /* (in/out) handle */ ub2 tag /* (in) Tag */ ) ___________________________ 2.20.2 Description Write a TLV entry that contains a tag with no value into the TLV described by tlv_handle. See documentation for kustv_put for information about what happens when the TLV to be added will not fit into the buffer.____________________ 2.20.3 Parameters o tlv_handle - handle of the TLV buffer that gets this TLV entry added o tag - tag for the new TLV entry ___________________________ 2.20.4 Condition Values Returned o KUSSTOK - Success o KUSSTBFSML - Buffer is empty and this TLV is too large to fit into it. No TLV was written into the buffer. o KUSSTCONT - Buffer is terminated with KUSGTBCNT. TLV was not added. o KUSSTEOB - Buffer is terminated with KUSGTBEND. TLV was not added. 2-30 SGA API Entry Point Descriptions o KUSSTNWR - TLV put operation attempted on a TLV buffer that doesn't have a length associated with it. o KUSSTTRNC - Buffer is terminated with KUSGTBTRN. TLV was not added. ___________________________ 2.20.5 Example kustv_handle tlv_hndl; kusst status; ... status = kustvptg_put_tag (tlv_hndl, KUSGTBEND); 2-31