HP 3000 Manuals HP 3000 Manuals
Chapter 5 TurboIMAGE/XL Library Procedures Using TurboIMAGE/XL Intrinsics This chapter contains the reference specifications for the TurboIMAGE/XL library procedures (also known as intrinsics), arranged alphabetically. Table 5-1 gives a summary of the procedures with a brief description of their function. On the following pages, the calling parameters for each procedure are defined in alphabetical order for easy look-up rather than the order in which they appear in the call statement. Every parameter must be included when a call is made because a parameter's meaning is determined by its position.
NOTE All parameters must be on halfword boundaries. Database names, data set names, and data item names that are passed to the TurboIMAGE/XL intrinsics must be in uppercase.
Table 5-1. TurboIMAGE/XL Procedures -------------------------------------------------------------------------------------------- | | | | Procedure | Function | | | | -------------------------------------------------------------------------------------------- | | | | DBBEGIN | When logging, designates the beginning of a transaction and | | | optionally writes user information to the log file. | | | | -------------------------------------------------------------------------------------------- | | | | DBCLOSE | Terminates access to a database or a data set, or resets the | | | pointers of a data set to their original state. | | | | -------------------------------------------------------------------------------------------- | | | | DBCONTROL | Allows a process operating in exclusive mode to enable or | | | disable the deferred output (AUTODEFER) option. Also allows a | | | process to enable or disable the critical item update (CIUPDATE) | | | option for the current DBOPEN without affecting other processes | | | operating on the same database. | | | | -------------------------------------------------------------------------------------------- | | | | DBDELETE | Deletes an existing entry from a data set. | | | | -------------------------------------------------------------------------------------------- | | | | DBEND | When logging, designates the end of a transaction and optionally | | | writes user information to the log file. | | | | -------------------------------------------------------------------------------------------- | | | | DBERROR | Supplies an ASCII language message that interprets the status | | | information set by any callable TurboIMAGE/XL procedure. The | | | message is returned to the calling program in a buffer. | | | | -------------------------------------------------------------------------------------------- | | | | DBEXPLAIN | Examines status information returned by a TurboIMAGE/XL | | | procedure and prints a multiline message on the $STDLIST device. | | | | -------------------------------------------------------------------------------------------- | | | | DBFIND | Locates the first and last entries of a data chain in | | | preparation for access to entries in the chain. | | | | -------------------------------------------------------------------------------------------- | | | | DBGET | Reads the data item values of a specified entry. | | | | -------------------------------------------------------------------------------------------- | | | | DBINFO | Provides information about the database being accessed, such as | | | the name and description of a data item or data set. It also | | | provides information on logging, including logging of dynamic | | | and multiple database transactions, and on third-party indexing, | | | critical item update, and other options. | | | | -------------------------------------------------------------------------------------------- | | | | DBLOCK | Locks one or more data entries, a data set, or an entire | | | database (or a combination of these) temporarily to allow the | | | process calling the procedure to have exclusive access to the | | | locked entities. | | | | -------------------------------------------------------------------------------------------- | | | | DBMEMO | When logging, writes user information to the log file. | | | | -------------------------------------------------------------------------------------------- | | | | DBOPEN | Initiates access to a database. Specifies the user access mode | | | and user class number for the duration of the process. | | | | -------------------------------------------------------------------------------------------- | | | | DBPUT | Adds a new entry to a manual master or detail data set. | | | | -------------------------------------------------------------------------------------------- | | | | DBUNLOCK | Releases those locks obtained with previous call(s) to DBLOCK. | | | | -------------------------------------------------------------------------------------------- | | | | DBUPDATE | Modifies the values of data items. Cannot be used to update | | | master data set key items. Can be used to update detail data | | | set search and sort items in database access mode 1, 3, or 4 if | | | permitted by the critical item update (CIUPDATE) option settings | | | for the database and the current process. | | | | -------------------------------------------------------------------------------------------- | | | | DBXBEGIN | Designates the beginning of a dynamic transaction. Refer to | | | "Transactions" later in this chapter for a description of | | | dynamic transactions. | | | | -------------------------------------------------------------------------------------------- | | | | DBXEND | Designates the end of a dynamic transaction. | | | | -------------------------------------------------------------------------------------------- | | | | DBXUNDO | Rolls back the active dynamic transaction. | | | | -------------------------------------------------------------------------------------------- Table 5-2 illustrates the forms of the call statements for the languages that can be used to call the procedures. Chapter 6 contains examples of using the procedures and specifications for declaration of parameters for some of these languages. It also provides a sample RPG program. Table 5-2. Calling a TurboIMAGE/XL Procedure --------------------------------------------------------------------------------------------- | | | | COBOL II | CALL "name" USING parameter,parameter,...,parameter. | | | | | FORTRAN 77 | CALL name (parameter,parameter,...,parameter) | | | | | Pascal | name (parameter,parameter,...,parameter); | | | | | BBASIC | linenumber CALL name (parameter,parameter,...,parameter) | | | | | C | name (parameter,parameter,...,parameter); | | | | --------------------------------------------------------------------------------------------- All procedures can be called from programs in any of the host languages. Intrinsic Numbers An intrinsic number is provided for each procedure. This number, which uniquely identifies the procedure within TurboIMAGE/XL and the MPE/iX operating system, is returned with other status information when an error occurs. You can use it to identify the procedure that caused the error or call DBEXPLAIN to interpret the number and other information. Database Protection When each procedure is called, TurboIMAGE/XL verifies that the requested operation is compatible with the user class number and access mode established when the database is opened. Unused Parameters When calling some procedures for a specific purpose, one of the parameters can be ignored; however, it still must be listed in the call statement. An application program may find it useful to set up a variable named Not_Used_Parm or DUMMY to be listed as the unused parameter as a reminder that the value of the parameter does not affect the procedure call. Refer to the examples in chapter 6. The Status Array The status array is a communication area. If the procedure executes successfully, the contents of the array reflect this as described under each intrinsic discussion in this chapter. If the procedure fails, standard error information is returned in the array as described in this chapter and appendix A. Transactions TurboIMAGE/XL transactions are defined below: Table 5-3. Types of Transactions -------------------------------------------------------------------------------------------- | | | | Transaction | Definition | | | | -------------------------------------------------------------------------------------------- | | | | Single | A single call to an intrinsic. A single transaction is not | | | delimited by DBBEGIN and DBEND, or DBXBEGIN and DBXEND. | | | | -------------------------------------------------------------------------------------------- | | | | Logical | A sequence of one or more procedure calls that begins with a | | | DBBEGIN or DBXBEGIN call and ends with a DBEND or DBXEND call. | | | A logical transaction can contain several intrinsic calls, but | | | is logically considered one transaction. | | | | -------------------------------------------------------------------------------------------- | | | | Static | A logical transaction that begins with a DBBEGIN call and ends | | | with a DBEND call. A static transaction spans only one | | | database, and can be recovered with DBRECOV. | | | | -------------------------------------------------------------------------------------------- | | | | Dynamic | A logical transaction that begins with a DBXBEGIN call and ends | | | with a DBXEND call. A dynamic transaction can be rolled back | | | dynamically with DBXUNDO. A dynamic transaction spans only one | | | database. | | | | -------------------------------------------------------------------------------------------- | | | | Multiple database | A logical transaction that spans more than one database. A | | | multiple database transaction begins with a DBBEGIN call and | | | ends with a DBEND call. A multiple database transaction can be | | | recovered with DBRECOV. | | | | -------------------------------------------------------------------------------------------- Refer to chapters 4 and 7 for more information on transactions. DBBEGIN INTRINSIC NUMBER 412 Designates the beginning of a sequence of TurboIMAGE/XL procedure calls regarded as a static or multiple database transaction (based on the mode) for the purposes of logging and recovery. The text parameter can be used to log user information to the log file. DBBEGIN is used in conjunction with DBEND to begin and end a static or multiple database transaction. Syntax DBBEGIN, {base } ,text,mode,status,textlen {baseidlist} Parameters base is the name of the array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.) Use base when calling DBBEGIN mode 1 (static transaction). baseidlist is the name of the integer array containing the base IDs of the databases which are involved in a multiple database transaction. Use baseidlist when calling DBBEGIN mode 3 or 4 (multiple database transaction). The layout of this array is shown here (note that each element is a halfword, or two bytes): Element Contents 1-2 The application program must set these two halfwords to binary 0s before calling DBBEGIN. After returning to the calling program, these two halfwords contain the transaction ID. This ID can be used in order to end the transaction by calling DBEND. 3 The number of base IDs involved in the multiple database transaction. This must be a number between 1 and 15, inclusive. 4-n Base IDs of the databases involved in the transaction. Base ID is the first halfword of the base parameter used to call TurboIMAGE/XL intrinsics. text is the name of an array up to 256 halfwords long which contains user ASCII or binary data to be written to the log file as part of the DBBEGIN log record. The text argument is used to assign each particular transaction a distinct name. (Refer to "Discussion" below for more information.) mode is an integer indicating the type of transaction desired as follows: Mode 1: Indicates a static transaction. Mode 3: Indicates a multiple database transaction with one log record per database. If user logging is enabled for the databases, mode 3 generates multiple entries in the log file in order to mark multiple database transactions. For example, assume that base IDs 11, 12, and 13 are involved in a multiple database transaction. DBBEGIN mode 3 (with base IDs 11, 12, and 13 specified in the baseidlist parameter) generates the following log record sequence: DBBEGIN (11, 1/3) DBBEGIN (12, 2/3) DBBEGIN (13, 3/3) : database updates : DBEND (11, 1/3) DBEND (12, 2/3) DBEND (13, 3/3) where the notations 1/3, 2/3, 3/3 in the log records indicate "first of three," "second of three," and "third of three." Refer to chapter 7 for more details about user logging. Mode 4: Indicates a multiple database transaction. If user logging is enabled for the databases, mode 4 generates one entry in the log file in order to mark multiple database transactions. For example, assume that base IDs 11, 12, and 13 are involved in a multiple database transaction. DBBEGIN mode 4 (with base IDs 11, 12, and 13 specified in the baseidlist parameter) generates the following log record sequence: MDBXBEGIN (11, 12, 13) : database updates : MDBXEND (11, 12, 13) Refer to chapter 7 for more details about user logging. status is the name of an array of 10 halfwords in which TurboIMAGE/XL returns status information. If the procedure executes successfully, the status array contents are: Element Contents 1 If the procedure succeeds, the return status is 0. Table 5-4 describes the contents of element 1 when the procedure does not succeed. 2-4 Unchanged from previous procedure call using this array. 5-10 Procedure call information. Refer to "Library Procedure Error Messages" in appendix A for a description of this information. textlen is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes to be logged. Length can be zero. Discussion DBBEGIN is called to designate the beginning of a sequence of TurboIMAGE/XL procedure calls which are jointly considered a single logical transaction. The transaction is either a static or multiple database transaction, based on the mode. The end of such a sequence is designated by a matching call to DBEND. If the calling process is logging, DBBEGIN causes a log record to be written to the log file which includes such information as the time, date, and user text buffer. DBBEGIN log records are used by the database recovery program DBRECOV to identify the beginning of all logical transactions. DBBEGIN returns an error condition if it is called twice without an intervening call to DBEND or if it is called while a dynamic transaction is still active, whether the process is actually logging or not. Table 5-4. DBBEGIN Return Status Values ---------------------------------------------------------------------------------------------- | Calling Errors: | -11 | Bad database reference. | | | -31 | Bad mode. | | | -139 | Invalid number of base IDs. | | | -140 | Bad base ID list. | | | -141 | All MDBX databases must be on the same system. | | | -142 | All MDBX databases must log to the same log file. | | | -143 | Logging must be enabled or disabled for all MDBX | | | | databases. | | | -144 | MUSTRECOVER must be enabled or disabled for all | | | | MDBX databases. | | | -145 | Roll-back must be enabled or disabled for all MDBX | | | | databases. | | | -151 | Text length greater than 512 bytes. | | | -152 | Transaction is in progress. | | | -221 | Cannot begin transaction when a dynamic transaction | | | | is active. | | | -222 | Only DBXUNDO allowed when a dynamic transaction | | | | encounters an error. | ---------------------------------------------------------------------------------------------- | Communications Errors: | -102 | DSWRITE failure. | | | -106 | Remote 3000 data inconsistent. | | | -107 | NS 3000 or DS 3000 system error. | ---------------------------------------------------------------------------------------------- - Logging System Failures: - -111 - WRITELOG failure. - ---------------------------------------------------------------------------------------------- | Exceptional Conditions: | -193 | DBU control block is full. | | | 63 | DBG disabled; potential damage; only DBCLOSE | | | | allowed. | ---------------------------------------------------------------------------------------------- Consult appendix A for more information about these conditions. DBCLOSE INTRINSIC NUMBER 403 Terminates access to a database or a data set, or rewinds a data set. DBCLOSE is used in conjunction with DBOPEN to establish and terminate access to a database. Syntax DBCLOSE,base,dset,mode,status Parameters base is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.) dset is the name of an array containing the left-justified name of the data set to be closed, or is an integer referencing the data set by number if mode equals 2 or 3. If mode equals 1, this parameter is ignored. The data set name can be up to 16 characters long. If shorter, it must be terminated by a semicolon or a blank. mode is an integer equal to 1, 2, or 3 indicating the type of termination desired as follows: [REV BEG] Mode 1: Access to the database is terminated. Any locks held by this user for this base ID are released. If DBCLOSE mode 1 is called while a dynamic transaction is still active, an error is returned, the transaction is aborted, and the database is closed automatically. You do not need to call DBXEND or DBXUNDO. Mode 2: The data set referenced by the dset array is closed, but locks held in the data set are not released. If DBCLOSE mode 2 is called while a dynamic transaction is still active, an error is returned. You must check the error and decide to use DBXEND, DBXUNDO, or continue with the transaction even if DBCLOSE mode 2 failed. DBXUNDO will abort the entire dynamic transaction. DBXEND will terminate the dynamic transaction; the modifications completed thus far within the transaction will remain in the database.[REV END] Mode 3: If mode equals 3, the data set referenced by the dset array is reinitialized but not closed. If your database is enabled for third-party indexing (TPI), refer to your vendor documentation for additional DBCLOSE mode information. The section on DBUTIL in chapter 8 of this book has a brief description of the TPI option. status is the name of an array of 10 halfwords in which TurboIMAGE/XL returns status information about the procedure. If the procedure executes successfully, the status array contents are: Element Contents 1 If the procedure succeeds, the return status is 0. Table 5-6 describes the contents of element 1 when the procedure does not succeed. 2-4 Unchanged from previous procedure call using this array. 5-10 Procedure call information. Refer to "Library Procedure Error Messages" in appendix A for a description of this information. Discussion [REV BEG] You must call DBCLOSE mode 1 to terminate access to the database when you have completed all the tasks you want to perform. If a process has issued multiple calls to DBOPEN for the same database, only the access path specified in the DBCLOSE base parameter is affected by the call to DBCLOSE.[REV END] The capability to reset and close a data set is provided to perform functions such as reinitializing dynamic status information for a process accessing a particular data set and returning system resources. In both modes 2 and 3, status information is reinitialized, but system resources are returned in mode 2 only. The current list is not reset. Table 5-5 summarizes the functions performed in each mode. Table 5-5. DBCLOSE Modes 2 and 3 Functions ----------------------------------------------------------------------------------------------- | | | | | Function | Mode 2 | Mode 3 | | | | | ----------------------------------------------------------------------------------------------- | | | | | Reinitialize dynamic status information for the | YES | YES | | data set (chain count, forward and backward | | | | pointers, current record number and last return | | | | status). | | | | | | | ----------------------------------------------------------------------------------------------- | | | | | Close the data set. | YES | NO | | | | | ----------------------------------------------------------------------------------------------- | | | | | Release locks held within the data set. | NO | NO | | | | | ----------------------------------------------------------------------------------------------- | | | | | Current list reset. | NO | NO | | | | | ----------------------------------------------------------------------------------------------- Because mode 3 does not close and reopen a data set, it is more efficient than mode 2 if the data set is to be accessed again before the database is closed. [REV BEG] Only mode 3 is allowed within a dynamic transaction; mode 2 will return an error, and mode 1 will abort the transaction.[REV END] If the process is logging, a mode 1 DBCLOSE causes a DBCLOSE log record to be written to the log file. DBCLOSE log records contain such information as the time, date, and user log identification number. A DBCLOSE log record is also written if the process aborts or terminates without closing the database. If the process aborts before completing an active transaction, a special DBEND log record is written prior to the DBCLOSE. DBCLOSE returns an error condition if the process has not completed an active transaction; in other words, the process has called DBBEGIN without a matching call to DBEND. Transactions that abort in this manner are not automatically suppressed by DBRECOV during recovery in order to salvage as many subsequent transactions that may depend on the aborted transaction as possible. Table 5-6. DBCLOSE Return Status Values ---------------------------------------------------------------------------------------------- | File System, Memory | -2 | FCLOSE failure. | | Management, and | -5 | FWRITEDIR failure. | | Transaction Management | -6 | FWRITELABEL failure. | | Failures: | | | ---------------------------------------------------------------------------------------------- | Calling Errors: | -11 | Bad database reference. | | | -21 | Bad data set reference. | | | -31 | Bad mode. | | | -222 | Only DBXUNDO allowed when a dynamic transaction | | | | encounters an error. | | | -232 | Illegal DBCLOSE mode 2 used during an active | | | | dynamic transaction. | | | -235 | Dynamic transaction aborted due to DBCLOSE mode 1; | | | | database closed. | ---------------------------------------------------------------------------------------------- | Communications Errors: | -101 | DSCLOSE failure. | | | -102 | DSWRITE failure. | | | -103 | Remote 3000 stack space insufficient. | | | -106 | Remote 3000 data inconsistent. | | | -107 | NS 3000 or DS 3000 system error. | ---------------------------------------------------------------------------------------------- | Logging System Failures: | -111 | WRITELOG failure. | | | -112 | CLOSELOG failure. | | | -152 | Transaction is in process. | ---------------------------------------------------------------------------------------------- | Exceptional Conditions: | -194 | Invalid DBB. | | | 63 | DBG disabled; potential damage; only DBCLOSE | | | | allowed. | ---------------------------------------------------------------------------------------------- Consult appendix A for more information about these conditions.