TurboIMAGE/XL Database Management System Reference Manual HP e3000 MPE/iX Computer Systems Edition 8 Manufacturing Part Number: 30391-90012 E0701 U.S.A.
Notice The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing or use of this material.
Contents 1. Introduction Data Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rapid Data Retrieval and Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Program Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Program Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents TurboIMAGE/XL and Program Language Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66 Data Item Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 Set Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 Master Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Access Modes and User Class Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Locking Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lock Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Locking Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144 DBCONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Mode 103: Items in Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mode 104: Items in Data Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mode 113: BTREEMODE1 and Wildcard Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mode 201: Set Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mode 202: Set Name . . .
Contents Discussion for Master Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 Discussion for Detail Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 DBUNLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230 INTRINSIC NUMBER 410 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Obtaining Database Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Error Messages and Explanations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Closing the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C ........................................................................ Defining Data Types, Variables, and Intrinsics. . . . . . . . . .
Contents 7. Logging and Recovery Database Utilities Used in Logging and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310 Recovery Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 Logging and Recovery Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314 Logical Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Post-Recovery Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Mirror Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transferring Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining the Mirror Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Text Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398 >PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operation Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . >>ACTIVATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435 >>EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Example Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example (Show All). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example (Show Capacity). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Entryname vs Entrynumber formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .487 Changes in User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .487 Migration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .489 Run-Time TurboIMAGE/XL Control Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Library Procedure Calling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Library Procedure Exceptional Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Library Procedure Abort Condition Messages in I File . . . . . . . . . . . . . . . . . . . . . . . . . . . Utility Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Major Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .689 Moving from MPE/iX to MPE V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .691 Major Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .691 Buffer Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figures Figure 1-1.. How to Use TurboIMAGE/XL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Figure 2-1.. CUSTOMER Data Set Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Figure 2-2.. Master and Detail Data Set Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Figure 2-3.. Master and Detail Data Sets Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Figure 2-4.. Adding Entries to a Sorted Chain . .
Figures Figure G-1.. Sample Job Stream for Starting Logging Cycle. . . . . . . . . . . . . . . . . . . . . . . 675 Figure G-2.. Sample Job Stream for Roll-Forward Recovery . . . . . . . . . . . . . . . . . . . . . . . 676 Figure G-3.. Sample Job Stream for Roll-Back Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . 677 Figure G-4.. Sample Job Stream for Starting Logging Cycle. . . . . . . . . . . . . . . . . . . . . . . 678 Figure G-5.. Sample Job Stream for Backup with Database Open for Access .
Tables Table 2-1.. Manual and Automatic Masters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Table 2-2.. Sample Read/Write Class Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Table 2-3.. Enabling a User Class to Perform a Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Table 2-4.. Sample Read and Write Class Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Table 3-1.. Additional Conventions . .
Tables Table 5-24.. DBXBEGIN Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Table 5-25.. DBXEND Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Table 5-26.. DBXUNDO Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Table 7-1.. Types of Logical Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Table 8-1.. TurboIMAGE/XL Utilities . . .
Preface This manual describes the TurboIMAGE/XL Database Management System for the HP 3000 Series 900 computers. It is the reference document for anyone designing, creating, and maintaining a database and for application programmers writing database access programs. TurboIMAGE/V users will find information and instructions on how to move from TurboIMAGE/V to TurboIMAGE/XL in appendix H.
What's New in this Edition TurboIMAGE/XL version C.09.05 or later includes the following enhancements: DBUTIL prompts for PURGE and ERASE command When purging or erasing a database, DBUTIL will prompt the user with full qualified database name and will wait for a ‘yes or no’ answer to prevent accidentally purging or erasing the wrong database. A JCW, NODBUTCONF, can be set to suppress the prompting so the existing script will not break.
How to Use This Manual The information in this manual is presented in the order you will use the various TurboIMAGE/XL modules. A text discussion of the overall purpose of a module and definitions of terms used to describe the module precede the reference specifications. Each chapter assumes a knowledge of the material presented in preceding chapters. Chapter 1 Introduces the TurboIMAGE/XL Database Management System.
Other Information Sources You may need to consult the following manuals: Migration Process Guide MPE/iX Intrinsics Reference Manual MPE/iX Commands Reference Manual Native Language Programmer's Guide NLS/3000 Reference Manual Query/V Reference Manual NS3000/XL User/Programmer Reference Manual TurboIMAGE/XL Database Management System DBChange Plus User's TurboIMAGE/XL Database Management System DBChange Plus Volume Management Reference Manual Training For current information on available training courses, s
Introduction Data Security 1 Introduction TurboIMAGE/XL is a set of programs and procedures that you can use to define, create, access, and maintain a database. A database is a collection of logically-related files containing both data and structural information. Pointers within the database allow you to gain access to related data and to index data across files. The primary benefit of the TurboIMAGE/XL database management system is time savings.
Introduction Rapid Data Retrieval and Formatting Rapid Data Retrieval and Formatting Conventional file organization frequently requires using multiple file extracts, sorts, and report programs to produce meaningful output. Information requests frequently require weeks to implement, during which time the usefulness of the requested data can decrease.
Introduction Program Maintenance Program Maintenance Throughout the life of a system, processing requirements evolve as the usefulness of the data is explored. As file organization concepts change with the needs of the application, some data restructuring can be done with little impact on existing programs. Changes to the structure of an existing database affect only those programs that process the changed data; no other programs in the system need to be recompiled to reflect the new database structure.
Introduction File Consolidation File Consolidation Most information processing systems that serve more than one application area contain duplicate data. For example, a vendor's name can appear in an Inventory file, an Accounts Payable file, and an Address Label file. The data stored in these three files probably varies slightly from file to file, resulting not only in wasted file space but also inconsistent program output.
Introduction Database Personnel Database Personnel The terms database administrator or database manager, database creator, and database designer can refer to one or more persons involved in administering, creating, or designing the database. The database administrator coordinates database use. This person knows the passwords and can authorize others to use the database by making a password available if it is needed for a particular application.
Introduction How to Use TurboIMAGE/XL How to Use TurboIMAGE/XL The following steps summarize how to use TurboIMAGE/XL. Refer to Figure 1-1. for an illustration of each of the steps. 1. Design the Database. A database designer (system analyst) or team of designers determine what data is required by all the application projects that will share the database. They determine which data should be protected from unauthorized access and how the data will be used.
Introduction How to Use TurboIMAGE/XL Figure 1-1.
Introduction How to Use TurboIMAGE/XL 34 Chapter 1
Database Structure and Protection Database Elements 2 Database Structure and Protection This chapter describes the structure of a TurboIMAGE/XL database. The discussion defines the elements of a database and describes how they are related and how they can be accessed. If you are designing a TurboIMAGE/XL database, use this chapter with chapter 3 which describes how to define a database. Database Elements A database is a named collection of related data.
Database Structure and Protection Database Elements Data Sets A data set is a collection of data entries where each entry contains values for the same data items. For example, a customer data set can contain entries composed of the same nine data items: ACCOUNT, LAST-NAME, INITIAL, STREET-ADDRESS, CITY, STATE, ZIP, and CREDIT-RATING. Normally, each data set is associated with some real-world entity, such as orders, customers, employees, and so forth. A database can contain up to 240 data sets.
Database Structure and Protection Data Set Types and Relationships Figure 2-1. CUSTOMER Data Set Sample Data Set Types and Relationships A TurboIMAGE/XL data set is either a master or a detail data set; these data sets are described in this section. Figure 2-2. illustrates the relationships and the types of six data sets in the ORDERS database. Master data sets are identified by triangles and detail data sets by trapezoids.
Database Structure and Protection Data Set Types and Relationships Figure 2-2. Master and Detail Data Set Relationships Master Data Sets Master data sets have the following characteristics: • They are used to keep information relating to a uniquely identifiable entity. For example, the CUSTOMER data set contains information describing customers. • They allow for rapid retrieval of a data entry because one of the data items in the entry, called the key item, determines the location of the data entry.
Database Structure and Protection Data Set Types and Relationships Figure 2-3.
Database Structure and Protection Data Set Types and Relationships Automatic and Manual Masters A master data set is defined as either automatic or manual. The characteristics of both are described below: Table 2-1. Manual and Automatic Masters Manual Master Automatic Master Can be standalone (not related to any detail data set) or can serve as an index for one or more detail data sets. Must serve as an index to one or more detail data sets. Must contain a key item and can contain other data items.
Database Structure and Protection Data Set Types and Relationships Manual versus Automatic Data Sets Database designers can choose a manual or automatic master data set depending on the following: • Manual masters help ensure that valid search item values are entered for related detail entries. They can also serve as indexes to detail data sets.
Database Structure and Protection Data Set Types and Relationships Because a detail data set can contain as many as 16 search items, it can be related to at most 16 master data sets. Each master-to-detail relationship must be relative to a different detail search item. The SALES data set is related to the CUSTOMER, PRODUCT, and DATE-MASTER data sets. A detail data set can be multi-indexed by a single master data set. For example, SALES is indexed twice by DATE-MASTER.
Database Structure and Protection Data Set Types and Relationships follows all existing entries in the chain. If the path has a sort item, the entry is inserted in the chain according to the value of that item. If the entry's sort item value matches the sort item values of other entries in the chain, the position of the entry is determined by an extended sort field consisting of the sort item value and the values of all items following the sort item in the entry.
Database Structure and Protection Data Set Types and Relationships SALES03 is the Chunk Control file. It has information about the other files, but no user data of its own. The remaining files in the data set are called Chunk Data files or chunks. To specify a jumbo data set, the JUMBO option must be included in the schema before defining a jumbo data set. Then any data set whose capacity is greater than 4 GB automatically becomes a jumbo data set.
Database Structure and Protection Data Set Types and Relationships Figure 2-4.
Database Structure and Protection Data Set Types and Relationships The ORDERS Database Figures 2-5 and 2-6 illustrate the complete ORDERS database. Figure 2-5. lists the data items within each data set as defined in the schematic of the ORDERS database shown in Figure 2-2. The data types (in parentheses) are described in chapter 3 with the item part of the schema. Paths are indicated by arrows. CUSTOMER, SUP-MASTER, PRODUCT, and DATE-MASTER are master data sets and SALES and INVENTORY are detail data sets.
Database Structure and Protection Data Set Types and Relationships Figure 2-6.
Database Structure and Protection Database Files Database Files Database elements are stored in privileged MPE/iX disk files. In addition to the root file which contains the database definition, other files that contain data are called data sets. Root File The root file serves as a common point of entry to, and a source of information about, the database. The root file is a single-extent MPE/iX disk file; that is, the entire file occupies contiguous sectors on the disk.
Database Structure and Protection Database Files MPE/iX file system constraints. Blocks The media records in a data file physically reside together in a group called a block. Each block corresponds to one MPE file record. The number of media records in each block is called the blocking factor. The Schema Processor determines the blocking factor during creation of the root file. Chapter 3 contains more information about block size and blocking factors. The format of blocks is given in chapter 10.
Database Structure and Protection Protecting the Database Protecting the Database TurboIMAGE/XL prevents unauthorized persons from gaining access to the database. It provides external protection through the MPE/iX privileged file, account, and group constructs and, in addition, provides the database designer and database manager with methods to refine security within the database. Privileged File Protection All TurboIMAGE/XL database files are privileged files.
Database Structure and Protection Protecting the Database Defining Database Security After the data items, data sets, and paths for the database have been defined, database security can be addressed. Defining security involves the following two steps: 1. Defining user classes and passwords 2. Setting up read and write class lists User Classes and Passwords Consider who will be using the database.
Database Structure and Protection Protecting the Database The combinations of the data set and data item user class lists result in one of the following five types of access: • Write access • Update access • Read access • No access • Creator-only access Write Access A user class that has write access can add entries to or delete from the data set. Write access means that update and read access are also granted, and is sometimes referred to as full data access.
Database Structure and Protection Protecting the Database Specify no access for a user class to an entire data set by excluding the user class from the read and write class lists of the data set. To allow no access to a specific data item, include the user class in the read class list of the data set and exclude the user class from the read and write class lists of the data item. Note that the read or write portions of the user class list can be left empty; this is known as a null list.
Database Structure and Protection Protecting the Database Database Access Modes and Data Set Write Lists Before you can gain access to a database, you must open it specifying a password that establishes your user class number and an access mode that defines the type of database tasks you want to perform. Access modes are described in chapter 4 with the instructions for opening a database.
Database Structure and Protection Protecting the Database Table 2-3. Enabling a User Class to Perform a Task Task Read Data Item Update Data Item Add or Delete Data Entries Database Access Mode 1, 3, or 4 Data Set\Security Rules Data Item\Security Rules User class must be in data set write list, or User class must be in data set read list and pass data item security. User class must be in read or write list.
Database Structure and Protection Protecting the Database Assuming the database designer has granted only read access at the data set level as summarized above, control at the data item level is established in the following ways: • Specify the user class number in the data item read class list (or omit both read and write class lists entirely). This grants the user class read access to the data item. • Specify the user class number in the data item write class list.
Database Structure and Protection Protecting the Database Figure 2-8.
Database Structure and Protection Protecting the Database Table 2-4. contains more illustrations of the effects of read and write class lists. These are general examples that are not based on the ORDERS database shown in this manual. Note that these examples take into account the effects of the access mode in which the database is opened. The database creator and user class 9 (in access mode 1, 3, or 4) have complete access to data set 1, but only the creator has complete access to data set 2.
Database Structure and Protection Protecting the Database User Classes and Locking TurboIMAGE/XL does not consider user classes when locking a database entity. Any data set or any data item can be referenced in a lock request by any user of a database regardless of his or her user class. Protection in Relation to Library Procedures All access to a database is achieved through database control blocks that reside in privileged MPE/iX files which are not directly accessible to database users.
Database Structure and Protection Protecting the Database maintenance word. • Unrecoverable disk or tape problems are treated as functional failures rather than limited successes and result in program termination.
Defining a Database 3 Defining a Database After the database has been designed, it must be described with the database description language and processed by the Schema Processor to create the root file. Figure 3-1. illustrates the steps in defining the database. Figure 3-1.
Defining a Database Database Description Language Database Description Language The database description, called a schema, can exist in the MPE/iX system as an ASCII file. Regardless of the actual physical record size of the file, the Schema Processor reads, prints, and processes only the first 72 characters of each record. Any remaining character positions in the record are available for your convenience, to be used for comments or collating information.
Defining a Database Database Description Language END. The database name is an alphanumeric string from 1 to 6 characters. The first character must be alphabetic. The language is the native language definition name or number for the database. Refer to the Native Language Support Programmer's Guide for further information. The default language is NATIVE-3000 which uses the US ASCII character set. NOTE When using DBLOAD, the database language must match the language ID stored in the backup media.
Defining a Database Password Part Password Part The password part defines user classes and passwords. Chapter 2 contains a description of user classes and how they are used to protect data elements from unauthorized access. Syntax user class number [password]; . . . user class number [password]; Parameters user class number is an integer between 1 and 63, inclusive. User class numbers must be unique within the password part.
Defining a Database Item Part Item Part The item part defines data items including the data item name, length, and the user classes that have access to the item. The data set(s) in which the data item appears is defined in the set part definition. Syntax item name, [sub-item count] type designator [sub-item length] [(read class list/write class list)]; Parameters item name is the data item name. It must be a valid TurboIMAGE/XL data name as described earlier in Table 3-1..
Defining a Database Item Part depends upon the type designator and can be a halfword, a byte, or a nibble. A halfword is 16 bits, a byte is eight bits, and a nibble is four bits or a half-byte. NOTE In this manual, a word is a 32-bit storage unit and a halfword is a 16-bit storage unit. One byte is 8-bits. Table 3-2. describes the type designators and the unit of measure used for each. Table 3-2.
Defining a Database Item Part a specific type of TurboIMAGE/XL data item. However, for consistency, R-type items are recommended for storing item values in HP 3000 real format and E-type items are recommended for storing values in IEEE format. Table 3-3. relates TurboIMAGE/XL type designators and sub-item lengths to the data types typically used to process them in the available programming languages.
Defining a Database Item Part Table 3-3. TurboIMAGE/XL Data Types and Programming Languages Data\ Type BBASIC R2d FORTRAN 77 Pascal Short real Real Real R4d Real Double precision Longreala U String char Display Picture A Character Char [subrange] Character X String char Display Picture X Character Char Character char[n] Display Picture X(n) Xn C COBOL II Z Display Picture S9 Zn Display Picture S9(n) RPG Packed array [1..n] of char Character Packed array [1..
Defining a Database Item Part PICTURE clause specifies MINUS sign: Sign is 11012 • For values entered using RPG: NO sign or PLUS specified: Sign is 11002 MINUS sign specified: Sign is 11012 When using TurboIMAGE/XL to locate all packed data items with a particular value (as described under "DBLOCK" in chapter 5), you must be aware that TurboIMAGE/XL differentiates between unsigned, positive, and negative data items with the same absolute value.
Defining a Database Item Part Table 3-4. shows examples of item parts. Table 3-4. Examples of an Item Part Item Example Description A,I2; 32-bit signed integer. MELVIN,3I(1,20/44); Compound item. Three single halfword signed integers. Read classes are 1 and 20; write class is 44. (Write classes can also read.) BLEVET,J; Single halfword signed integer between −9999 and 9999 (COBOL ΙΙ). COSTS,2X10; Compound item. Two 10-character ASCII strings. DATE,X6; Six-character ASCII string.
Defining a Database Set Part Set Part The set part of the schema defines data sets. It indicates which data items listed in the item part belong to which sets and links the master data sets to the detail data sets by specifying key and search items. In addition, it defines security at the set level and at the item level within each data set. Master Data Sets The set part syntax and parameters for master data sets are provided below.
Defining a Database Set Part item name is the name of a data item defined in the item part. path count is an integer between 0 and 64, inclusive, which is used with the key item only. It indicates the number of paths that will be established to various detail data sets. Refer to chapter 2 for more information about paths. A path count must be specified for one, and only one, item in the master set. A zero path count can be used with a manual master data item to indicate the key item.
Defining a Database Set Part the data set, or is zero, but the initial capacity is greater than zero, then the increment for each expansion is defaulted to ten percent (10%) of the initial capacity for the data set. If the initial capacity is equal to the maximum capacity, or the initial capacity is zero, then this indicates the data set cannot be expanded and increment is ignored.
Defining a Database Set Part performance of TurboIMAGE/XL. NOTE For existing databases, use DBChange Plus or a third-party utility to specify the expansion parameters. Detail Data Sets The set part syntax and parameters for detail data sets are provided below. Syntax {NAME: N: }set name, D[ETAIL]][(read class list/write class list)][,device class]; {ENTRY: E: } item name [([!] master set name [(sort item name) ])], . . .
Defining a Database Set Part detail data set. If no data items have a master name following them, the detail is not related to any master. In this case, the combined length of all data items in the data set must equal or exceed two halfwords. sort item name is the name of a detail data item of type U, K, or X which is a part of the data set being defined. A sort item defines a sorted path. Each entry added to a chain of a sorted path will be linked logically in ascending order of the sort item values.
Defining a Database Set Part cannot exceed the maximum entry count minus the initial allocation. The increment is an optional parameter. If the increment is not specified for the data set, or is zero, but the initial capacity is greater than zero, then the increment for each expansion is defaulted to ten percent (10%) of the initial capacity for the data set.
Defining a Database Set Part appear in more than one data set, you can use the same data item name and definition for both the master key items and detail search items. For example, the data item ACCOUNT is used as the key item in the CUSTOMER master and as the search item in the SALES detail data sets. If you want to make a distinction between the search items, they can be defined separately. An example of this technique is found in the ORDERS database.
Defining a Database Schema Processor Operation Schema Processor Operation The Schema Processor is a program that accepts a textfile containing the schema as input, scans the schema and if no errors are detected, optionally produces a root file. The Schema Processor prints a heading, an optional list of the schema, and summary information on a listfile. The Schema Processor executes as either an MPE/iX job or session.
Defining a Database Schema Processor Operation Table 3-6. shows sample combinations of MPE/iX RUN and FILE commands that can be used to initiate DBSCHEMA execution. Table 3-6. Examples of RUN and FILE Commands :RUN DBSCHEMA.PUB.SYS Uses all default files. Prompts for lines of schema in session mode. :FILE DBSTEXT=ORDERSSC :RUN DBSCHEMA.PUB.SYS;PARM=1 Processes schema from a user disk text file named ORDERSSC. Outputs listing to $STDLIST. :FILE DBSLIST;DEV=LP :RUN DBSCHEMA.PUB.
Defining a Database Schema Processor Operation The Schema Processor can also be executed in batch mode. See "Schema Processor Commands" later in this chapter. Figure 3-2. Sample Schema Creation Session 1 2 3 4 5 6 :HELLO USER.ACCOUNT HP3000 RELEASE: B.30.00 ... TUE, SEP 10, 1991, 1:49 PM MPE/iX HP31900 B.08.14 Copyright (C) Hewlett-Packard 1987. :EDITOR HP32201A.00.00 EDIT/3000 TUE, SEP 10, 1991, 2:07 PM (C) HEWLETT-PACKARD CO.
Defining a Database Schema Processor Commands Schema Processor Commands TurboIMAGE/XL provides several commands that you can use anywhere in the schema to specify options available while processing the schema. The commands are: $PAGE, $TITLE, and $CONTROL. The dollar sign ($) must always be the first character of the record, immediately followed by the command name, which must be completely spelled out.
Defining a Database $PAGE $PAGE The $PAGE command causes the list file to eject to the top of the next page, print character-strings that you can optionally specify, and skip two more lines before continuing the listing. Syntax $PAGE [["character-string"],...] Parameters character-string is a list of characters enclosed in quotation marks. When the command is executed, the quotation marks are stripped and the character-strings are concatenated.
Defining a Database $TITLE $TITLE The $TITLE command specifies a list of characters to be printed each time a heading is printed on a new page. It does not cause a page eject. Syntax $TITLE [["character-string"],...] Parameters character-string is a list of characters enclosed in quotation marks. When the command is executed, the quotation marks are stripped and the character-strings are concatenated. A quotation mark within a character-string is specified by a pair of quotation marks.
Defining a Database $CONTROL $CONTROL The $CONTROL command allows you to specify options in relation to processing the schema. Syntax $CONTROL [LIST NOLIST] [,ERRORS=nnn][,LINES=nnnn][,ROOT ,NOROOT] [,BLOCKMAX=nnnn] [,TABLE ,NOTABLE] [,JUMBO ,NOJUMBO] [, ODDPALLOWED] [,UNSIGNED BLOCKS ,NOUNDIGNED BLOCKS] [,LARGESET] Parameters LIST causes each source record of the schema to be printed on the list file. NOLIST specifies that only source records with errors be printed on the list file.
Defining a Database $CONTROL format used by TurboIMAGE/XL) as part of block number. So the maximum possible data set size can go up to 80 GB. LARGESET Database will use entry number instead of entryname as the internal pointer format, that will allow the data set size to go beyond 80 GB. For more detail please refer to Chapter 10, large size data set in TurboIMAGE/XL section.. Description The default parameters are LIST, ROOT, TABLE, NOUNSIGNED BLOCKS, and NOJUMBO.
Defining a Database Schema Processor Output Schema Processor Output The Schema Processor prints the following heading on the first page of the listing: PAGE 1 HEWLETT-PACKARD 30391C.05.00 TurboIMAGE/3000: DBSCHEMA MON, JAN 10, 1994, 3:32 PM (C) HEWLETT-PACKARD CO. 1987 If your standard output device ($STDLIST) is different from the list file, an abbreviated product identification is also printed on $STDLIST.
Defining a Database Schema Processor Output Table 3-7. Data Set Summary Table Information Headings Description DATA SET NAME The name of the data set. TYPE A for automatic, M for manual, or D for detail. A small letter "i" adjacent to the "M" or "A" indicates the data set has a B-Tree index on the key item. FLD CNT The number of data items (fields) in each entry of the data set. PT CT Path count. For a master data set, this is the number of paths specified for the data set key item.
Defining a Database Schema Processor Output commands. The error count is also sent to $STDLIST if it is different from the list file. • If no schema syntax or logical errors are encountered, a third line is printed. The form of this line is: ROOT LENGTH: r BUFFER LENGTH: b TRAILER LENGTH: t ROOT LENGTH is the length in halfwords of the body of the root file.
Defining a Database Schema Processor Output Schema Processor Example Figure 3-5. contains the list file output printed when the schema of the sample ORDERS database is processed. The database has 5 passwords and contains 23 data item definitions and 6 data set definitions. The Schema Processor summary information is printed following the schema. Figure 3-5. ORDERS Database Schema ORDERS Database Schema PAGE 1 HEWLETT-PACKARD 30391C.05.
Defining a Database Schema Processor Output NAME: ENTRY: CAPACITY: PAGE 2 CUSTOMER,MANUAL /INDEXED (14/11,18),DISC1; ACCOUNT(1), LAST-NAME, FIRST-NAME, INITIAL, STREET-ADDRESS, CITY, STATE, ZIP, CREDIT-RATING; 201; <> SCHEMA FOR DATABASE ORDERS NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: PRODUCT,MANUAL(13,14/12,18),DISC1;<> STOCK#(2), DESCRIPTION; 300; SUP-MASTER,MANUAL(13/12,18),DISC1; <> SUPPLIER
Defining a Database Schema Processor Output DATA SET NAME DATE-MASTER CUSTOMER PRODUCT SUP-MASTER INVENTORY SALES TYPE FLD CNT PT CT ENTR LGTH A 1 3 3 Mi 9 1 41 M 2 2 14 M 5 1 31 D 6 3 20 INITIAL CAPACITY: 450 D 8 4 19 INITIAL CAPACITY: 504 MED REC 26 52 31 42 32 35 MAXIMUM CAPACITY BLK FAC BLK DISC LGTH SPACE 365 19 496 96 201 7 365 96 300 16 497 80 201 12 505 80 1800 15 481 128 INCREMENT ENTRIES: 45 1008 14 491 160 INCREMENT ENTRIES: 112 TOTAL DISC SECTORS INCLUDING ROOT: 672 NUMBER OF ERROR
Defining a Database Schema Processor Output 92 Chapter 3
Using the Database Opening the Database 4 Using the Database After you design the database, create the root file, and build the data sets, you can write application programs to enter and use the data. Programs written in BBASIC, C, COBOL II, FORTRAN 77, or Pascal gain access to the database through calls to TurboIMAGE/XL procedures. RPG programs contain specifications used by the Report Program Generator to make calls to the TurboIMAGE/XL procedures for you.
Using the Database Opening the Database Database Control Blocks TurboIMAGE/XL executes using data stored in different types of control blocks stored in privileged mapped files or virtual data objects: the Database System Control Block (DBS), the Database Globals Control Block (DBG), the Database Buffer Area Control Block (DBB), the Database User Local Control Block (DBU), the Remote Database Control Block (DBR), Database User Local Index Control Block (DBUX), the Lock Table (TURBOLKT), Global Dynamic Multi
Using the Database Opening the Database (63 per database) depending on the availability of system resources. The DBUX remains allocated until the user's process is terminated. • The TurboLock Table is a permanent file, TURBOLKT.PUB.SYS, that is created by DBOPEN (if it does not exist beforehand). Thereafter, it is opened when the first user opens any database on the system. It is purged when the system is rebooted. Each system has only one TURBOLKT file.
Using the Database Opening the Database detail data set search and sort items to be updated and which is discussed later in this chapter, is not available in this mode. • Modify access modes (1, 3, and 4) allow updates and permit the user to add and delete entries. For access modes 1, 3, and 4 only, users can update the values of detail data set search and sort items if the critical item update (CIUPDATE) option settings for the database and the current process permit them to do so.
Using the Database Opening the Database Here is a summary of the acceptable environments: • Multiple access mode 1 and access mode 5 users • Multiple access mode 6 and access mode 2 users • Multiple access mode 6 users and one access mode 4 user • Multiple access mode 6 and access mode 8 users • One access mode 3 user • One access mode 7 user Subsets of these environments are also allowed. For example, all users can be access mode 5, 6, or 8 users; or there could be one access mode 1 user; and so on.
Using the Database Opening the Database option, which can permit you to update the values of detail data set search and sort items, is not available in this mode. Therefore, the access mode 2 user is able to read all data entries and update some data entries, but is not permitted to add or delete data entries in any data set. The programmer must be aware of the possibility that other access mode 2 users are simultaneously updating data entries.
Using the Database Opening the Database • Access Mode 7. The database is opened for exclusive read access. No other users can access the database concurrently. Access mode 7 operates the same as access mode 3, except that the DBUPDATE, DBPUT, and DBDELETE procedures, which alter the database, are disabled for the access mode 7 user. • Access Mode 8. The database is opened for shared read access. Concurrent users must either be in access mode 6 or 8, or using the TurboIMAGE/XL utility, DBSTORE.
Using the Database Opening the Database Access Mode 2 Can be used if processes are allowed to update the database concurrently. Locking should be used to coordinate updates. The critical item update (CIUPDATE) option, which can permit you to update the values of detail data set search and sort items, is not available in this mode. • Programs that only locate and read or report on information in the database should open with one of the read-only access modes.
Using the Database Opening the Database The DBBEGIN and DBEND intrinsics are used to designate or block logical, static transactions for logging and recovery purposes. The DBXBEGIN and DBXEND intrinsics are used to mark logical, dynamic transactions spanning one database, or multiple databases up to fifteen, for dynamic roll-back recovery. Refer to Table 4-5. later in this chapter for a definition of TurboIMAGE/XL transaction types.
Using the Database Entering Data in the Database Entering Data in the Database Data is added to the database, one entry at a time, using the DBPUT procedure. You can add data entries to manual master and detail data sets. Entries are automatically added to automatic master data sets when you add entries to the associated detail data sets. To add an entry, you specify the data set name or number, a list of data items in the set, and the name of a buffer containing values for these items.
Using the Database Entering Data in the Database Figure 4-1. Sample Data Entries from ORDERS Database Coordinating Additions to a Database A single DBPUT call involves chain maintenance and other activity that can span multiple data sets and multiple blocks within data sets even if an application is only adding entries to a single data set.
Using the Database Entering Data in the Database be used to establish a lock covering the entry to be inserted. For detail data sets, this can be a data entry, data set, or database lock. For master data sets, this can be a data set or a database lock. Note that the locking mechanism accepts a request to lock a data entry that does not yet exist; therefore, you can lock a data entry before you add it.
Using the Database Reading the Data Reading the Data When you read data from the database, you specify which data set and which entry in that data set you want. If the user class number with which you opened the database grants you read access, you can read the entire entry or specific data items from the entry. You specify the items to be read and the array where the values should be stored. You can read items or entries in any access mode if your user class grants read access to the data element.
Using the Database Reading the Data Figure 4-2. Reading Access Methods (DBGET Procedure) Directed Access The directed access method of selecting the data entry to be read requires that you specify the record number of that entry. Record numbers are returned in status halfwords 3-4 by a successful call to the TurboIMAGE/XL intrinsic DBPUT (refer to the discussion of DBPUT in chapter 5).
Using the Database Reading the Data During directed access the calling program specifies a record number or address. If any entry exists at this address, TurboIMAGE/XL returns the values for the data items requested in the calling program's buffer. If no such entry exists, the program is notified by an exceptional condition return, such as end-of-file, beginning-of-file, or no entry.
Using the Database Reading the Data effectively allows you to use a data set in the same way you would use an MPE/iX file. Thus, you have the advantages of TurboIMAGE/XL database organization and the efficiency of serial access. NOTE When using serial access with master data sets, you should be aware of migrating secondaries. These are described in chapter 10. Locking.
Using the Database Reading the Data program can use the chained access method of retrieving data. You can use both forward and backward chained access. In either case, if there are no more entries in the chain when you request the next one, DBGET returns an exceptional condition, beginning-of-chain or end-of-chain for backward and forward access, respectively. Chained access to master data sets retrieves the next entry in the current synonym chain.
Using the Database Reading the Data Rereading the Current Record The DBGET library procedure allows you to read the entry from the most recently accessed record again. You may want to do this in a program that has unlocked the data entry and locked it again and needs to check if the contents of the current entry have been changed.
Using the Database Updating Data Updating Data TurboIMAGE/XL allows you to change the values of data items if the user class number with which you opened the database grants this capability to you. These items cannot be master data set key items or detail data set search or sort items, unless you take advantage of the critical item update (CIUPDATE) option.
Using the Database Updating Data NOTE To avoid locking around terminal reads, you may need to establish the lock, perform a mode 1 DBGET, check the value, update the entry, then remove the lock. The password you use to open the database must grant update capability to the data items you intend to change.
Using the Database Updating Data DBCONTROL in mode 6 disables the option. Using DBCONTROL modes 5 and 6 does not alter the permanent setting set with the DBUTIL >>SET command. The database must be opened in access mode 1, 3, or 4; and your user class must have write access at the set level, or both read access at the set level and write access at the item level.
Using the Database Updating Data NOTE If this is a dynamic transaction, a call to DBXUNDO must be processed if an error occurs or if the transaction needs to be rolled back for any other reason. TurboIMAGE/XL will not go on to the next transaction in the event of a transaction abort unless an intervening call to DBXUNDO occurs. 11.If the status code is zero and this is a logical transaction, call DBEND or, alternatively, DBXEND to declare the end of the modifications.
Using the Database Deleting Data Entries Deleting Data Entries Data is deleted from the database using the DBDELETE procedure. You can delete entries from manual master and detail data sets. Entries are automatically deleted from automatic master data sets as explained below. To delete an entry from a data set, you must first locate the entry to be deleted by reading it with the DBGET library procedure, or the DBFIND and DBGET procedures if it is advantageous to use chained access to locate the entry.
Using the Database Deleting Data Entries For additional information, refer to the discussion of DBDELETE in chapter 5 and the description of the DBUTIL >>ENABLE command in chapter 8. Access Modes and User Class Numbers To update data items, the database must be opened with access mode 1, 3, or 4.
Using the Database Using the Locking Facility Using the Locking Facility The DBLOCK procedure applies a logical lock to a database or one or more data sets or data entries. The DBUNLOCK procedure releases these locks. Locking can be viewed as a means of communication and control to be used by mutually cooperating users. The locking facility provides a method for protecting the logical integrity of the data shared in a database.
Using the Database Using the Locking Facility With the exception of compound items, any data item can be used in a lock descriptor; that is, the lock item need not be a search item. TurboIMAGE/XL does not require that you have read or write access to a data set or data item in order to specify it in a lock request. A process can specify any number of lock descriptors with a single DBLOCK call.
Using the Database Using the Locking Facility Figure 4-3. Lock Descriptor List Conditional and Unconditional Locking You can request conditional or unconditional locking. If you request unconditional locking, TurboIMAGE/XL returns control to your calling program only after the specified entity has been locked. If you request conditional locking, TurboIMAGE/XL returns immediately. In this case, the condition code must be examined to determine whether or not the requested locks have been applied.
Using the Database Using the Locking Facility Automatic Masters When adding or deleting entries from a detail data set, you need not have locks covering the implicit additions or deletions that occur in any associated automatic masters. Locking Levels Locking can be viewed as operating on three levels: the whole database, whole data sets, or data entries. TurboIMAGE/XL allows mixed levels of locking. For example, one user could be locking data entries and another locking the data set.
Using the Database Using the Locking Facility entries. At system design time, a compromise must be made between the benefits of low-level locking and the extra programming effort required. Data entry locking should give the best concurrency; however, there are situations in which the extra programming effort for data entry locking is not worthwhile. Concurrency is least optimum at the higher level of the lock.
Using the Database Using the Locking Facility or the dynamic transaction is aborted. NOTE A call to DBXUNDO must be processed if an error occurs or if the transaction needs to be rolled back for any other reason, because TurboIMAGE/XL will not go on to the next transaction in the event of a transaction abort unless an intervening call to DBXUNDO occurs. Furthermore, if DBXUNDO was used to roll back a transaction, the program logic should ensure that the subsequent call to DBXEND is not processed.
Using the Database Using the Locking Facility Table 4-4. Locking in Shared-Access Environments Action Recommended Locks Chained DBGET calls Lock all data entries in the chain. This usually requires one lock descriptor. Serial DBGET calls Lock the data set. Update a data entry (DBUPDATE) Lock the data entry before calling DBGET to read the data entry. Unlock after the update. Directed reads (DBGET calls) These are not recommended in a shared environment.
Using the Database Using the Locking Facility 4. DBPUT a new data entry in SUP-MASTER data set. 5. DBPUT a new data entry in INVENTORY data set for STOCK# = 4444A33B. 6. DBEND. 7. DBUNLOCK. The locking in the above example was done around the entire transaction to maintain data consistency during the multistep transaction. Interactively Modify a Customer Account Order 1. DBLOCK SALES: ACCOUNT = 89393899. 2.
Using the Database Using the Locking Facility recommended unless absolutely necessary. Users whose programs have MR capability and issue multiple DBLOCK calls are responsible for deadlock prevention. This type of locking must be done very carefully. Recovery from a deadlock requires a restart of the operating system.
Using the Database TurboIMAGE/XL Logging Services TurboIMAGE/XL Logging Services TurboIMAGE/XL provides logging through the following two MPE/iX services: • Transaction Management (XM) logging • User logging XM logging is used to ensure the physical integrity of the database. It is transparent to the user because it is automatically enabled unless AUTODEFER is enabled. Dynamic roll-back recovery (explained in chapter 7) works in conjunction with XM and ensures the logical integrity of the database.
Using the Database TurboIMAGE/XL Logging Services DBXBEGIN, DBXEND, and DBXUNDO. In addition, DBQUIESCE procedures called by TrueOnline Backup to quiesce and unquiesce the database are also logged to the logging file. TurboIMAGE/XL calls the MPE/iX logging intrinsics OPENLOG, WRITELOG, and CLOSELOG in order to log information to the log file. When a database is opened, DBOPEN calls the OPENLOG intrinsic using the log identifier and password stored in the database root file.
Using the Database TurboIMAGE/XL Logging Services In the event of a system failure and subsequent recovery, only complete logical transactions are re-executed, returning the database to a consistent state. Therefore, it is essential that an application program use the intrinsics DBBEGIN and DBEND, or DBXBEGIN and DBXEND, to mark the beginning and end of a sequence of calls which constitute a single logical transaction.
Using the Database Obtaining Database Structure Information Obtaining Database Structure Information The DBINFO library procedure allows you to acquire information programmatically about the database. It provides information about database settings, data items, data sets, data paths, B-Tree indices, and third-party indices. The information returned is restricted by the user class number and access mode established when the database is opened.
Using the Database Obtaining Database Structure Information set is a detail set, the information includes the master data set number of the related master data set, the detail search item number and sort item number for each path. • Determine the key item number of a master data set or the search item number for the primary path of the detail and the data set number of the related master. In either case, if the search item is inaccessible to the current user, no information is returned.
Using the Database Closing the Database or a Data Set Closing the Database or a Data Set After you have completed all the tasks with the database, use the DBCLOSE library procedure to terminate access to the database. When DBCLOSE is used for this purpose, all data sets and the root file are closed, and the DBU control block is released to the MPE/iX system. If there are no other concurrent users of the database, the DBB and DBG control blocks are also released.
Using the Database Checking the Status of a Procedure Checking the Status of a Procedure Each time a procedure is called, TurboIMAGE/XL returns status information in a buffer specified by the calling program and, if the program is in Compatibility Mode, sets the CM condition code maintained by MPE/iX.
Using the Database Interpreting Errors Interpreting Errors TurboIMAGE/XL provides two library procedures, DBEXPLAIN and DBERROR, which can be used to interpret status information programmatically. DBEXPLAIN prints on the $STDLIST device an English language error message which includes the name of the database and the name of the procedure that returned the status information. DBERROR returns the English language error message contained in a buffer specified by the calling program.
Using the Database Interpreting Errors 134 Chapter 4
TurboIMAGE/XL Library Procedures 5 TurboIMAGE/XL Library Procedures 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.
TurboIMAGE/XL Library Procedures Using TurboIMAGE/XL Intrinsics Using TurboIMAGE/XL Intrinsics 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.
TurboIMAGE/XL Library Procedures Using TurboIMAGE/XL Intrinsics Table 5-1. TurboIMAGE/XL Procedures Procedure Function 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.
TurboIMAGE/XL Library Procedures Using TurboIMAGE/XL Intrinsics 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.
TurboIMAGE/XL Library Procedures DBBEGIN 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.
TurboIMAGE/XL Library Procedures DBBEGIN 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.
TurboIMAGE/XL Library Procedures DBBEGIN textlen 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. 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.
TurboIMAGE/XL Library Procedures DBBEGIN Table 5-4. DBBEGIN Return Status Values 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. -332 Error in QLOCK table operation. 62 DBU full. 63 DBG disabled; potential damage; only DBCLOSE allowed. Consult appendix A for more information about these conditions.
TurboIMAGE/XL Library Procedures DBCLOSE 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.
TurboIMAGE/XL Library Procedures DBCLOSE 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-5. 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.
TurboIMAGE/XL Library Procedures 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.
TurboIMAGE/XL Library Procedures DBCONTROL DBCONTROL INTRINSIC NUMBER 411 Allows a process accessing the database to have control over some DBUTIL options. In exclusive mode (DBOPEN mode 3), DBCONTROL can be used to enable or disable the deferred output (AUTODEFER) option and perform several B-Tree related tasks such as adding, dropping, or rebuilding a B-Tree index.
TurboIMAGE/XL Library Procedures DBCONTROL or the database is closed. You can call mode 5 successfully if the CIUPDATE setting for the database equals ON, but the call has no impact on the option setting for the current process unless an intervening call to DBCONTROL mode 6 disabled the option. If the CIUPDATE flag is DISALLOWED, a call to mode 5 returns an error. The CIUPDATE option is available only in database access modes 1, 3, and 4. Mode 6: Disable the critical item update option.
TurboIMAGE/XL Library Procedures DBCONTROL 148 Mode 14: Allow a privileged mode caller to set BTREEMODE1 option to ON or OFF and set wildcard character for the database (permanent). Refer to chapter 11, "B-Tree Indices" for the qualifier layout. Mode 15: Enable B-Tree wildcard search for DBFIND mode 1, X and U types, for the master data set's key item and its corresponding search items in details, if the key item has a B-Tree index.
TurboIMAGE/XL Library Procedures DBCONTROL sets with an item and DBINFO mode 301 returns paths for a specific data set. If a user program allocates arrays to store the data returned from above DBINFO calls and the size of the arrays are defined by the old TurboIMAGE/XL item/set limit. Then a database with new item/set limit may cause the program to abort.
TurboIMAGE/XL Library Procedures DBCONTROL Discussion DBCONTROL can be called by a program for the following purposes: • To enable or disable the AUTODEFER option for the current mode 3 DBOPEN. • To enable or disable the critical item update option for the current process accessing the database in mode 1, 3, or 4 depending on the CIUPDATE setting for the database. • To enable or disable the HWMPUT for the current DBOPEN. • To include a database in dynamic multiple database transaction.
TurboIMAGE/XL Library Procedures DBCONTROL NOTE If HWMPUT is enabled, DBPUT will not inform you when it has reached the end of file and has started using the delete chain head. In general, it is not a good practice to toggle HWMPUT. If you plan to use roll-forward recovery, do not toggle HWMPUT after storing the database. By default, DBPUT first checks the delete chain head, then if it is empty, DBPUT places the new entry at the high-water mark.
TurboIMAGE/XL Library Procedures DBCONTROL Table 5-7. DBCONTROL Return Status Values Calling Errors: -11 Bad database reference. -14 Illegal intrinsic in current access mode. -31 Bad mode. -80 Output deferred not allowed when ILR enabled. -81 Output deferred not allowed with roll-back enabled. -82 CIUPDATE is set to DISALLOWED; cannot use critical item update. -222 Only DBXUNDO allowed when a dynamic transaction encounters an error.
TurboIMAGE/XL Library Procedures DBDELETE DBDELETE INTRINSIC NUMBER 408 Deletes the current entry from a manual master or detail data set. The database must be opened in access mode 1, 3, or 4. Syntax DBDELETE,base,dset,mode,status 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.
TurboIMAGE/XL Library Procedures DBDELETE 7-10 Unchanged preceding and succeeding record numbers of a chain. If master data set and the new synonym chain count is greater than zero, the numbers reference the last and first synonym chain entries, respectively. Discussion When deleting entries from detail data sets, and if the database is open in access mode 1, you must establish a lock covering the data entry to be deleted, the data set, or the database.
TurboIMAGE/XL Library Procedures DBDELETE Database" in chapter 4 for what to consider when enabling or disabling this option. If the process is logging, a call to DBDELETE causes a log record to be written with such information as the time, date, user identification number, and a copy of the record to be deleted. In a dynamic transaction, DBDELETE causes a log record to be written after the physical transaction has been successfully completed.
TurboIMAGE/XL Library Procedures DBDELETE Table 5-8. DBDELETE Return Status Values Calling Errors: -11 Bad database reference. -12 No lock covers the data entry to be deleted. (Occurs only if database open in access mode 1.) -14 Illegal intrinsic in current access mode. -21 Bad data set reference. -23 Data set not writable. -24 DBDelete not allowed on Auto Master. -31 Bad mode. -222 Only DBXUNDO allowed when a dynamic transaction encounters an error. -102 DSWRITE failure.
TurboIMAGE/XL Library Procedures DBEND DBEND INTRINSIC NUMBER 413 Designates the end 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. DBEND is used in conjunction with DBBEGIN to begin and end a static or multiple database transaction.
TurboIMAGE/XL Library Procedures DBEND Mode 2: Write contents of the logging buffer in memory to disk, and end the static transaction. Mode 3: End of multiple database transaction. 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.
TurboIMAGE/XL Library Procedures DBEND Element Contents 1 If the procedure succeeds, the return status is 0. Table 5-8. 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.
TurboIMAGE/XL Library Procedures DBEND whether the process is actually logging or not. Table 5-9. DBEND Return Status Values Calling Errors: Communications Errors: Logging System Failures: Exceptional Conditions: -11 Bad database reference. -31 Bad mode. -146 Invalid transaction ID. -147 Mode doesn't match DBBEGIN mode. -148 Base ID list doesn't match DBBEGIN base ID list. -151 Text length greater than 512 bytes. -153 No transaction in progress to end.
TurboIMAGE/XL Library Procedures DBERROR DBERROR INTRINSIC NUMBER 419 Moves a message, as an ASCII character string, to a buffer specified by the calling program. The message interprets the contents of the status array as set by a call to a TurboIMAGE/XL procedure. Syntax DBERROR,status,buffer,length Parameters status is the name of the array used as the status parameter in the TurboIMAGE/XL procedure call about which information is requested.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. lists all messages that can be returned by DBERROR with their corresponding return status values. Variable information is represented by a lowercase word or phrase. Several messages can correspond to one return status and the interpretation of the value depends on the context in which it is returned; the message returned depends on additional information returned by the TurboIMAGE/XL intrinsic. Table 5-10.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. DBERROR Messages Return Status 166 DBERROR Message -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 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. -146 INVALID TRANSACTION ID.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. DBERROR Messages Return Status 168 DBERROR Message -206 REMOTE TURBOIMAGE DATABASE EXCEEDS IMAGE/3000 LIMITATION -208 MPE ERROR nn RETURNED BY FLABELINFO FOR MPE XL XM -209 INVALID MODE FOR MPE XL XM DETACH -210 MPE ERROR nn WHILE GETTING LOG FILE NAME -211 INVALID OR NO USER LABEL.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. DBERROR Messages Return Status DBERROR Message -233 KEY DATA FOUND IN THE DATABSE DOES NOT MATCH THAT IN THE MEMO RECORD -234 CANNOT PURGE THE 00 FILE -235 DYNAMIC TRANSACTION ABORTED DUE TO DBCLOSE MODE 1; DATABASE CLOSED -236 INTERNAL ERROR OCCURRED WHEN OPENING THE AUX FILE; ERROR nn -237 CANNOT DBXEND OR DBXUNDO A DBBEGIN TRANSACTION -238 MDBX, MODES OF DBXBEGIN/DBXEND DON'T MATCH. -240 ERROR IN DYNAMIC ROLLBACK.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. DBERROR Messages Return Status 170 DBERROR Message -264 WRITE ERROR FOR TPI FILES. -265 ERROR IN THIRD-PARTY SHADOWING PACKAGE. -266 ERROR WHILE DISABLING THIRD-PARTY SHADOWING. -267 DAMAGED FILE ERROR RETURNED BY THIRD-PARTY SHADOWING. -268 INVALID PCODE RETURNED BY TPS. -269 WRITE ERROR FOR TPS FILES. -270 DATABASE WITH NEW LIMITS MAY OVERRUN USERS’S DBINFO BUFFER -280 DBCONTROL MODE 18 NOT ALLOWED INSIDE A DYNAMIC TRANSACTION.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. DBERROR Messages Return Status DBERROR Message -427 BTE: FCLOSE, PURGE FAILED. -428 BTE: REBUILDINDEX FAILED. -429 BTE: DBFIND ARGUMENT VERSION IS BAD. -430 BTE: DBFIND (mode 4/24) ARGUMENT TYPE IS BAD. -431 BTE: DBFIND (mode 4/24) ARGUMENT #1 LENGTH IS BAD. -432 BTE: WILDCARD NOT ASCII. -433 BTE: DBFIND (MODE 4/24) ARGUMENT #2 LENGTH IS BAD. -434 DATASET DETAIL INSTEAD OF MASTER. -436 BTE: FAILED TO EXTRACT DATA FROM ROOT FILE.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. DBERROR Messages Return Status -3999 to -3000 DBERROR Message ERROR RETURNED BY THIRD-PARTY INDEXING PRODUCTS. 10 BEGINNING OF FILE 11 END OF FILE 12 DIRECTED BEGINNING OF FILE 13 DIRECTED END OF FILE 14 BEGINNING OF CHAIN 15 END OF CHAIN 16 THE DATA SET IS FULL (The following messages are returned only if capacity expansion is specified for the data set. Dataset# and FSERR # are replaced by the actual number.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10. DBERROR Messages Return Status DBERROR Message 41 DBUPDATE ATTEMPTED TO MODIFY VALUE OF CRITICAL ITEM--KEY, SEARCH OR SORT (The following messages are returned only if the critical item update (CIUPDATE) option is permitted for the database and the current process. The bracketed numbers after the messages refer to the value in halfword 3 of the status array. The nn in the value represents the path number returned.
TurboIMAGE/XL Library Procedures DBERROR Table 5-10.
TurboIMAGE/XL Library Procedures DBEXPLAIN DBEXPLAIN INTRINSIC NUMBER 418 Prints a multiline message on the $STDLIST device which describes a TurboIMAGE/XL procedure call and explains the call's results as recorded in the calling program's status array. Syntax DBEXPLAIN,status Parameters status NOTE is the name of the array used as the status parameter in the TurboIMAGE/XL procedure call about which information is requested.
TurboIMAGE/XL Library Procedures DBEXPLAIN Table 5-11.
TurboIMAGE/XL Library Procedures DBEXPLAIN application. Figure 5-1.
TurboIMAGE/XL Library Procedures DBFIND DBFIND INTRINSIC NUMBER 404 Can be used both when B-Tree index exists on a key item of the master and when B-Tree index does not exist. For a detailed discussion on B-Trees, refer to chapter 11, "B-Tree Indices.
TurboIMAGE/XL Library Procedures DBFIND on the key item of the master to which the search item has a path. • BTREEMODE1 flag is set ON by DBUTIL or DBCONTROL mode 15. • Argument contains a wildcard character. The chain count is accurate in halfword 5-6, and status halfwords 7-8 and 9-10 record the last entry in the last chain, and the first entry in the first chain of the super-chain for detail data sets.
TurboIMAGE/XL Library Procedures DBFIND documentation for additional DBFIND modes. 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-11.
TurboIMAGE/XL Library Procedures DBFIND The other is for modes 4 and 24, which requires a structured format as follows: Bytes Meaning 1-2 Type of generic search.
TurboIMAGE/XL Library Procedures DBFIND 3-4 version number. Must be numeric zero, or an error is returned. 5-6 The size (in bytes) of argument1 (not including these two bytes) for search types =, <, <=, >, >=, @c, PK. 7-8 The size (in bytes) of argument2 (not including these two bytes) for the search type [ ]. Must be numeric zero for other search types, or an error is returned. 9... 9+n-1 Argument1. The n bytes of argument data (for example, for an X10 field, n = 10). 9+n... 9+n+m-1 Argument2.
TurboIMAGE/XL Library Procedures DBFIND — Item type is X or U (ASCII). — DBFIND is for master and a B-Tree index exists on the key item or DBFIND is for detail and B-Tree index exists on the key item of the master to which the search item has a path. — BTREEMDODE1 flag is set ON by DBUTIL or DBCONTROL mode 15. — Argument contains a wildcard character. • Status array reflects information based on set, mode, and search type.
TurboIMAGE/XL Library Procedures DBFIND Table 5-12. DBFIND Return Status Values Calling Errors: Communications Errors: Exceptional Conditions: 184 -11 Bad database reference. -21 Bad data set reference. -31 Bad mode. -51 Bad list length. -52 Bad item. -222 Only DBXUNDO allowed when a dynamic transaction encounters an error. -258 Invalid argument for index. -259 Invalid mode for index. -260 No previous list of qualified data entries. -426 BTE: B-Tree doesn't exist.
TurboIMAGE/XL Library Procedures DBGET DBGET INTRINSIC NUMBER 405 Provides eight different methods for accessing the entries of a data set. Syntax DBGET,base,dset,mode,status,list,buffer,argument 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 base ID.
TurboIMAGE/XL Library Procedures DBGET 6 Backward Chained Read. Read the previous entry in the current chain, or the previous qualified entry for a B-Tree DBFIND. This is the entry referenced by the internally maintained backward pointer (argument parameter is ignored). Super-chains are traversed for detail data sets. If your database is enabled for third-party indexing (TPI), refer to your vendor documentation for additional information. 7 Calculated Read. (Master data sets only.
TurboIMAGE/XL Library Procedures DBGET list is the name of an array containing an ordered set of data item identifiers, either names or numbers. The values for these data items are placed in the array specified by the buffer parameter in the same order as they appear in the list array. The list array can contain a left-justified set of data item names, separated by commas and terminated by a semicolon or blank. No embedded blanks are allowed and no name can appear more than once.
TurboIMAGE/XL Library Procedures DBGET NOTE A call to DBOPEN does not open individual data sets. Thus, a call to DBGET (or DBFIND) that accesses a data set for the first time (or after the data set has been closed), must open the data set as well as jumbo files and B-Tree index files. This causes extra overhead not incurred by subsequent calls to the same data set by DBFIND or DBGET. Table 5-13.
TurboIMAGE/XL Library Procedures DBGET Table 5-13. DBGET Return Status Values Exceptional Conditions: DBGET Modes 10 Beginning of file. (3) 11 End of file. (2) 12 Directed beginning of file. (4) 13 Directed end of file. (4) 14 Beginning of chain/qualifier entries. (6) 15 End of chain/qualifier entries. (5) 17 No entry. (1,2,7,8) 18 Broken chain. (5,6) 49 Illegal buffer address.
TurboIMAGE/XL Library Procedures DBINFO DBINFO INTRINSIC NUMBER 402 Provides information about the database being accessed. The information returned is restricted by the user class number established when the database is opened; any data items, data sets, or paths of the database which are inaccessible to that user class are considered to be non-existent.
TurboIMAGE/XL Library Procedures DBINFO used. They are also described in "Discussion" on the following pages. Table 5-14. DBINFO Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: Communications Errors: Exceptional Conditions: -1 FOPEN failure. -4 FREADLABEL failure. -168 Cannot attach n to MPE XL XM: file system error nn. -169 Invalid mode for XM attach options. -175 Cannot attach n to MPE XL XM: XM error nn.
TurboIMAGE/XL Library Procedures DBINFO 9nn – Language modes Mode 101: Item Number Mode 101 defines the type of access available for a specific item. Qualifier identifies the data item name or number for which the information is requested. Buffer returns the following (each element is a halfword or two bytes): Element 1 Contents +/− Data item number If the data item number is positive, the user class has only read access to the data item.
TurboIMAGE/XL Library Procedures DBINFO Mode 103: Items in Database Mode 103 identifies data items available in the database and displays the type of access allowed. This mode does not identify unreferenced data items, that is, those items that are defined in the item section of the schema but are not referenced by at least one data set. Qualifier is ignored. Buffer returns the following (each element is a halfword or two bytes): Element Contents 1 Item count x 2 +/− Data item number 1 . . . . .
TurboIMAGE/XL Library Procedures DBINFO Mode 113: BTREEMODE1 and Wildcard Character Mode 113 gives the settings of BTREEMODE1 and wildcard character in the root file as well as current DBOPEN (DBU). Qualifier is ignored. Buffer must be at least 32 bytes and returns the following (each element is a halfword or 2 bytes): Element 1 Contents 0 if BTREEMODE1 is off in the root file 1 if BTREEMODE1 is on in the root file 2 The first byte (8 bits) is always 0.
TurboIMAGE/XL Library Procedures DBINFO Mode 202: Set Name Mode 202 describes a specific data set. Qualifier identifies the data set name or number for which the information is requested. Buffer returns the following (each element is a halfword or two bytes): Element 1–8 Contents Data set name 9 One of the following set types followed by a blank: M, A, D 10 Entry length 11 Blocking factor 12 0 13 0 14–15 Number of entries in set 16–17 Capacity of set.
TurboIMAGE/XL Library Procedures DBINFO Mode 204: Sets with Item Mode 204 identifies all data sets available which contain a specified data item and indicates the type of access allowed. Qualifier identifies the data item name or number for which the information is requested. Buffer returns the following (each element is a halfword or two bytes): Element Contents 1 Set count x 2 +/− Data set number . . . . . .
TurboIMAGE/XL Library Procedures DBINFO Element 24-25 Contents Incremental number of entries 26 Incremental percent 27 Dynamic capacity expansion flag (0 = off, 1 = on) The data set name is left-justified and will be padded with blanks if the name is shorter than 16 characters. Mode 205 can be used for any master or detail data set with or without dynamic capacity expansion capability. Mode 205 allows users to obtain information on dynamic data set capacity expansion programmatically.
TurboIMAGE/XL Library Procedures DBINFO Element Contents 1 # of chunks in a jumbo data set 2 0 3-4 Size of chunk 1 (# entries, not # of blocks!) 5-6 Size of chunk 2 (# entries, not # of blocks!) 7-8 . . . 2n + 3 Size of chunk n (# entries, not # of blocks!) Total size: (n + 1) * 4 bytes. If the data set is not a jumbo data set, then zero is returned for the number of chunks. Mode 208: Primary and Actual Capacity Mode 208 returns the primary and actual capacity.
TurboIMAGE/XL Library Procedures DBINFO capacities in DBINFO 208. DBINFO mode 208 returns information about internals which will be meaningful to only a few customers. Mode 209: B-Tree Attachment Mode 209 informs whether or not a B-Tree exists for a master. Qualifier is a master data set name or number.
TurboIMAGE/XL Library Procedures DBINFO If qualifier specifies a detail data set, the set number identifies the master data set. If qualifier specifies a master data set, the item numbers identify items in the detail data sets. If you do not have access to a search item, it is not included in the path count and the path information is not returned. If a sort item does not exist or you do not have access to it, the sort item number is zero.
TurboIMAGE/XL Library Procedures DBINFO Mode 401: Logging Mode 401 obtains information related to logging. Qualifier is ignored. Buffer returns the following (each element is a halfword or two bytes): Element Contents 1–4 Log identifier name 5 Database log flag 6 User log flag 7 Transaction flag 8–9 User transaction number The log identifier name is left-justified and padded with blanks if shorter than 8 characters.
TurboIMAGE/XL Library Procedures DBINFO Element 5 is always 0. ß indicates blank. Elements 6 to 14 are always blank. Elements 15 and 16 are reserved. Mode 403: Dynamic Roll-Back Mode 403 obtains information related to dynamic transaction activity on a given database. Qualifier is ignored.
TurboIMAGE/XL Library Procedures DBINFO If the database is associated with the default XM user log set, the XM log set name element contains blanks; otherwise it contains the name of the XM log set. Mode 404: Logging Subsystem Information Mode 404 returns information about multiple database transactions. Qualifier is ignored.
TurboIMAGE/XL Library Procedures DBINFO The log index is used to call the WRITELOG intrinsic. It is set to 0 if logging is not used. The transaction ID represents a multiple or single database transaction. Elements 16-31 are set when a multiple database transaction is in progress. Mode 406: Database Information Mode 406 returns information about fully qualified database name and open mode. Qualifier is ignored.
TurboIMAGE/XL Library Procedures DBINFO Mode 502: Critical Item Update Mode 502 checks the critical item update (CIUPDATE) option settings for the database and the current DBOPEN. The CIUPDATE option is set for the database with the DBUTIL >>SET command and then, depending on the setting, can be enabled or disabled with DBCONTROL for the current DBOPEN. Refer to the discussion of DBCONTROL in this chapter and the descriptions of the DBUTIL >>SHOW and >>SET commands in chapter 8 for more information.
TurboIMAGE/XL Library Procedures DBLOCK DBLOCK INTRINSIC NUMBER 409 Applies a logical lock to a database, one or more data sets, or one or more data entries. Syntax DBLOCK,base,qualifier,mode,status Parameters base is the name of the array used for 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 base ID.) qualifier Modes 1 and 2: Ignored.
TurboIMAGE/XL Library Procedures DBLOCK NOTE 2 The number of lock descriptors that were successfully applied in the DBLOCK request. For successful locks in modes 1 through 4 this will be 1. 3 If the return status is 20, this element contains 0 if the database is locked, 1 if the data set or entries are locked. 4 Reserved: Contents undefined. 5-10 Information about the procedure call and its results.
TurboIMAGE/XL Library Procedures DBLOCK Table 5-15. Locking Mode Options Lock Mode Lock Level Locking Type Description 1 Base Unconditional DBLOCK applies an unconditional lock to the whole database, returning to the calling program only after the lock is successful (or if an error occurs). The qualifier parameter is ignored. 2 Base Conditional DBLOCK applies a conditional lock to the database and returns immediately. A return status of zero indicates success.
TurboIMAGE/XL Library Procedures DBLOCK Figure 5-2. Qualifier Array Format for Locking Modes 5 and 6 Figure 5-3.
TurboIMAGE/XL Library Procedures DBLOCK Table 5-16. Lock Descriptor Fields Field Name length dset Description A halfword integer specifying the physical length in halfwords of the lock descriptor, including the length field itself. Describes the data set in which locks are placed. It is always 8 halfwords long and can be one of the following: • A data set name, left-justified, 16 characters long or, if shorter, terminated with a blank or semicolon (for example, SALES;).
TurboIMAGE/XL Library Procedures DBLOCK If you specify a data item of type P, U, or Z in a lock descriptor, TurboIMAGE/XL checks that the value is valid for that data item type. The following checks are made: • If the data item is type P, the right half of the right most byte must contain a sign and all preceding nibbles must contain decimal digits represented in Binary Coded Decimal (BCD) format.
TurboIMAGE/XL Library Procedures DBLOCK Table 5-17. DBLOCK Return Status Values Calling Errors: Communications Errors: 212 -11 Bad database reference. -31 Bad mode value. -121 Descriptor count error. -123 Illegal relop in a descriptor. -124 Descriptor too short. Must be greater than or equal to 9. -125 Bad set name/number. -126 Bad item name/number. -127 Attempt to lock using a compound item. -128 Value field too short in a descriptor. -129 P-type item longer than P28 specified.
TurboIMAGE/XL Library Procedures DBLOCK Table 5-17. DBLOCK Return Status Values Exceptional Conditions: Applicable Modes 20 Database locked or contains locks. (2,4,6) (Status element 3: 0 = database locked 1 = data set or entries locked) 22 Data set locked by another process. (3,4,5,6) 23 Entries locked within set. (4) 24 Item conflicts with current locks. (6) 25 Entry or entries already locked. (6) 26 Lock not performed since deadlock would occur. (1,2,3,4,5,6) 62 DBG full.
TurboIMAGE/XL Library Procedures DBMEMO DBMEMO INTRINSIC NUMBER 414 Used to log user data (ASCII or binary) to the log file. Syntax DBMEMO,base,text,mode,status,textlen 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.
TurboIMAGE/XL Library Procedures DBMEMO Table 5-18. DBMEMO Return Status Values Calling Errors: -11 Bad database reference. -31 Bad mode. -151 Text length greater than 512 bytes. -222 Only DBXUNDO allowed when a dynamic transaction encounters an error. -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.
TurboIMAGE/XL Library Procedures DBOPEN DBOPEN INTRINSIC NUMBER 401 Initiates access to the database and establishes the user class number and access mode for all subsequent database access. DBOPEN is used in conjunction with DBCLOSE to establish and terminate access to a database. Syntax DBOPEN,base,password,mode,status Parameters base is the name of an integer array containing a string of ASCII characters.
TurboIMAGE/XL Library Procedures DBOPEN [/USERIDENT] ;[/USERIDENT] password[/USERIDENT] Access class zero (0). Creator access. Password access. If either the password or the user identifier string is less than eight characters long, it must be terminated with a semicolon or a blank. The password establishes a user class number as described in chapter 2. A semicolon supplied as the password implies creator class 64.
TurboIMAGE/XL Library Procedures DBOPEN NOTE If the database is open in database access mode 1, a lock must be in effect on either the data set or the whole database when adding to or deleting from master data sets.
TurboIMAGE/XL Library Procedures DBOPEN Discussion A process can concurrently use the database through independent, unique access paths by issuing as many as 127 calls to DBOPEN (63 calls per database) and specifying a different base array in each call. Subsequent calls to other TurboIMAGE/XL procedures must use the appropriate base array so that the correct base ID is used.
TurboIMAGE/XL Library Procedures DBOPEN If DBRECOV roll-back recovery is enabled, the first DBOPEN checks if the user logging file and the database are attached to the same Transaction Management (XM) user log set. The database and the user logging file must be kept synchronized at the XM level in order for DBRECOV roll-back recovery to work. DBOPEN initiates recovery of the incomplete dynamic transactions, if necessary; then DBRECOV rolls back the incomplete static transactions.
TurboIMAGE/XL Library Procedures DBOPEN Table 5-19. DBOPEN Return Status Values Calling Errors: Communicati ons Errors: Logging System Failures: Chapter 5 -11 Bad database reference. -13 Must be creator of root file or database. -21 Bad password. -22 Maintenance word required. -31 Bad mode. -32 Unobtainable mode. -34 Database must be recovered before access is allowed. -90 Root file bad: unrecognized state: % octal integer. -91 Bad root modification level. -92 Database not created.
TurboIMAGE/XL Library Procedures DBOPEN Table 5-19. DBOPEN Return Status Values Native Language Support Errors: -200 Database language not system supported. -201 Native Language Support not installed. -202 MPE Native Language Support error decimal integer returned by NLINFO. Exceptional Conditions: -167 Cannot begin MPE XL XM transaction: XM error nn. -191 DBS control block is full. -199 Cannot end MPE XL XM transaction: XM error nn. -220 User log and database not attached to same XM log.
TurboIMAGE/XL Library Procedures DBPUT DBPUT INTRINSIC NUMBER 407 Adds new entries to a manual master or detail data set. The database must be opened in access mode 1, 3, or 4. Syntax DBPUT,base,dset,mode,status,list,buffer 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 base ID.
TurboIMAGE/XL Library Procedures DBPUT list is the name of an array containing an ordered set of data item identifiers; names or numbers. The new entry contains values supplied in the buffer array for data items in the list array. Search or sort items defined for the entry must be included in the list array. Fields of unreferenced items are filled with binary zeros.
TurboIMAGE/XL Library Procedures DBPUT Table 5-20. Special list Parameter Constructs Construct Commercial At-Sign NOTE: list Array Contents @; or @ Purpose Request procedure to use all data items of the data set in the order of their occurrence in the entry. indicates blank Discussion for Master Data Sets When adding entries to master data sets, the following rules apply: • The data set must be a manual master.
TurboIMAGE/XL Library Procedures DBPUT entry, it must have space to add one. This addition occurs automatically. • The order of data item values in the new entry is determined by the set definition in the schema and not by the order of the items' occurrence in the list and buffer arrays. • Values for data items not included in the list array are filled with binary zeros. • The new entry is linked into one chain for each search item, or path, defined according to the search item value.
TurboIMAGE/XL Library Procedures DBPUT information as the time, date, user identification number, and a copy of the new record to be added. If DBPUT is called within a dynamic transaction, a log record is written after the physical transaction has been successfully completed. If the intrinsic cannot be completed, an error is returned. This error condition must be checked, and you must decide to use DBXUNDO, DBXEND, or continue with the remainder of the dynamic transaction.
TurboIMAGE/XL Library Procedures DBPUT Table 5-21. DBPUT Return Status Values Calling Errors: Communications Errors: Logging System Failures: 228 -11 Bad database reference. -12 No lock covers the data entry to be added. (Occurs only if database is open in access mode 1.) -14 Illegal intrinsic in current access mode. -21 Bad data set reference. -23 Data set not writable. -24 Operation not allowed on automatic master data set. -31 Bad mode. -51 Bad list length. -52 Bad list or bad item.
TurboIMAGE/XL Library Procedures DBPUT Table 5-21. DBPUT Return Status Values Exceptional Conditions: -193 DBU control block is full. -196 DBB control block is full. -212 Database corruption detected. -264 XM write procedure returned 1030 or 1040. -312 Internal error encountered while reading database block. -314 Error while obtaining path information for set. -322 Error returned by process list. -332 Error in QLOCK table operation. 16 Data set full.
TurboIMAGE/XL Library Procedures DBUNLOCK DBUNLOCK INTRINSIC NUMBER 410 Relinquishes the locks acquired by all previous calls to DBLOCK. Redundant calls are ignored. If the calling process has the same database opened multiple times, only those locks put into effect for the specified access path are unlocked.
TurboIMAGE/XL Library Procedures DBUNLOCK to "Library Procedure Error Messages" in appendix A for a description of this information. Table 5-22. DBUNLOCK Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: Communications Errors: Exceptional Conditions: -4 MPE file error nn returned by DBUNLOCK on FREADLABEL. -6 MPE file error nn returned by DBUNLOCK on FWRITELABEL. -167 Cannot begin MPE XL XM transaction: XM error nn.
TurboIMAGE/XL Library Procedures DBUPDATE DBUPDATE INTRINSIC NUMBER 406 Modifies values of data items in the entry residing at the current record address of a specified data set. To call DBUPDATE, you must open the database in access mode 1, 2, 3, or 4. The update is always carried out correctly against the latest version of the data, regardless of modifications made by other users.
TurboIMAGE/XL Library Procedures DBUPDATE list is the name of an array containing an ordered set of data item identifiers, either names or numbers. Values supplied in the buffer array replace the values of data items occupying the same relative position in the list array. The user class established when the database is opened must allow at least read access to all the items included in the list array.
TurboIMAGE/XL Library Procedures DBUPDATE DBXUNDO, DBXEND, or continue with the remainder of the dynamic transaction. DBXUNDO will abort the entire transaction. DBXEND will terminate the dynamic transaction; the modifications completed thus far within the transaction will remain in the database. Table 5-23. DBUPDATE Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: Communications Errors: Logging System Failures: 234 -1 FOPEN failure.
TurboIMAGE/XL Library Procedures DBUPDATE Table 5-23. DBUPDATE Return Status Values Exceptional Conditions: -193 DBU control block is full. -264 Error while writing to TPI files. -3nn Internal error. -312 Error while reading database file. -314 Error while getting path information for set. -332 Error in QLOCK table operation. 17 No entry. 41 DBUPDATE attempted to modify value of critical item--key, search or sort. 42 Read only item. 49 Illegal buffer address. 50 Buffer too small.
TurboIMAGE/XL Library Procedures DBXBEGIN DBXBEGIN INTRINSIC NUMBER 420 Designates the beginning of a sequence of TurboIMAGE/XL procedure calls that are to be regarded as a dynamic transaction of a single database or dynamic transaction spanning multiple databases (DMDBX) for the purposes of logging and dynamic roll-back recovery. The text parameter can be used to log user information to the log file. DBXBEGIN is used in conjunction with DBXEND to begin and end a dynamic transaction.
TurboIMAGE/XL Library Procedures DBXBEGIN Mode 3: Indicates a dynamic transaction spanning multiple databases (DMDBX). If user logging is enabled for the databases, mode 3 generates multiple entries in the log file, one for each database. 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: status textlen Element Contents 1 If the procedure succeeds, the return status is 0. Table 5-24.
TurboIMAGE/XL Library Procedures DBXBEGIN Table 5-24. DBXBEGIN Return Status Values File System, Memory Management, and Transaction Management Failures: -4 FREADLABEL error. -228 DBXBEGIN encountered XM error nn when starting dynamic transaction. Calling Errors: -11 Bad database reference. -31 Bad (unrecognized) DBXBEGIN mode: n. -139 Invalid number of base IDs. -140 Bad base ID list. -151 Text length greater than 512 bytes. -152 DBXBEGIN called while a transaction is in progress.
TurboIMAGE/XL Library Procedures DBXEND DBXEND INTRINSIC NUMBER 421 Designates the end of a sequence of TurboIMAGE/XL procedure calls regarded as a dynamic transaction for the purposes of logging and dynamic roll-back recovery. The text parameter can be used to log user information to the log file. DBXEND is used in conjunction with DBXBEGIN to begin and end a dynamic transaction.
TurboIMAGE/XL Library Procedures DBXEND 5-25. describes the contents of element 1 when the procedure does not succeed. textlen 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. 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. Length can be zero.
TurboIMAGE/XL Library Procedures DBXEND Table 5-25. DBXEND Return Status Values File System, Memory Management, and Transaction Management Failures: -213 DBXEND encountered XM error nn when ending dynamic transaction. Calling Errors: -11 Bad database reference. -31 Bad (unrecognized) DBXEND mode: n. -140 Bad baseid list. -151 Text length greater than 512 bytes. -219 Remote database access incompatible with Dynamic Rollback.
TurboIMAGE/XL Library Procedures DBXUNDO DBXUNDO INTRINSIC NUMBER 422 Rolls back the active sequence of TurboIMAGE/XL procedure calls which are considered a dynamic transaction. Syntax DBXUNDO ,{ base baseidlist } ,text,mode,status,textlen 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.
TurboIMAGE/XL Library Procedures DBXUNDO 5-10 Procedure call information. Refer to "Library Procedure Error Messages" in appendix A for a description of this information. 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. Length can be zero. textlen Discussion DBXUNDO is called to dynamically roll back a sequence of TurboIMAGE/XL procedure calls that completed successfully inside a dynamic transaction.
TurboIMAGE/XL Library Procedures DBXUNDO Table 5-26. DBXUNDO Return Status Values File System, Memory Management, and Transaction Management Failures: -215 XM error nn encountered when rolling out dynamic transaction. Calling Errors: -11 Bad database reference. -31 Bad (unrecognized) DBXUNDO mode n. -140 Bad baseid list. -151 Text length greater than 512 bytes. -218 Output deferred is incompatible with Dynamic Rollback. -219 Remote database access is incompatible with Dynamic Rollback.
Host Language Access 6 Host Language Access You can access TurboIMAGE/XL from Compatibility Mode or Native Mode application programs. Compilers are available on MPE/iX in one or both modes in BASIC, BBASIC, C, COBOL, COBOL II, FORTRAN 66, FORTRAN 77, Pascal, RPG, and SPL. This chapter focuses on specific programming languages for use with Native Mode only. For Compatibility Mode examples, refer to the TurboIMAGE/V Database Management System Reference Manual.
Host Language Access Model Program Model Program This section shows the model for the example programs that run against the ORDERS database. You may wish to skip this section if you are an experienced TurboIMAGE/XL programmer. The main entry point for the application is a numbered list of functions that can be performed by calling the various routines. Each routine is made up of one or more tasks that are implemented through TurboIMAGE/XL intrinsic calls.
Host Language Access Model Program ITEMS: ACCOUNT, BINNUM, CITY, CREDIT-RATING, DATE, DELIV-DATE, DESCRIPTION, FIRST-NAME, INITIAL, LAST-NAME, LASTSHIPDATE, ONHANDQTY, PRICE, PURCH-DATE, QUANTITY, STATE, STOCK#, STREET-ADDRESS, SUPPLIER, TAX, TOTAL, UNIT-COST, ZIP, SETS: NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: PAGE 2 ORDER FOR CONVENIENCE >> << CUSTOMER ACCOUNT NUMBER>> << STORAGE LOCATION OF PROD>> << CITY>> << CUSTOMER CREDIT RATING>> << DATE (YYMMDD)>> << DELIVERY DATE (YYMMDD)>> << PRODUCT DESC
Host Language Access Model Program NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: END.
Host Language Access Model Program Buffer_Name is made up of data item name data item name data item name data item name Indicates that a data structure is being used. Buffer_Name is the name given to the structure, and data item name is the name given to the individual parts of that record. BEGIN MAIN LINE Indicates the beginning of the main body of the program. BEGIN ROUTINE Indicates the beginning of a routine.
Host Language Access ORDERS Database Model Program ORDERS Database Model Program Main Body of Program BEGIN MAIN LINE * OBJECTIVE: The main line contains the logic of this application. * It displays all functions, accepts a selection, * then calls the appropriate routines. The execution * of this program stops after the database is closed. * * ACCESS: Not applicable. * * CALLED BY: Not applicable.
Host Language Access ORDERS Database Model Program OBTAIN option ← user input If option = 1 Then CALL Open_The_Database and RETURN If option = 2 Then CALL Get_Sales_For_Date and RETURN If option = 3 Then CALL Get_A_Customer_Record and RETURN If option = 4 Then CALL Get_A_Product_Record and RETURN If option = 5 Then CALL List_All_Customers and RETURN If option = 6 Then CALL Add_A_Product and RETURN If option = 7 Then CALL Update_A_Customer and RETURN If option = 8 Then CALL Delete_A_Product and RETURN If
Host Language Access ORDERS Database Model Program BEGIN ROUTINE OBTAIN DBname ← " ORDERS;" OBTAIN Password ← "DO-ALL;" CALL DBOPEN (DBname, Password, Mode1_SMA, Status) ERROR CHECKING END ROUTINE Retrieving All the Records on a Chain (with Item Level Locking) (USER SELECTS 2 TO RETRIEVE SALES DATA) ROUTINE: Get_Sales_For_Date * OBJECTIVE: This routine demonstrates chained access, forward chained * read, and data item locking.
Host Language Access ORDERS Database Model Program OBTAIN Number_Of_Elements ← 1 OBTAIN Length_Of_Descriptor ← 21 OBTAIN Data_Set_Of_Descriptor ← "SALES;" OBTAIN Data_Item_Of_Descriptor ← "PURCH-DATE;" OBTAIN Relative_Operator_For_Data_Item ← " =" OBTAIN Value_For_Data_Item ← "881012" OBTAIN List ← "@;" OBTAIN Search_Item_Name ← "PURCH-DATE;" OBTAIN Search_Item_Value ← "881012" CALL DBLOCK (DBname, Lock_Descriptor_Sales_Array_Type, Mode5_Unconditional, Status) ERROR CHECKING CALL DBFIND (DBname, Sales_Deta
Host Language Access ORDERS Database Model Program Retrieving a Data Entry Using a Record Number (USER SELECTS 3 TO RETRIEVE CUSTOMER DATA) ROUTINE: Get_A_Customer_Record * OBJECTIVE: This routine demonstrates directed access by retrieving * a customer record with a known record number. Note * that the record number is first obtained using a DBGET * call, which in this case is a calculated mode 7.
Host Language Access ORDERS Database Model Program * * * * CALLED BY: Main Line CALLS: DBGET in mode 7 (calculated read) BEGIN ROUTINE Product_Buffer is made up of: Stock# Description OBTAIN List ← "@;" OBTAIN Key_Item_Value ← "STK30040" CALL DBGET (DBname, Product_Master, Mode7_Calculated, Status, List, Product_Buffer, Key_Item_Value) ERROR CHECKING DISPLAY the Product_Buffer ____________________________________________________________________ Stock# Description END ROUTINE Retrieving Data Serially (
Host Language Access ORDERS Database Model Program ERROR CHECKING DISPLAY List ____________________________________________________________________ Account Last-Name First-Name Initial EXIT LOOP if first word of Status buffer
Host Language Access ORDERS Database Model Program OBTAIN Textlen ← 14 CALL DBEND (DBname, Text, Mode1_Xend, Status, Textlen) ERROR CHECKING CALL DBUNLOCK (DBname, Product_Master, Mode1_Unlock, Status) ERROR CHECKING END ROUTINE Updating an Entry (USER SELECTS 7 TO DO AN UPDATE) ROUTINE: Update_A_Customer * OBJECTIVE: This routine updates a customer record interactively. * Updating is achieved by using the key item value to * locate the proper entry. It then displays the contents * to be updated.
Host Language Access ORDERS Database Model Program Relative_Operator_For_Data_Item Value_For_Data_Item Lock_Descriptor_Customer_Array_Type is made up of: Number_Of_Elements Lock_Descriptor_Customer_Type OBTAIN List ← "@;" OBTAIN Key_Item_Value ← user input CALL DBGET (DBname, Customer_Master, Mode7_Calculated, Status, List, Customer_Buffer, Key_Item_Value) ERROR CHECKING Customer_Buffer_Old ← Customer_Buffer DISPLAY Customer_Buffer OBTAIN Customer_Buffer_New ← user input OBTAIN Number_Of_Elements ← 1 OBTAIN
Host Language Access ORDERS Database Model Program Deleting an Entry (USER SELECTS 8 TO DELETE AN ENTRY) ROUTINE: Delete_A_Product * OBJECTIVE: This routine deletes an entry from the Product master * data set. The entry is specified by its key item value. * Identifying the entry and deleting it are preceded by * calls to DBLOCK and DBBEGIN to obtain locks and to start * a new transaction.
Host Language Access ORDERS Database Model Program ERROR CHECKING END ROUTINE Rewinding a Data Set (USER SELECTS 9 TO REWIND A DATA SET) ROUTINE: Rewind_Customer_Set * OBJECTIVE: This routine rewinds the customer data set by calling * DBCLOSE in mode 2.
Host Language Access ORDERS Database Model Program Obtaining Error Messages and Explanations (USER SELECTS 11 TO OBTAIN ERROR MESSAGES AND ADDITIONAL ERROR-RELATED INFORMATION) ROUTINE:Get_Error_And_Explain * OBJECTIVE: This routine generates an error message, corresponding * to the existing value in the first word of the status * parameter, by calling the DBERROR intrinsic. * Additionally, the routine generates a description * regarding the outstanding error message by calling the * DBEXPLAIN intrinsic.
Host Language Access C C This section shows, in C, portions of the model program presented at the beginning of this chapter. The examples perform specific tasks to illustrate the use of TurboIMAGE/XL intrinsics. The C example does not illustrate everything in the COBOL example. Some blocks of code may be appropriate only if expanded to a full program. Data items are defined at the beginning of the sample program. TurboIMAGE/XL intrinsics must be declared for C as external procedures.
Host Language Access C short DBname[6] Password[4] Sales_D_Set[4]; char *Purch_Date *Equal_Op *Item_List = "PURCH-DATE;", = " =", ="ACCOUNT,STOCK#,PRICE,TAX,TOTAL,PURCH-DATE;"; /* Define all your global variables.
Host Language Access C Obtaining Error Messages and Explanations The following paragraph implements the GET-ERROR-AND-EXPLAIN routine of the sample program. This routine calls DBEXPLAIN and DBERROR. DBEXPLAIN interprets the contents of the status parameter and prints a message on $STDLIST. DBERROR returns a message in the ERROR-BUFFER, explaining the condition code returned by TurboIMAGE/XL. At the end the routine, users can choose to abort or continue the execution of this program.
Host Language Access C Opening the Database This paragraph implements the OPEN-THE-DATABASE routine of the sample program in C. All required values, such as the password, are defined in the "static char" section of the program. Note that the password DO-ALL establishes user class number 18. The password DO-ALL is followed by a semicolon because it is less than eight characters long; a blank can be substituted for the semicolon. OPEN-THE-DATABASE uses open mode 1, which is the shared modify access mode.
Host Language Access C DBFIND in mode 1 (chained access) DBGET in mode 5 (forward chained read) DBUNLOCK in mode 1 (unlock) Get_Error_And_Explain */ { struct struct short short short short size_t /* Lock_Descriptor_Type Sales_Data_Set_Type Lock_Descriptor; Sales_Buffer; Search_Item_Value[3]; Search_Item_Name[8]; List[40]; Dummy; srch_len = 6; Prepare the lock descriptor buffer for obtaining item level locks on the Sales data set. */ Lock_Descriptor.Num_Of_Elements = 1; Lock_Descriptor.
Host Language Access C } else { /* Start retrieving all records in the current chain */ printf("\n"); printf("Acct-Number Stock_Number Price Tax Total Purch-Date \n"); printf("---------------------------------------------------------\n"); Mode = 5; strcpy((char *)List,Item_List); while (Status.Condition != End_Of_Chain) { DBGET(DBname,Sales_D_Set,&Mode,&Status,List,&Sales_Buffer, &Dummy); if (Status.Condition == 0) { printf("\n"); printf("%11d",Sales_Buffer.Account_Number); printf("%13.8s",Sales_Buffer.
Host Language Access COBOL II COBOL II The model program presented at the beginning of this chapter is now shown here in COBOL II. The program performs specific tasks to illustrate the use of TurboIMAGE/XL intrinsics. Note that the code, although broken out by task, can be combined to make up a complete, executable program. Data items are defined at the beginning of the sample program.
Host Language Access COBOL II chapter 3. Tables 3-2 and 3-3 show the TurboIMAGE/XL type designators, sub-item lengths, and data types typically used to process them in COBOL II. NOTE All parameters must be on halfword boundaries. Defining Data Types, Variables, and Intrinsics The following is part of the COBOL II program; it defines all the data items and records. IDENTIFICATION DIVISION. PROGRAM-ID. RECEIVE. DATE-COMPILED. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES.
Host Language Access COBOL II 01 01 01 01 01 01 01 01 01 270 05 ACCOUNT-NUMBER PIC S9(9) COMP. 05 STOCK-NUMBER PIC X(8). 05 QUANTITY PIC S9(4) COMP. 05 PRICE PIC S9(9) COMP. 05 TAX PIC S9(9) COMP. 05 TOTAL PIC S9(9) COMP. 05 PURCH-DATE PIC X(6). 05 DELIV-DATE PIC X(6). SALES-BUFFER-OUT. 05 ACCOUNT-NUMBER-OUT PIC Z(9)9. 05 STOCK-NUMBER-OUT PIC B(7)X(8). 05 QUANTITY-OUT PIC Z(5)9. 05 PRICE-OUT PIC Z(6)9. 05 TAX-OUT PIC Z(4)9. 05 TOTAL-OUT PIC Z(6)9. 05 PURCH-DATE-OUT PIC B(6)X(6).
Host Language Access COBOL II 01 01 01 01 01 01 05 05 INITIAL1-CUST-OUT 05 LAST-NAME-CUST-OUT KEY-ITEM-VALUE-PRODUCT KEY-ITEM-VALUE LIST-NO-ITEM SAVED-RECORD-NUMBER PRODUCT-MASTER PRODUCT-BUFFER. 05 STOCK-NUMBER 05 DESCRIPTION PIC PIC PIC PIC PIC PIC PIC PIC X. X(02). X(16) JUST RIGHT. X(08). S9(9) COMP. S9(9) COMP. S9(9) COMP. X(16). PIC PIC X(08). X(20). 01 DONE-VALUE PIC S9(4) COMP. 88 NOT-DONE VALUE 0. 88 DONE VALUE 1. 01 TEXT1 PIC X(80). 01 TEXTLEN PIC S9(9) COMP. 01 CUSTOMER-BUFFER-NEW.
Host Language Access COBOL II "| 3)GET A CUSTOMER RECORD 4)GET A PRODUCT RECORD |". 05 MENU-LINE-8 PIC X(62) VALUE "| 5)LIST ALL CUSTOMERS 6)ADD A PRODUCT |". 05 MENU-LINE-9 PIC X(62) VALUE "| 7)UPDATE CUSTOMER RECORD 8)DELETE A PRODUCT |". 05 MENU-LINE-10 PIC X(62) VALUE "| 9)REWIND/RESET CUSTOMER SET 10)OBTAIN DATA ITEM INFORMATION|". 05 MENU-LINE-11 PIC X(62) VALUE "| 11)GENERATE ERROR MESSAGES 12)CLOSE DATABASE |". Main Body of Program PROCEDURE DIVISION. 10-MAIN-LINE.
Host Language Access COBOL II DISPLAY "-----------------------------------" DISPLAY "Press Enter to Continue... " NO ADVANCING ACCEPT OPTION FREE END-EVALUATE. Opening the Database This paragraph implements the OPEN-THE-DATABASE routine of the sample program in COBOL II. All required values, such as the password, are provided by the routine. Note that the password DO-ALL establishes user class number 18.
Host Language Access COBOL II ****************************************************************** * ACCESS : Mode 1 - Shared Modify Access * * Called By: 30-DO-ACTION * * Calls : DBLOCK in mode 5 (unconditional item level locking) * DBFIND in mode 1 (chained access) * DBGET in mode 5 (forward chained read) * DBUNLOCK in mode 1 (unlock) * 1100-GET-ERROR-AND-EXPLAIN 200-GET-SALES-FOR-DATE.
Host Language Access COBOL II NOT-USED-PARM-16 IF CONDITION NOT = 0 THEN IF CONDITION = END-OF-CHAIN THEN DISPLAY SPACE DISPLAY SPACE DISPLAY SPACE DISPLAY "-----> End of Chain, " NO ADVANCING DISPLAY "Hit Enter to Continue" NO ADVANCING ACCEPT OPTION FREE ELSE PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF END-IF MOVE ACCOUNT-NUMBER OF SALES-BUFFER TO ACCOUNT-NUMBER-OUT MOVE STOCK-NUMBER OF SALES-BUFFER TO STOCK-NUMBER-OUT MOVE QUANTITY OF SALES-BUFFER TO QUANTITY-OUT MOVE PRICE OF SALES-BUFFER TO PRICE-OUT MOV
Host Language Access COBOL II NO ADVANCING DISPLAY "------------> " NO ADVANCING ACCEPT KEY-ITEM-VALUE FREE MOVE 7 TO DB-MODE MOVE ZERO TO LIST-NO-ITEM MOVE "@;" TO LIST MOVE "CUSTOMER;" TO CUSTOMER-MASTER CALL "DBGET" USING DBNAME, CUSTOMER-MASTER, DB-MODE, STATUS1, LIST-NO-ITEM, CUSTOMER-BUFFER, KEY-ITEM-VALUE IF CONDITION = 0 THEN SET FOUND TO TRUE MOVE RECORD-NUMBER TO SAVED-RECORD-NUMBER ELSE IF CONDITION = NO-SUCH-ENTRY THEN DISPLAY CLEAR SCREEN DISPLAY "*****************************************" DISP
Host Language Access COBOL II DISPLAY "* *" MOVE ACCOUNT-NUMBER OF CUSTOMER-BUFFER TO ACCOUNT-NUMBER-CUST-OUT DISPLAY "* Account # = ", ACCOUNT-NUMBER-CUST-OUT DISPLAY "* Last Name = ", LAST-NAME OF CUSTOMER-BUFFER DISPLAY "* First Name = ", FIRST-NAME OF CUSTOMER-BUFFER DISPLAY "* Initial = ", INITIAL1 OF CUSTOMER-BUFFER DISPLAY "* Address = ", STREET-ADDRESS OF CUSTOMER-BUFFER DISPLAY "* City = ", CITY OF CUSTOMER-BUFFER DISPLAY "* State = ", STATE OF CUSTOMER-BUFFER DISPLAY "* Zip = ", ZIP OF CUSTOMER-BU
Host Language Access COBOL II DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY CLEAR SCREEN "****************************************" "* No Such Entry in the Product Data Set." "* Please Try Again.
Host Language Access COBOL II SET NOT-DONE TO TRUE MOVE 3 TO DB-MODE MOVE "@;" TO LIST MOVE "CUSTOMER;" TO CUSTOMER-MASTER CALL "DBLOCK" USING DBNAME, CUSTOMER-MASTER, DB-MODE, STATUS1 IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF MOVE 2 TO DB-MODE MOVE "ACCOUNT,LAST-NAME,FIRST-NAME,INITIAL;" TO LIST PERFORM WITH TEST AFTER UNTIL DONE CALL "DBGET" USING DBNAME, CUSTOMER-MASTER, DB-MODE, STATUS1, LIST, CUSTOMER-BUFFER, NOT-USED-PARM-32 IF CONDITION NOT = 0 THEN IF CONDITION = END-OF-DAT
Host Language Access COBOL II ('0;') which returns no data, and same list ('*;') which returns the same fields listed in the previous call. ****************************************************************** * ACCESS : Mode 1 - Shared Modify Access * * Called By: 30-DO-ACTION * * Calls : DBLOCK in mode 3 (unconditional) * DBBEGIN in mode 1 (transaction begin) * DBPUT in mode 1 (put) * DBEND in mode 1 (transaction end) * DBUNLOCK in mode 1 (unlock) * 1100-GET-ERROR-AND-EXPLAIN 600-ADD-A-PRODUCT.
Host Language Access COBOL II NO ADVANCING ACCEPT OPTION FREE ELSE PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF MOVE "Add Entry to Product Set End" TO TEXT1 MOVE 14 TO TEXTLEN CALL "DBEND" USING DBNAME, TEXT1, DB-MODE, STATUS1, TEXTLEN IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF CALL "DBUNLOCK" USING DBNAME, PRODUCT-MASTER, DB-MODE, STATUS1 IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF.
Host Language Access COBOL II ACCEPT KEY-ITEM-VALUE FREE MOVE 7 TO DB-MODE MOVE 0 TO LIST-NO-ITEM MOVE "@;" TO LIST MOVE "CUSTOMER;" TO CUSTOMER-MASTER CALL "DBGET" USING DBNAME, CUSTOMER-MASTER, DB-MODE, STATUS1, LIST, CUSTOMER-BUFFER, KEY-ITEM-VALUE IF CONDITION = 0 THEN SET FOUND TO TRUE DISPLAY SPACE DISPLAY SPACE DISPLAY SPACE DISPLAY "Data On Account # = ", KEY-ITEM-VALUE DISPLAY "****************************************" DISPLAY "* *" DISPLAY "* Account # = ", ACCOUNT-NUMBER OF CUSTOMER-BUFFER DISPLA
Host Language Access COBOL II DISPLAY "* Account # = " NO ADVANCING ACCEPT ACCOUNT-NUMBER OF CUSTOMER-BUFFER-NEW FREE DISPLAY "* Last Name = " NO ADVANCING ACCEPT LAST-NAME OF CUSTOMER-BUFFER-NEW FREE DISPLAY "* First Name = " NO ADVANCING ACCEPT FIRST-NAME OF CUSTOMER-BUFFER-NEW FREE DISPLAY "* Initial = " NO ADVANCING ACCEPT INITIAL1 OF CUSTOMER-BUFFER-NEW FREE DISPLAY "* Address = " NO ADVANCING ACCEPT STREET-ADDRESS OF CUSTOMER-BUFFER-NEW FREE DISPLAY "* City = " NO ADVANCING ACCEPT CITY OF CUSTOMER-BUF
Host Language Access COBOL II PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF ELSE DISPLAY CLEAR SCREEN DISPLAY SPACE DISPLAY SPACE DISPLAY SPACE DISPLAY SPACE DISPLAY "***************************************" DISPLAY "** During Terminal Interaction *" DISPLAY "** Data On Account Number ", KEY-ITEM-VALUE DISPLAY "** Has Been Modified." DISPLAY "** *" DISPLAY "** Please Try Again.
Host Language Access COBOL II * DBUNLOCK in mode 1 (unlock) * 1100-GET-ERROR-AND-EXPLAIN 800-DELETE-A-PRODUCT.
Host Language Access COBOL II TEXTLEN IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF MOVE 1 TO DB-MODE CALL "DBUNLOCK" USING DBNAME, PRODUCT-MASTER, DB-MODE, STATUS1 IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF DISPLAY "Press Enter to Continue -----------> " NO ADVANCING ACCEPT OPTION FREE. Rewinding a Data Set This paragraph implements the REWIND-CUSTOMER-SET routine of the sample program.
Host Language Access COBOL II DISPLAY SPACE DISPLAY SPACE DISPLAY DATA-ITEM-NAME-IN, " Data Item" DISPLAY "----------------------------------------" DISPLAY "Data Item Name = ", DATA-ITEM-NAME DISPLAY "Data Item Type = ", DATA-ITEM-TYPE DISPLAY "Data Item Length = ", DATA-ITEM-LENGTH DISPLAY "Data Item Count = ", DATA-ITEM-COUNT DISPLAY "----------------------------------------" DISPLAY "Press Enter to Continue... " NO ADVANCING ACCEPT OPTION FREE.
Host Language Access COBOL II Closing the Database This paragraph implements the CLOSE-THE-DATABASE routine of the sample program. Closing the database is achieved by a call to DBCLOSE in mode 1. Error handling is done by referring all non-zero returned conditions to the 1100-GET-ERROR-AND-EXPLAIN paragraph.
Host Language Access FORTRAN 77 FORTRAN 77 Portions of the model program presented at the beginning of this chapter are now shown here in FORTRAN 77. The examples perform specific tasks to illustrate the use of TurboIMAGE/XL intrinsics. Data items are defined at the beginning of the sample program. Explicit declaration of intrinsics is not required. Other global variables in this program are placed in a COMMON file.
Host Language Access FORTRAN 77 Integer*2 Mode5_Forward, Mode1_Unlock C**** Set up for the Status parameter.
Host Language Access FORTRAN 77 Main Body of Program In the following portion of the program, the $hp3000_16$ compiler directive allows the FORTRAN 77 compiler to change the data alignment from a four-byte limit to a two-byte limit. For example, the non-alignment caused by the Quantity field in the Sales data set can be resolved using this directive. $hp3000_16$ Program Fortran_For_TurboIMAGEXL C C This area will contain the main line for the C FORTRAN 77 example.
Host Language Access FORTRAN 77 Integer*2 Error_Buffer(40) Equivalence (Error_Buffer(1),Error_Buffer_Text) Integer*4 Error_Length Integer*2 Answer Parameter (In=5,Out=6) Call DBERROR (Status,Error_Buffer,Error_Length) 10 Write(Out,*)'--------------------------------------' Write(Out,10)Error_Buffer_Text Format(A60) Write(Out,*)'--------------------------------------------' Call DBEXPLAIN (Status) 20 Answer=0 Write(Out,*)'---Enter, <1> to ABORT...
Host Language Access FORTRAN 77 Pass_Word='DO-ALL;' Call DBOPEN (DBname,Password,Mode1_SMA,Status) If (Condition.NE.0) Then Call Get_Error_And_Explain EndIf Return End Retrieving All the Records on a Chain (with Item Level Locking) This procedure implements the Get_Sales_For_Date routine of the sample program. Chained access is achieved using a call to DBFIND. The search item used for this call is Purch-Date. An item level lock is obtained on the value of the search item before the DBFIND call.
Host Language Access FORTRAN 77 Equivalence Parameter (Search_Item_Value(1),Search_Item_Value_Is) (End_Of_Chain=15,No_Chain_Head=17) C** Set up for the predicate buffer used in item level locking. Num_Of_Elements = 1 Length_Of_Descriptor = 21 Data_Set_Of_Descriptor ='SALES;' Data_Item_Of_Descriptor='PURCH-DATE;' Relative_Operator =' =' C** Accept the search value.
Host Language Access FORTRAN 77 & & & & List, Sales_Buffer, Not_Used_Parm) If (Condition.NE.0) Then If (Condition.EQ.End_Of_Chain) Then Print *,'-->End Of Chain, Hit Enter to Continue' Read (5,*) Else Call Get_Error_And_Explain EndIf Else Print* Print*,Account_Number,' ', Stock_Number,' ', Quantity,' ',Price,' ',Tax,' ',Total,' ', Purch_Date,' ',Deliv_Date EndIf End Do EndIf Mode1_Unlock =1 Call DBUNLOCK (DBname,Sales_Detail,Mode1_Unlock,Status) If (Condition.NE.
Host Language Access Pascal Pascal Portions of the model program presented at the beginning of this chapter are now shown here in Pascal. The examples perform specific tasks to illustrate the use of TurboIMAGE/XL intrinsics. Data items are defined at the beginning of the sample program. TurboIMAGE/XL intrinsics must be declared for Pascal as external procedures. The procedure name is followed by the word "Intrinsic.
Host Language Access Pascal BaseId : Packed Array [1..2] of Char; BaseName : Packed Array [1..16] of Char; End; (* for the password parameter *) Database_Password_Type = Packed Array [1..10] of Char; Data_Set_Name_Type (* for the status parameter *) = Packed Record Condition : ShortInt; Length : ShortInt; Record_Number : Integer; Chain_Count : Integer; Back_Pointer : Integer; Forward_Pointer : Integer; End; (* for the data set name parameter *) = Packed Array [1..
Host Language Access Pascal Status Option Mode List (* (* : : : : Database_Status_Type; ShortInt; ShortInt; Data_Item_List_Type; Define all TurboIMAGE/XL procedure calls that *) will be used in your application program.
Host Language Access Pascal Var Error_Buffer Error_Length Answer : : : Packed Array [1..80] of Char; Integer; ShortInt; Begin DBERROR (Status,Error_Buffer,Error_Length); Writeln('-------------------------------------------'); Writeln(Error_Buffer); Writeln('-------------------------------------------'); Writeln; DBEXPLAIN (Status); Answer:=0; Prompt( '---Enter, <1> to ABORT..., <2> to Continue >'); Readln(Answer); If Answer <> 1 Then Writeln(' Continuing .........
Host Language Access Pascal Retrieving All the Records on a Chain (with Item Level Locking) This procedure implements the Get_Sales_For_Date routine of the sample program. Chained access is achieved using a call to DBFIND. The search item used for this call is Purch-Date. An item level lock is obtained on the value of the search item before the DBFIND call. After that, individual chain items are retrieved, until the end of chain is encountered. This is done using multiple calls to the DBGET procedure.
Host Language Access Pascal Readln (Search_Item_Value); Mode5_Unconditional :=5; (* Request item level locks. *) (* Append the user's input to the lock descriptor buffer. *) Lock_Descriptor_Array. Lock_Descriptor_Sales.Value_For_Data_Item :=Search_Item_Value; (* Place item level locks on all entries identified by *) (* the value in the Search_Item_Value. *) DBLOCK (DBname,Lock_Descriptor_Array,Mode5_Unconditional,Status); If Status.
Host Language Access Pascal DBGET (DBname,Sales_Detail,Mode5_Forward,Status,List,Sales_Buffer, Not_Used_Parm); If Status.Condition= 0 Then Begin With Sales_Buffer Do Begin Writeln; Write(Account_Number:10); Write(Stock_Number:15); Write(Quantity:6); Write(Price:7 ); Write(Tax:5 ); Write(Total:7); Write(Purch_Date:12); Write(Deliv_Date:12); End; End (* Check the status buffer for any condition *) Else (* codes not equal to zero. *) Begin If Status.
Host Language Access RPG RPG RPG contains language constructs that make calls to TurboIMAGE/XL intrinsics, rather than having the user code do the intrinsic calls directly. For example, RPG opens all files at the beginning of program execution, thereby calling DBOPEN for any databases named on File Description specifications. Likewise, DBCLOSE is automatically called for databases at the end of program execution.
Host Language Access RPG F KIMAGE ORDERSLC F KITEM PURCH-DATE F KLEVEL DO-ALL F KSTATUSSTAT FTERMIN ID F 79 $STDIN FTERMOUT O V 79 $STDLST **************************************************************** * TABLE/ARRAY DECLARATIONS * **************************************************************** E ESC 1 1 1 Escape = 27 **************************************************************** * INPUT RECORD LAYOUTS * **************************************************************** ISALES NS I B 1 40ACCT# I 5 12 STOC
Host Language Access RPG C MOVELOPTION DATE 6 C*-------------------------------------------------------------C* Do unconditional data item lock on DATE. C* C DATE LOCK SALES 21 C 21 EXSR GETERR C LR GOTO END1 C*-------------------------------------------------------------C* Loop on CHAIN operation to get all entries in chain. On C* first occurrence of CHAIN for a unique value of DATE, RPG C* calls DBFIND, followed by DBGET. On subsequent uses of C* CHAIN with the same value for DATE, only DBGET is called.
Host Language Access RPG Obtaining Error Messages and Explanations The following subroutine implements the GET-ERROR-AND-EXPLAIN routine of the sample program. Because RPG as yet does not have access to DBEXPLAIN and DBERROR, this subroutine simply displays the TurboIMAGE/XL error number from the status array and then allows the user to either abort the program or continue its execution.
Host Language Access RPG O* Display error message. O* O E 1 ERRBUF O 23 "-----------------------" O 30 "-------" O E 1 ERRBUF O 11 "IMAGE ERROR" O STAT,1 21 " *" O 35 " HAS OCCURRED." O E 2 ERRBUF O 23 "-----------------------" O 30 "-------" O E 1 ERRBUF O 23 "---Enter, <1> to Abort." O 43 ".., <2> TO Continue" O*-------------------------------------------------------------O* Display message for continuing execution after error. O* O E 1 ERRCON O 15 "Continuing.....
Host Language Access RPG O 40 "Price " O 46 "Tax " O 53 "Total " O 66 "Purch-Date " O 79 "Deliv-Date " O*-------------------------------------------------------------O* Display Sales record line.
Logging and Recovery 7 Logging and Recovery This chapter discusses how to maintain database consistency; that is, how to log logical transactions and recover a TurboIMAGE/XL database from a system failure or program abort.
Logging and Recovery Database Utilities Used in Logging and Recovery Database Utilities Used in Logging and Recovery The TurboIMAGE/XL database is maintained using various TurboIMAGE/XL database utilities which are fully described in chapter 8. Because the following database utilities are used in logging and recovery, they are also referred to in this chapter: DBUTIL Creates and maintains the database. DBUNLOAD Copies data to specially formatted tape volumes.
Logging and Recovery Database Utilities Used in Logging and Recovery manager (SM) capability can use the DBUTIL >>SHOW command on any database without having to supply the maintenance word. Use this chapter together with chapter 8 which gives the syntax of the database utilities and commands.
Logging and Recovery Recovery Options Recovery Options The logging and recovery system is used to bring databases back to the same state at the time of a system failure; this state does not include incomplete transactions. TurboIMAGE/XL provides several types of recovery options: • Default recovery mode • Dynamic roll-back recovery • Intrinsic Level Recovery (ILR) • Roll-forward recovery • Roll-back recovery • Mirror database The recovery options are described briefly below.
Logging and Recovery Recovery Options and your database will not be left with an incomplete transaction. Dynamic roll-back also allows programs to selectively abort any ongoing transaction. TurboIMAGE/XL uses XM to dynamically roll back uncommitted dynamic transactions. Dynamic roll-back requires using the three intrinsics: DBXBEGIN, DBXEND, and DBXUNDO. Dynamic roll-back recovery can be used with roll-forward recovery to handle disk media failures. Intrinsic Level Recovery (ILR).
Logging and Recovery Recovery Options Logging and Recovery Considerations To ensure database integrity, the following responsibilities need to be assigned to specific individuals: • Enabling and disabling the logging and recovery processes. • Creating database backup copies and synchronizing with log files. • Performing actual recoveries when required.
Logging and Recovery Logical Transactions Logical Transactions A Definition TurboIMAGE/XL logging and recovery (via DBRECOV) provide the ability to restore the database to a consistent state after a system failure. To understand how this is done, it is important to understand the concept of a logical transaction. A logical transaction is a sequence of one or more procedure calls that are considered one logical unit of work. Table 7-1.
Logging and Recovery Logical Transactions Table 7-1. Types of Logical Transactions Transaction Definition Unlike a dynamic transaction for one database, DMDBX requires that a DBCONTROL mode 7 be done once for every database you want to include in a DMDBX, after DBOPEN of that database and before using it in the DBXBEGIN intrinsic. DBCONTROL mode 7 enables the database for deadlock detection, which when encountered, returns an error 26 instead of triggering a process hang.
Logging and Recovery Logical Transactions Figure 7-1. illustrates the concept of a logical transaction using a static and a dynamic transaction. Note that a transaction block is also illustrated. A transaction block consists of all transactions between a call to DBOPEN and a call to DBCLOSE. For further information about transaction blocks, refer to "FILE Command" later in this chapter. Figure 7-1.
Logging and Recovery Logical Transactions transaction A failed to complete, all of its record additions are suppressed. Because transaction B is dependent upon the suppressed transaction A, it cannot be recovered. DBRECOV is forced to suppress transaction B, even though it successfully completed during real-time processing. This potential problem could be avoided if transactions modifying the database employ locking correctly.
Logging and Recovery Logical Transactions Locking Examples Examples of the two recommended locking schemes follow: Single Lock Strategy DBLOCK for account 2,18,34 DBBEGIN DBGET data for account 2 DBPUT data for account 34 DBGET data for account 18 DBDELETE data for account 18 DBEND DBUNLOCK for all accounts Lock should precede DBBEGIN call. DBUNLOCK must be last call.
Logging and Recovery Logical Transactions is returned indicating the failure of the intrinsic, the status condition must be checked before proceeding further or rolling back the entire transaction. As with nondynamic transactions, the placement of DBLOCK calls either before or after DBXBEGIN is up to the programmer. A program with Multiple RIN (MR) capability can apply multiple locks with a dynamic transaction. MR capability is described in appendix D.
Logging and Recovery Dynamic Roll-Back Recovery Dynamic Roll-Back Recovery Dynamic roll-back allows a more timely recovery of databases than is possible with DBRECOV. Dynamic roll-back eliminates the overhead incurred when a database is enabled for user logging and permits database access to continue, even while other users are accessing a database. Using XM, uncommitted logical transactions can be rolled back dynamically (online) while other database activity is occurring.
Logging and Recovery Dynamic Roll-Back Recovery failed. As the application designer, you should be very cautious when taking this option as the modification to the database in this intrinsic did not take place. 6. Call DBXEND to declare the end of the modifications. If DBXUNDO was used in step 4 to roll back a transaction, your program logic should ensure that the subsequent call to DBXEND is not processed. 7. Call DBUNLOCK to release all of the locks.
Logging and Recovery Intrinsic Level Recovery Intrinsic Level Recovery Intrinsic Level Recovery (ILR), one of the TurboIMAGE/XL recovery options, closely resembles default mode recovery. The distinction that ILR provides is an enforced flushing of the Transaction Management (XM) log file after every intrinsic.
Logging and Recovery Logging Preparation Logging Preparation User logging is required for roll-forward recovery, roll-back recovery, and to maintain a mirror database. It is not required for dynamic roll-back recovery, but is recommended to protect against a hard disk failure. To prepare a database for user logging, you must set a log identifier (logid) into the database root file.
Logging and Recovery Logging Preparation NEWACCT command for a new account, or the ALTACCT command for an existing account, as follows: :NEWACCT acctname,mgrname;CAP=capability list :ALTACCT acctname;CAP=capability list (include LG) (include LG) Next, the account manager can provide logging capability to individual users by using the NEWUSER command for new users, or the ALTUSER command for an existing user, as follows: :NEWUSER username;CAP=capability list :ALTUSER username;CAP=capability list (include
Logging and Recovery Logging Preparation Step 4--Building a Log File for Logging to Disk This step is required only when logging to disk. You must build the new file and allocate space for it on disk by using the MPE/iX BUILD command below. Syntax :BUILD logfile;CODE=LOG;DISC= [numrec] [, [numextents] [,initial loc]] [;DEV= [device]] Parameters logfile NOTE is the name of the log file being built, as specified in the MPE/iX GETLOG command.
Logging and Recovery Logging Preparation Example :BUILD ORDER001;CODE=LOG;DISC=200000,20,7 Step 5--Creating the Log Identifier You create the log identifier on MPE/iX by using the GETLOG command shown in this section. A log identifier (logid) is a unique logical name that identifies a system logging process to which log records are passed. Before using the GETLOG command, use the MPE/iX LISTLOG command to check if the logid already exists on MPE/iX.
Logging and Recovery Logging Preparation NOTE Do not give the logid and the log file the same name, because the logid is used to name the RESTART file (used for DBRECOV STOP/RESTART recovery explained later in this chapter). logfile is an MPE/iX file reference that identifies the actual file to which the log records are written. If the AUTO option is specified, the last three digits are numeric (001-999).
Logging and Recovery Logging Preparation :LISTLOG NO LOGGING IDENTIFIERS ASSIGNED (CIWARN 1231) :GETLOG ORDERLOG;LOG=ORDER001,DISC;PASS=PASSLOG :LISTLOG LOGID CREATOR CHANGE AUTO CURRENT LOG FILE ORDERLOG BEA.MKTG YES NO ORDER001.MKTG.SYS :ALTLOG ORDERLOG;AUTO :LISTLOG LOGID CREATOR CHANGE AUTO CURRENT LOG FILE ORDERLOG BEA.MKTG YES YES ORDER001.MKTG.
Logging and Recovery Logging Preparation :RUN DBUTIL.PUB.SYS >>SET ORDERS LOGID = ORDERLOG PASSWORD: PASSLOG If no logid password was previously specified in the GETLOG command, you would press Return at the prompt.
Logging and Recovery Logging Preparation • Enable Rollback Flag. If you plan to use roll-back recovery, use the following command to enable roll-back recovery: >>ENABLE database name FOR ROLLBACK After the logid is set and the log file has been built, the >>ENABLE command for roll-back recovery shown above automatically enables logging for the database. However, the >>DISABLE database name FOR ROLLBACK command will not automatically disable logging. • Enable MUSTRECOVER Flag.
Logging and Recovery Logging Preparation (with ONLINE=START or ONLINE=END)—after the preceding flags have been set in the database. Logging status can be checked by referring to the procedure in "Logging Status" later in this chapter. Step 8--Making a Database Backup Copy This step is required for roll-forward recovery. It is recommended (for protection in the event of a hard disk failure), but not required, for roll-back recovery.
Logging and Recovery Logging Preparation NOTE If you plan to restore the TurboIMAGE/XL database on an MPE V system, use the TRANSPORT option of the DBSTORE or STORE command. Chapter 8 contains detailed information about the DBSTORE command. Refer to the MPE/iX Commands Reference Manual for more information about STORE options. TurboSTORE/iX 7x24 True-Online Backup This section describes the use of TurboSTORE/iX 7x24 True-Online Backup with the ONLINE=START or ONLINE=END option.
Logging and Recovery Logging Preparation backup, and the ONLINE=END option permits the sync point at the end of a True-Online backup. The ONLINE=START option has the following advantages over ONLINE=END: • Allows the database to be restored on an earlier version of MPE/iX. • Allows faster partial (selective, not @.@.@) restores, since sync point at end requires RESTORE to read the log files (used for backup) from the end of the last piece of media.
Logging and Recovery Logging Preparation True-online backup. An example is given below: Access is enabled. . . . Logging is enabled. . . . Database last stored using True-Online Backup and log file NLOG007 on THU, JAN 18, 1996, 6:06 PM. If you used the AUTO option with GETLOG command, you may purge log files NLOG001 up to NLOG006. When you continue updating the database, log files up to NLOG999 will be automatically created when needed.
Logging and Recovery Logging Preparation Benefits of TurboSTORE/iX 7x24 True-Online Backup The benefits of using True-Online backup to store TurboIMAGE/XL databases regardless of logging enabled are as follows: • Stores the database when it is open for read/write access, or closed. • Stores one or more TurboIMAGE/XL databases, along with their related files including the TC file, third-party index files, jumbo data sets, and B-Tree index files, if any.
Logging and Recovery Logging Status Logging Status The DBUTIL >>SHOW command can be used to display the log identifier and the status of the flags for access, recovery, and logging. If TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option) is used to back up the database, it can also display the date, time, and the logfile used during backup.
Logging and Recovery Logging Status Database has at least one indexed dataset. BTREEMODE1 is off, wildcard = "@". Logid: ORDERLOG is valid. password is correct. XM log set : XM log set type : XM log set size : The language is default XM user log set for volume set MPEXL_SYSTEM_VOLUME_SET circular 32 megabytes 0 - NATIVE-3000. Buffer specifications: 8(1/2),9(3/4),10(5/6),11(7/8),12(9/10),13(11/12),14(13/14), 15(15/16),16(17/18),17(19/120) No other users are accessing the database.
Logging and Recovery Logging Maintenance Logging Maintenance You should determine a log maintenance cycle for the database. For example, suppose the database is maintained on a daily cycle. This means that, at the beginning of each day, the log process is initiated from the console with the LOG command and the flags are set (see the following discussion). At the end of the day, the log process is stopped from the console and the flags are reset for storage of the database backup copy.
Logging and Recovery Logging Maintenance Example LOG ORDERLOG, START If the log process is stopped using the LOG command, but a database backup copy is not generated at that time, the RESTART option must be used to resume logging to the same log file. To determine whether or not a log process is running, use the MPE/iX SHOWLOGSTATUS command to determine the log identifiers of active log processes. SHOWLOGSTATUS displays the percentage of records in the log file if the logid output is to disk.
Logging and Recovery Logging Maintenance CHANGELOG Capability The MPE/iX CHANGELOG feature provides a continuous MPE/iX user logging process, with the ability to change tape or disk log files when they reach capacity without stopping the user logging process. User logging also keeps track of the order of the files in the log file set. Parts of the CHANGELOG record contain the file set number (001-999) and the device type of the file names in the record.
Logging and Recovery Logging Maintenance to the current log file. The current log file is closed and the new log file is opened.
Logging and Recovery Logging Maintenance To illustrate another example when TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option) was used to back up the database, assume that the log file in use during backup was LOGF041. If a database needs to be recovered and the logging cycle is currently writing to LOGF065, DBRECOV will begin recovery with LOGF041 (following the backup) and will continue until LOGF065.
Logging and Recovery Logging Maintenance :file orderssf;dev=disc :store orders;*orderssf;online=start >>TURBO-STORE/RESTORE VERSION C.55.07 B5152AA << (C) 1986 HEWLETT-PACKARD CO. STORE orders;*orderssf;ONLINE=START FRI, APR 18, 1997, 12:01 PM ONLINE BACKUP UTILIZED DISC SPACE FOR LOG ON THE FOLLOWING VOLSETS: MPEXL_SYSTEM_VOLUME_SET : 0 KB DATABASE INFORMATION: TURBOIMAGE DATABASE: ORDERS FILES STORED : .RECTOL .
Logging and Recovery Logging Maintenance Log File Time Stamps The two log file time stamps are as follows: • The DBSTORE time stamp set at the time the last database backup copy was made using DBSTORE or TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option). This time stamp is used by roll-forward recovery. The DBSTORE time stamp is fixed and does not change once the database backup copy has been made.
Logging and Recovery Roll-Forward Recovery Roll-Forward Recovery Roll-forward recovery can be executed to bring databases back to a likeness of their state at the time of a hard system failure (for example, a disk head crash or a system failure while the database is enabled for AUTODEFER). Roll-forward recovery requires a synchronized backup copy of the database and the log file. (Refer to "Logging Preparation" earlier in this chapter for roll-forward logging information.
Logging and Recovery Roll-Forward Recovery Enabling the Roll-Forward Feature To enable the roll-forward feature, complete the following sequence: 1. Set the logid and build a log file (if logging to disk) as shown in steps 2 through 6 of "Logging Preparation" earlier in this chapter. 2. For each particular database, disable access and enable the logging and roll-forward features by entering the following DBUTIL commands. You can also enable the MUSTRECOVER option if you wish to use it.
Logging and Recovery Roll-Forward Recovery END OF PROGRAM :RUN DBRESTOR.PUB.SYS WHICH DATABASE? ORDERS DATABASE RESTORED END OF PROGRAM :RUN DBUTIL.PUB.SYS >>SHOW ORDERS FLAGS For database ORDERS Access is disabled. Autodefer is disabled. Dumping is disabled. Rollback recovery is disabled. Recovery is enabled. ILR is disabled. Mustrecover is enabled. Logging is enabled. Prefetch is disabled. Indexing is disabled. HWMPUT is disabled. Restart is disabled.
Logging and Recovery Roll-Forward Recovery FILES RESTORED : FILES RESTORED : 7 7 : :RUN DBUTIL.PUB.SYS HP30391C.07.00 TurboIMAGE/XL: DBUTIL (C) COPYRIGHT HEWLETT-PACKARD COMPANY 1987 >>show orders flags For database ORDERS Maintenance word is not present. Access is enabled. Autodefer is disabled. Dumping is disabled. Rollback recovery is disabled. Recovery is disabled. ILR is disabled. Mustrecover is enabled. Logging is enabled. Prefetch is disabled. Indexing is disabled. HWMPUT is disabled.
Logging and Recovery Roll-Forward Recovery Performing Roll-Forward Recovery To complete the transaction roll-forward process following a hard system failure, perform the following steps: 1. Following a start recovery operation to bring up the system, locate the applicable log file medium to be used for roll-forward recovery. If logging to tape, the correct tape needs to be mounted.
Logging and Recovery Roll-Forward Recovery enter the >EXIT command; DBRECOV terminates, and no recovery takes place. >RUN After the >RUN command is given, DBRECOV recovers the specified databases, creates user recovery files, and terminates. After entering the >RUN command, DBRECOV asks you to mount the log tape (if the log file medium is tape). Continue the roll-forward process as directed by messages returned to both the console and the terminal screens. 9.
Logging and Recovery Roll-Forward Recovery 4. Start the log process: :LOG logid,START 5. Back up the database using TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option) and logfile LOGF001. Let this be backup number 1. 6. Access the database for modifications. The current log file is LOGF005. 7. Back up the database, while open for access, using TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option). Let this be backup number 2.
Logging and Recovery Roll-Forward Recovery the recommended procedures have been followed. Recovery can be completed for all of the other specified databases that have been restored from a backup copy and the recovery flag is enabled, as long as >CONTROL ERRORS is set appropriately (see "DBRECOV >CONTROL" in chapter 8).
Logging and Recovery Roll-Back Recovery Roll-Back Recovery Roll-back recovery is another TurboIMAGE/XL recovery option. Roll-back recovery provides rapid recovery of database data integrity following a "soft" system crash (that is, system failure or loss of working memory). The roll-back feature is invoked through the DBRECOV utility and requires only the current database log files to restore data integrity. Note that ILR is not needed for roll-back recovery.
Logging and Recovery Roll-Back Recovery When transaction T4 is aborted, TurboIMAGE/XL completes the transaction by issuing an abnormal end (DBABEND). This transaction is then seen as completed by the roll-back feature and is not normally rolled back.
Logging and Recovery Roll-Back Recovery words for the current time stamp). The roll-back time stamp is updated and logged in the log file and in the root file when the database is first opened. Roll-back recovery then uses the time stamp during recovery to verify the correct log file for each database. Note that if the database and the log file are not on the same volume set, an error is issued. CAUTION In the event of a system failure, do not restart user logging before running DBRECOV.
Logging and Recovery Roll-Back Recovery automatically locates the first log file in the given logging cycle by checking the beginning of the root file for the logid. Note that the system boot-up process writes a crash record to the last volume of the user log set. If a start recovery operation is not performed, this will not occur, causing DBRECOV to issue a warning. 2. Make a database backup copy in case a system failure occurs during the roll-back recovery process. 3.
Logging and Recovery Roll-Back Recovery For recovery to succeed, you must have access to the log file. This implies either knowing the maintenance word and having system manager (SM) or operator (OP) capability, or being the creator of the log identifier with read access to the log file if it resides in a different logon group and account. If the log file is on tape, you must know the volume identifier.
Logging and Recovery DBRECOV Commands Used with Roll-Forward and Roll-Back Recovery DBRECOV Commands Used with Roll-Forward and Roll-Back Recovery The following DBRECOV commands are used for either roll-forward or roll-back recovery: CONTROL Specifies the conditions for recovery. FILE Sorts the log file by individual users and/or user identifiers, and designates an MPE/iX file as the destination for each user's log records.
Logging and Recovery DBRECOV Commands Used with Roll-Forward and Roll-Back Recovery The initial default condition for stop time and end-of-file is that none is imposed on recovery. When a particular date or record number has been specified by STOPTIME or EOF, it can be changed by specifying a new date or record number.
Logging and Recovery DBRECOV Commands Used with Roll-Forward and Roll-Back Recovery the intrinsics DBOPEN and DBCLOSE. Rmode refers to transactions that recovered successfully; fmode refers to transactions that failed to be recovered. Refer to the DBRECOV >FILE command for details of operation. PRINT Command The >PRINT command is an option used to display information before actually initiating recovery with the >RUN command.
Logging and Recovery DBRECOV Commands Used with Roll-Forward and Roll-Back Recovery ROLLBACK Command The >ROLLBACK command is used for roll-back recovery. It designates the name of a database to be rolled back. Any incomplete transactions at the time of the system failure are rolled out. Multiple databases may be roll-back recovered by entering more than one database name after the command.
Logging and Recovery Recovery Tables Recovery Tables The first three of the following four tables are displayed, along with statistics, by every execution of the recovery system. The last table is displayed only if the user recovery file feature is used.
Logging and Recovery Recovery Tables account, program name, and transaction statistics. This table contains one entry for each process that logged transactions to the log file. An asterisk appears for any process that issued a DBOPEN without a corresponding DBCLOSE before the system failure. In roll-forward recovery, the columns "TRANS, PUTS, DELS, UPS" indicate the number of transactions recovered. In roll-back recovery, these columns and numbers indicate the number of transactions rolled out.
Logging and Recovery Post-Recovery Options Post-Recovery Options After a recovery has completed, there are three procedural options. The option chosen determines the recovery procedure in the event of a subsequent system failure. Together, the database administrator and system manager or console operator should agree upon the best post-recovery procedure to avoid confusion at recovery time. The options available after recovery include: 1.
Logging and Recovery The Mirror Database The Mirror Database Transaction logging and regular backups are good maintenance. However, if databases must be accessible at all times and cannot be down even for maintenance, then a different maintenance method is needed. A system can be set up for constant access or "high availability," and still have controlled maintenance. The mirror database is the fundamental element in creating a high availability database system.
Logging and Recovery The Mirror Database Figure 7-3.
Logging and Recovery The Mirror Database Maintaining the Mirror Database After the mirror database system is set up, the DBRECOV STOP-RESTART feature is used to maintain the secondary database. To start the initial DBRECOV procedure, the user must make sure logging is enabled on the primary system and that either the MPE/iX GETLOG AUTO option or CHANGELOG is being used. These MPE/iX options make logging without interruption on the primary system possible, thus increasing the availability of the databases.
Logging and Recovery The Mirror Database aborted because the RESTART file is purged. The database flags are returned to the same settings as before the recovery process was started. If ABORT fails to abort recovery because of an inconsistent RESTART file, DBRECOV,PURGE can be used to delete the current RESTART file before beginning the mirror database process again. Performing DBRECOV STOP-RESTART The processes involved in using the STOP-RESTART feature of DBRECOV are discussed here.
Logging and Recovery The Mirror Database recorded in the RESTART file. DATABASE(S) WITH RECOVERY SUSPENDED: base1.group.acct base2.group.acct . . . This is a list of the databases that are in the RESTART file. These database names are specified later when either the RESTART or ABORT options are used. The RESTART file name is the same as the logid name used in the GETLOG and the LOG,START commands when logging was enabled on the primary system.
Logging and Recovery The Mirror Database with which databases, the RESTART of recovery from a backup is not possible. To restart recovery from a backup, the user needs to restore the tapes containing the following: • The databases. • The RESTART file. • All log files processed since the last successful RESTART. When running DBRECOV, the tapes containing the log files must be mounted in the correct sequence according to the tape volume labels.
Logging and Recovery The Mirror Database and the user is returned to the MPE/iX prompt. This error usually occurs when another file with the same name as the RESTART file has been created on the system. Make sure the file is a RESTART file, and try RESTART again. If the RESTART file cannot be located, go back to the previous tape, restore the databases which should have their own RESTART file and log files stored with them, and run DBRECOV,RESTART from that point.
Logging and Recovery The Mirror Database command and RESTART from the previous STOP point. To start the recovery process again, find out why the databases are not in RESTART mode and try to correct the problem. If the problem cannot be corrected, take either of the following steps: • Go to the previous STOP point and use the databases and RESTART file stored to restart roll-forward recovery, or • ABORT the current RESTART process.
Logging and Recovery The Mirror Database on the secondary system. CAUTION When recovery is aborted (refer to the following discussion), the current RESTART file is purged and RESTART must be done from the previous STOP point. Aborting DBRECOV To run the ABORT option: :RUN DBRECOV.PUB.
Logging and Recovery The Mirror Database When the RESTART file is successfully opened, DBRECOV identifies all the databases in the RESTART file, and verifies that they are in RESTART mode. DBRECOV then checks the time stamps in the RESTART file and the databases to make sure they match. If the time stamps do not match, the following message is printed: RESTART TIME STAMPS DON'T AGREE WITH DATABASE TIME STAMPS This indicates incompatibility of the RESTART file with the data bases.
Logging and Recovery The Mirror Database is disabled, and the database access flag is reset to the state it was in before DBRECOV was run. Purging a RESTART File If the RESTART option fails at the current STOP point, the user can ABORT the current recovery process and RESTART the databases from the previous STOP point.
Logging and Recovery The Mirror Database If some of the databases are not found, DBRECOV prompts for confirmation to purge the RESTART file: Can't re-open DATABASE basename. CONTINUE WITH PURGE (N/Y)? DBRECOV allows you to make sure that you wish to purge this recovery process. If not all databases are in the RESTART file, this could be a different set of databases. Respond Y or YES to purge the RESTART file, or N, NO, (or press carriage return) to stop.
Logging and Recovery The Mirror Database • When using the STOP-RESTART option, the log file name and the logid must be different. Log File Size Determine the size of the log files, based on how far behind the secondary system will be, and how often backups will be done. To keep the secondary system as close to a mirror image of the primary database as possible, log files should be made small so that they will be filled quickly and can be sent to the secondary system frequently.
Using the Database Utilities 8 Using the Database Utilities The TurboIMAGE/XL utilities create and initialize the database files and perform various maintenance functions, such as restructuring a database. This chapter discusses these utilities and the syntax of each utility. You must be the database creator to execute the >>CREATE command of the DBUTIL utility program or to change or remove the maintenance word with the DBUTIL >>SET command.
Using the Database Utilities Restructuring the Database with TurboIMAGE/XL Utilities Restructuring the Database with TurboIMAGE/XL Utilities Using the utilities DBUNLOAD, DBUTIL, DBSCHEMA, and DBLOAD, certain changes to the structure of an existing database, such as capacity changes, adding additional items and sets, and repacking data sets, can be made without having to write special programs to transfer data from the old database to the new one.
Using the Database Utilities Restructuring the Database with TurboIMAGE/XL Utilities • Removing data items from the original end of a data entry definition. • Changing an automatic master to a manual master or vice versa. • Adding or deleting a data set at the end of a schema. • Changing the native language definition for the database. These are unsupported schema changes. DBLOAD does not prohibit these changes; however, the data is not guaranteed to be consistent.
Using the Database Utilities Summary of Utility Routines Summary of Utility Routines Here is a brief summary of the utilities, their commands, and their functions. Table 8-1. TurboIMAGE/XL Utilities Program Commands Function DBLOAD Loads data entries, which were copied to tape by DBUNLOAD, back into the data sets. DBRECOV Performs database recovery from log files. CONTROL Controls various options that affect the execution of DBRECOV.
Using the Database Utilities Summary of Utility Routines Table 8-1. TurboIMAGE/XL Utilities Program Chapter 8 Commands Function DETACH Detaches the database from the attached DBEnvironment(s). DISABLE Disables logging, roll-back recovery, ILR, AUTODEFER, HWMPUT, MUSTRECOVER, PREFETCH, access, third-party indexing, and dumping options. DROPINDEX Drops the associated B-Tree index.
Using the Database Utilities Utility Program Operation Utility Program Operation Database utilities can be run in either job or session mode. With the exception of DBUTIL's >>SHOW command, DBUTIL, DBSTORE, DBRESTOR, DBUNLOAD, and DBLOAD all require you to be logged on in the group and account that contains the database root file. Consequently, these utilities cannot be used with a remote database unless you initiate a remote session and run the utility as part of that session.
Using the Database Utilities DBLOAD DBLOAD Loads data entries from the backup volume(s) created by the DBUNLOAD utility into data sets of the database. Operation 1 [:FILE DBLOAD[=filename] [;DEV=device] ] 2 :RUN DBLOAD.PUB.SYS . . . 3 WHICH DATABASE? database name [/maint word] WARNING: The LANGUAGE of the database is DIFFERENT from the language found on the DBLOAD MEDIA. Continue DBLOAD operation? (Y/N): 4 DATA SET m: x ENTRIES . . .
Using the Database Utilities DBLOAD DBLOAD calls the DBPUT procedure to put the entries read from the backup volume into the appropriate data sets. In every case, the DBPUT dset parameter is a data set number and the list parameter is an at-sign followed by a semicolon (@;). Prior to calling DBPUT, DBLOAD moves each entry from the backup volume into a buffer. The length of the entry is determined by the definition of entries in the target data set.
Using the Database Utilities DBLOAD 2 Initiates execution of the DBLOAD program in the PUB group and SYS account. 3 In session mode, DBLOAD prompts for the database name and maintenance word. In job mode, the database name and maintenance word, if any, must be in the record immediately following the RUN command. The language ID of the database is stored along with data when DBUNLOAD has been used to copy the database to tape.
Using the Database Utilities DBLOAD for instructions about console interaction. Using ControlY When executing DBLOAD in session mode, ControlY can be pressed to request the approximate number of entries in the current data set that have already been copied. DBLOAD prints the following message on $STDLIST: DATA SET m:x ENTRIES HAVE BEEN PROCESSED Example :RUN DBLOAD.PUB.
Using the Database Utilities DBRECOV DBRECOV The DBRECOV program usually is executed after a backup database copy has been restored by running DBRESTOR in the event of a system failure. DBRECOV reads the log file containing records of all database modifications and re-executes the transactions against the restored database(s). The DBRECOV >FILE command enables individual users to be informed of the extent of recovery.
Using the Database Utilities DBRECOV Example 2 Roll-forward recovery of multiple databases ORDERS and RETAIL. PART and SALES are filenames, ADMIN and MKTG are accounts in the FILE commands. The 0 is the rmode and the 3 is the fmode. :RUN DBRECOV.PUB.SYS >RECOVER ORDERS DATABASE ORDERS LAST DBSTORED MON, SEP 25, 1989, 6:40 PM >CONTROL NOSTORE >RECOVER RETAIL >FILE PART,JOHN.ADMIN >FILE SALES,MARY.MKTG,0,3 >RUN Example 3 Roll-back recovery of multiple databases ORDERS and RETAIL. :RUN DBRECOV.PUB.
Using the Database Utilities DBRECOV WHICH DATABASE? ORDERS DATABASE(S) TO BE RESTARTED: ORDERS.DATAMGT.
Using the Database Utilities >CONTROL >CONTROL Used to control various options that affect the execution of DBRECOV. The options are STAMP, NOSTAMP, STORE, NOSTORE, ABORTS, NOABORTS, UNEND, NOUNEND, STOPTIME, ERRORS, STATS, NOSTATS, MODEX, MODE 4, EOF, MDBX, and NOMDBX. Syntax >CONTROL parameters [,parameters...] Discussion The >CONTROL options are described in detail on the next page.
Using the Database Utilities >CONTROL >CONTROL NOSTAMP >CONTROL STAMP In both cases, the STAMP condition cancels the previous NOSTAMP. Recovery proceeds with the time stamp check intact. If additional databases are specified for simultaneous recovery, they are all governed by the same >CONTROL options. In the specifications below, default options are shown in brackets [ ]. The default conditions for STOPTIME, ERRORS, and EOF are included with their descriptions.
Using the Database Utilities >CONTROL STOPTIME= mm/dd/yy hh:mm causes DBRECOV to impose an artificial end-of-file when the specified log record time stamp (supplied by MPE/iX) is encountered. All log records with subsequent time stamps will not be recovered. This feature is useful in the event of a user program failure; the database can be recovered to a point in time before the suspect program began execution. Default condition: Log record time stamps are not checked by DBRECOV.
Using the Database Utilities >CONTROL log file as separate transactions. If all of the databases involved in the multiple database transaction are not specified in the >RECOVER or >ROLLBACK command, DBRECOV will abort. It does not allow partial recovery of multiple data base transactions. If a multiple database transaction is dependent on any transaction that was not recovered, the multiple database transaction will be rolled out.
Using the Database Utilities >EXIT >EXIT Used to terminate DBRECOV without recovering any databases.
Using the Database Utilities >FILE >FILE Routes log records to individual user files, providing the application program with information about the outcome of recovery; provides a useful tool for auditing previous entries. One file for each user can be opened simultaneously by re-entering the >FILE command once for each user, or all users can be directed to a single file. Syntax >FILE fileref,userref [,rmode,fmode] Parameters fileref is an MPE/iX file reference: filename [/lockword] [.group[.account``]].
Using the Database Utilities >FILE transactions, use DBEND mode 2 for immediate posting of the log system's memory buffer. fmode can take one of the following values: 0 No records associated with failed transactions are copied. (Default value.) 1 Log records corresponding to the first unsuccessfully recovered call to DBBEGIN of each transaction block are copied. 2 The sequence of log records associated with the first unsuccessfully recovered transaction of each transaction block are copied.
Using the Database Utilities >PRINT >PRINT Prints the names of databases specified for recovery (DBTABLE option) or recovery files specified (FILETABLE option). Can be used as a check before actually initiating recovery with the >RUN command. NOTE The >PRINT DBTABLE command produces the DATABASE STATISTICS table, but does not include statistics. The table, along with statistics, is automatically displayed by every execution of the recovery system.
Using the Database Utilities >RECOVER >RECOVER Used to designate the name of a database to be roll-forward recovered; opens database root file, validates logid and password with MPE/iX, and checks the DBSTORE flag. Multiple databases can be roll-forward recovered concurrently if they have all logged to the same log file by entering the >RECOVER command once for each database or as follows: >RECOVER database name, database name Syntax >RECOVER database name[/maint word][.group[.
Using the Database Utilities >RECOVER erroneous data in the database if the database is recovered with the wrong log file. 4. The DBSTORE flag must be set, indicating that the database has not been modified between restoration and roll-forward recovery. This check can be overridden by the NOSTORE option of the >CONTROL command. 5. No other users can be accessing the database when >RECOVER is called.
Using the Database Utilities >ROLLBACK >ROLLBACK Rolls out any incomplete transactions following a system crash. Multiple databases can be roll-back recovered concurrently by entering the command as follows: >ROLLBACK dbname, dbname Syntax >ROLLBACK dbname[/maint word][.group[.account]] Parameters database name is the name of individual database(s) to be rolled-back. maint word is the maintenance word defined by the database creator. This word must be supplied by anyone other than the database creator.
Using the Database Utilities >ROLLBACK can be concurrently accessed by users when the >CONTROL command is specified with the MODE4 option. The >ROLLBACK command itself does not initiate recovery, but makes several preparatory checks. The recovery system is actually initiated by the >RUN command. The following commands are used with >ROLLBACK: >FILE >PRINT >CONTROL The >FILE command optional parameter rmode is not used with >ROLLBACK.
Using the Database Utilities >RUN >RUN Initiates recovery-process. The recovery system opens the log file and validates the log identifier before roll-forward recovery or roll-back recovery begins. Syntax >RUN Discussion For recovery to succeed, the log file must be accessible to the database administrator.
Using the Database Utilities >RUN Example 1 Roll-forward recovery of database ORDERS. :RUN DBRECOV.PUB.SYS >RECOVER ORDERS DATABASE ORDERS LAST DBSTORED FRI, SEP 22, 1989, 4:00 PM >RUN Example 2 Roll-back recovery of database ORDERS. :RUN DBRECOV.PUB.
Using the Database Utilities DBRESTOR DBRESTOR Copies a database to disk from the backup volume(s) created by the DBSTORE program or by the MPE/iX STORE command. Operation 1 2 [ :FILE DBRESTOR [=filename] [;DEV=device] [;REC=recsize] [; {BUFNOBUF} ]] :RUN DBRESTOR.PUB.SYS . . . 3 WHICH DATABASE? database name [/maint word] 4 DATABASE RESTORED END OF PROGRAM Parameters filename is a name (up to 8 characters) that replaces DBRESTOR in the mount prompt at the operator's console.
Using the Database Utilities DBRESTOR Console Messages After you supply the database name and DBRESTOR opens the file specified by filename, a message is displayed on the system console. A tape must be mounted on the appropriate unit and identified through an operator reply. Refer to Volume Management Reference Manual for instructions about console interaction. If the database is on more than one volume, another message is displayed on the system console.
Using the Database Utilities DBSTORE DBSTORE Stores the database root file and all data sets to a tape in a format compatible with backup files created by the MPE STORE and SYSGEN commands. DBSTORE differs from these commands in that it handles only TurboIMAGE/XL databases. Operation 1 [:FILE DBSTORE [=filename] [;DEV=device] [;REC=recsize] [; { BUF NOBUF} ] ] 2 :RUN DBSTORE.PUB.SYS [;INFO="MPE STORE options"] . . .
Using the Database Utilities DBSTORE parameter (INFO="TRANSPORT") allows you to migrate files from MPE/iX to MPE V with the MPE/iX STORE command. Operation Discussion 1 The optional file equation that specifies the device class name for the device on which the database is to be stored, the record size of the records written to the device, and whether records are to be buffered. The default device class is TAPE. 2 Initiates execution of the DBSTORE program in the PUB group of the SYS account.
Using the Database Utilities DBSTORE either an MPE SYSGEN or STORE command could have been used instead of DBSTORE. Because neither SYSGEN or STORE update the database time stamp and store flag, the protection afforded by these mechanisms is not available if this form of backup is selected. For this reason, it is highly recommended to use DBSTORE as the backup facility when logging. See chapter 7 for further discussion of logging and recovery.
Using the Database Utilities DBSTORE TurboSTORE/iX 7x24 True-Online Backup You can also use TurboSTORE/iX 7x24 True-Online Backup to back up your database. The advantages of using the option ONLINE=START or ONLINE=END are: • You can store the database even when it is open for access. • The related files including TC file, third-party indexing files, jumbo data set files, and B-Tree index files are also stored along with it. • The DBSTORE flag and time stamp are also set before storing the database.
Using the Database Utilities DBUNLOAD DBUNLOAD Copies the data entries from each data set to specially formatted tape volumes. Operation 1 [:FILE DBUNLOAD[=filename] [;DEV=device] ] 2 :RUN DBUNLOAD.PUB.SYS [ ,CHAINED ,SERIAL ] . . . 3 WHICH DATA BASE? database name [/maint word] . . .
Using the Database Utilities DBUNLOAD n is the number of the volume. y is the number of write errors from which DBUNLOAD has successfully recovered. z is the logical device number of the unit. DBUNLOAD is necessary if you want to modify the database structure to, for example, increase the capacity of a data set. To increase a capacity, 1. Unload the entries. 2. Purge the database. 3. Change the schema and create a new root file. 4. Execute the DBUTIL >>CREATE command. 5.
Using the Database Utilities DBUNLOAD Broken Chains If a chained DBUNLOAD encounters a broken chain, it will unload all entries in the chain down to, but not including the break. It will then go to the end of the chain and follow the chain backward to the break, then unload the remaining records of the chain. In some instances, this will save all entries in the chain. In any case, the order of the entries is preserved.
Using the Database Utilities DBUNLOAD DATA SET m: x ENTRIES[EXPECTED, t LOST!!] For example: 5 DATA SET 1: 3 ENTRIES DATA SET 2: Broken Chain at Entry #2, following Entry #1 Chain Head is Entry #5 of Data Set #1 KEY = AA 4 entries expected, 3 entries salvaged DATA SET 2: 11 ENTRIES EXPECTED; 1 LOST!! When the end of a volume is encountered, DBUNLOAD prints this message: END OF VOLUME n, y WRITE ERRORS RECOVERED where n is the number of the volume and y is the number of write errors from which DBU
Using the Database Utilities DBUNLOAD Writing Errors If an unrecoverable write error occurs, DBUNLOAD prints the message: UNRECOVERABLE WRITE ERROR, RESTARTING AT BEGINNING OF VOLUME and attempts to recover by starting the current volume again.
Using the Database Utilities DBUNLOAD DATA DATA DATA DATA DATA DATA SET SET SET SET SET SET 1: 2: 3: 4: 5: 6: 50 9 24 12 5 0 ENTRIES ENTRIES ENTRIES ENTRIES ENTRIES ENTRIES EXPECTED, EXPECTED, EXPECTED, EXPECTED, EXPECTED, EXPECTED, 50 ENTRIES PROCESSED. 9 ENTRIES PROCESSED. 24 ENTRIES PROCESSED. 12 ENTRIES PROCESSED. 5 ENTRIES PROCESSED. 0 ENTRIES PROCESSED.
Using the Database Utilities DBUNLOAD Figure 8-1.
Using the Database Utilities DBUTIL DBUTIL The DBUTIL program performs several different functions according to the command you enter. Each DBUTIL command is described separately on the following pages. Operation 1 :RUN DBUTIL.PUB.SYS 2 >>command Operation Discussion 1 Initiates execution of the DBUTIL program in the PUB group of the SYS account. 2 Prompts for a DBUTIL >>command.
Using the Database Utilities DBUTIL or semicolons, that defines a password to be used by anyone other than the database creator to enable them to execute certain DBUTIL commands, and operate other utilities. (The database creator can also define or change the maintenance word by using the >>SET command). In job mode, the database name and maintenance word, if any, must be in the record immediately following the RUN command.
Using the Database Utilities >>ACTIVATE >>ACTIVATE Activates the database-access file for use with DBOPEN. Before using this command, read the description of remote database access in chapter 9. This command should be used to prepare a database-access file before accessing a remote database residing on another HP 3000.
Using the Database Utilities >>ACTIVATE where is "Looks good" if there are no errors associated with the record. Appendix A lists the record errors (results) that would cause the file to be rejected. Example :RUN DBUTIL.PUB.SYS Initiate DBUTIL execution. . . . >>ACT ORDDBA Enter abbreviated form of ACTIVATE command and database-access file name.
Using the Database Utilities >>ADDINDEX >>ADDINDEX The ADDINDEX command updates the root file, and adds the associated B-Tree index file. When using the ALL option and there is no master dataset, a warning is generated, but the command is considered to be successful. Syntax >>ADDI[NDEX] database name [/maintword] FOR { ALL setnamelist setnumlist } For example: >>ADDINDEX ORDERS FOR ALL where ORDERS is the database name. Parameters database name is the name of a TurboIMAGE database.
Using the Database Utilities >>CREATE >>CREATE Creates and initializes a file for each data set in the database. Once the Schema Processor has created the root file, the database creator must build a file for each data set in the database using the >>CREATE command. DBUTIL initializes each data set to zeros and saves it as a catalogued MPE/iX file in the same logon group as the root file, on the device classes specified in the schema.
Using the Database Utilities >>CREATE Example (Session Mode) :RUN DBUTIL.PUB.SYS Initiate DBUTIL executions. . . . >>CREATE ORDERS Respond to DBUTIL prompt with >> CREATE command and database name. Database ORDERS has been CREATED >> DBUTIL creates, initializes, and saves files named ORDERS01, ORDERS02, and so forth, one file for each data set. These constitute the empty database. Example (Job Mode) :JOB MGR.ACCOUNTA :RUN DBUTIL.PUB.SYS CREATE ORDERS EXIT :EOJ Initiate job. Initiate DBUTIL execution.
Using the Database Utilities >>DEACTIVATE >>DEACTIVATE Deactivates the database-access file to allow modifications to the file or to disallow remote database access. This command is used before you change the contents of the database-access file. (Refer to chapter 9 for more information about accessing remote databases.) If DBUTIL successfully deactivates the file, it prints a confirmation message on the list file device.
Using the Database Utilities >>DETACH >>DETACH The DETACH command detaches the database from the DBEnvironment(s) the database is attached to. You can use one command of DBUTIL to detach a given database from all of the DBEnvironments to which it is attached; you do not have to specify each DBEnvironment name. If you copy your database to a different account or different group, then issue a DETACH command for the copied database, you will get an error stating that the detach failed from dbename.group.
Using the Database Utilities >>DISABLE >>DISABLE Disables the access, automatic deferred output, data prefetching, dumping, ILR, indexing, MUSTRECOVER, logging, and recovery options. Syntax >>DI[SABLE] database name[/maint word] FOR option[,option...] For example: DISABLE ORDERS FOR LOGGING,RECOVERY where ORDERS is the database name, and LOGGING and RECOVERY are the options.
Using the Database Utilities >>DISABLE FORCESESSION disables a program opening the database to use session name or job name to replace the user identifier in the DBOPEN log record. HWMPUT disables DBPUT action of placing entries at the high-water mark first, instead of at the delete chain head. ILR disables Intrinsic Level Recovery facility. INDEXING disables third-party indexing (TPI) for the database.
Using the Database Utilities >>DISABLE Example :RUN DBUTIL.PUB.SYS . . .
Using the Database Utilities >>DROPINDEX >>DROPINDEX The DROPINDEX command drops the associated B-Tree index file and updates the root file. When using the ALL option and there is no master dataset, a warning is generated, but the command is considered to be successful. Syntax >>DROPI[NDEX] database name [/maintword] FOR { ALL setnamelist setnumlist } For example: >>DROPINDEX ORDERS FOR 2 where ORDERS is the database name and 2 is set# 2. Parameters database name is the name of a TurboIMAGE/XL database.
Using the Database Utilities >>ENABLE >>ENABLE Enables the access, automatic deferred output, data prefetching, dumping, ILR, indexing, MUSTRECOVER, logging, and recovery options. Syntax >>EN[ABLE] database name[/maint word] FOR option[,option...] For example: ENABLE RETAIL FOR LOGGING where RETAIL is the database name and LOGGING is an option. Parameters database name is the name of a TurboIMAGE/XL database being enabled.
Using the Database Utilities >>ENABLE detect the dead lock among locks issued by users.. DSEM enables use of Dependency Semaphore for increased concurrency of modification intrinsics (DBPUT, DELETE, and DBUPDATE with CIU ON). DUMPING is an option for Hewlett-Packard support use, development, and debugging only. When enabled, the TurboIMAGE/XL abort procedure copies the user's stack and the database control blocks to files if a TurboIMAGE/XL procedure aborts.
Using the Database Utilities >>ENABLE Forcesession ius Disabled HWMPUT is Disabled ILR is Disabled Indexing is Disabled Logging is Disabled Mustrecover is Disabled Oldinfolimits is Disabled Prefetch is Disabled Recovery is Disabled Roll-Back is Disabled Example :RUN DBUTIL.PUB.SYS . . .
Using the Database Utilities >>ERASE >>ERASE Reinitializes all data sets in the database to their empty condition and resets all flags except the access, PREFETCH, and recovery flags (refer to the discussion of the DBUTIL >>ENABLE command earlier in this chapter). The data sets remain as catalogued MPE/iX files. To execute DBUTIL to reinitialize the data sets, you must be the database creator or supply the correct maintenance word.
Using the Database Utilities >>ERASE DBUTIL reinitializes all the data sets in the ORDERS database to binary zeroes. With the exception of the access, PREFETCH, and recovery flags, the database flags are reset to their default conditions. The logging and MUSTRECOVER options are disabled if they were previously enabled. NOTE The execution of utilities is not logged.
Using the Database Utilities >>EXIT >>EXIT Terminates DBUTIL execution. Syntax >>E[XIT] Example >>CREATE ORDERS Create a database. Database ORDERS has been CREATED >>EXIT If no other DBUTIL functions are to be performed, terminate DBUTIL with >>EXIT command.
Using the Database Utilities >>HELP >>HELP Displays each of the DBUTIL commands. >>H[ELP] [commandname] Parameter commandname is the name of a specific DBUTIL command whose format you want to display. The name can be abbreviated to the minimum command abbreviation permitted by DBUTIL. If you do not specify a command, the >>HELP command lists the names of all valid DBUTIL commands. If you specify a command, the correct syntax for that command is displayed.
Using the Database Utilities >>MOVE >>MOVE Moves TurboIMAGE/XL files across devices within the same volume set. Syntax >>M[OVE] TurboIMAGE/XL file name TO device For example: MOVE ORDERS05 to DISC2 where ORDERS05 is the file name and DISC2 is a device. Parameters file name is a TurboIMAGE/XL root file, data set, or ILR file. Enter the file name only; no group/account specification is allowed. The user must be the creator of the file.
Using the Database Utilities >>MOVE 3. Checks the root file to determine the database state. 4. Copies the old file to the new file. 5. Sets the flag in the root file. 6. Purges the old file, then saves the new file. 7. Resets the flag in the root file. For jumbo datasets, the MOVE command enables you to move either the chunk control file or a specific chunk data file to a different device. The MOVE command does not allow a B-Tree index (".idx") file to be moved.
Using the Database Utilities >>PURGE >>PURGE Purges the root file and all the data sets of the referenced database. If you use third-party indexing, the >>PURGE command also purges any existing third-party index files regardless of third-party indexing being enabled or disabled. Purging removes the files from the catalog and returns the disk space to the system. As with >>ERASE, you must be the database creator or must provide the maintenance word to use DBUTIL with the >>PURGE entry.
Using the Database Utilities >>PURGE Message Meaning No root file, >>PURGE operation proceeding DBUTIL was unable to locate the root file, but will attempt to purge data set, if any. Data set XXXXk has been purged DBUTIL successfully purged the root file and the n data sets of the database. However, DBUTIL also discovered and purged an unexpected data set named XXXXk, where k is a number greater than the number of data sets defined for the database (n).
Using the Database Utilities >>PURGE together with the group name and the account name where the database resides for confirmation: >>PURGE ORDERS/SELL Database selected -- ORDERS.MYGROUP.MYACCT Do you want to continue with PURGE (Y/N)? DBUTIL will not prompt for confirmation if it is not in interactive mode.
Using the Database Utilities >>REBUILDINDEX >>REBUILDINDEX REBUILDINDEX rebuilds the B-Tree index file for a specified dataset that should have an index file. When using the ALL option and there is no master dataset, a warning is generated, but the command is considered to be successful. The KSAM file built by REBUILDINDEX has the Native Language Support language specified to match the language of the database, if the key is a text (X or U) data type.
Using the Database Utilities >>REDO >>REDO Redo the previous command or the previous nth command. Redo follows exactly the MPE/iX REDO syntax. REDO, LISTREDO, and DO work for DBUTIL the same was as the MPE/iX commands. Syntax >>REDO [n] For example: >>REDO 8 where 8 is the eighth previous command. Parameter n Chapter 8 is the backwards count of the command being repeated.
Using the Database Utilities >>RELEASE >>RELEASE Suspends file system security provisions for the database root file and data sets, allowing access to the database from other groups and accounts. If you use third-party indexing, the >>RELEASE command suspends the file system security provisions for any existing index files. Syntax >>R[ELEASE] database name For example: RELEASE ORDERS where ORDERS is the database name. Parameter database name is the name of a TurboIMAGE/XL database.
Using the Database Utilities >>SECURE >>SECURE Restores security provisions that were released by a >>RELEASE command for the database root file and data sets. If you use third-party indexing, the >>SECURE command restores the security provisions for any existing index files. Syntax >>SE[CURE] database name For example: >>SECURE ORDERS where ORDERS is the database name. Parameter database name is the name of a TurboIMAGE/XL database being secured.
Using the Database Utilities >>SET >>SET Changes or removes the maintenance word; only the database creator can change or remove the maintenance word. The >>SET command also sets the log identifier into the root file, modifies access class passwords, sets a subsystem flag, and sets the critical item update (CIUPDATE) option.
Using the Database Utilities >>SET databases that will be migrated to MPE V, it sets the number of buffers to be allocated by TurboIMAGE in the Database Buffer Area `Control Block (DBB). Refer to "Moving from MPE/iX to MPE V" in appendix H for a discussion of BUFFSPECS and a description of its parameters. LOGID sets the MPE/iX log identifier. The log identifier is obtained using the MPE/iX GETLOG command.
Using the Database Utilities >>SET change the language ID. This command can be issued only on a virgin root file or an empty database. NOTE When reloading the database, the language must match the language ID stored in the backup media. A DBLOAD issued in a job fails if the language of the media differs from the database language. A DBLOAD in session mode provides a prompt to allow you to complete the DBLOAD operation when you reply Y. sets critical item update for the database.
Using the Database Utilities >>SET doing a B-Tree DBFIND, mode-1-style arguments are scanned to find the first occurrence of the current wildcard character in the argument text. If the wildcard is not found, a non- B-Tree search is done (even if the DBFIND mode was 21). If the wildcard is found, the rest of the argument text is ignored. NOTE This does not match the functionality of "@" in commands such as the MPE LISTF, but does match the functionality of current TPI implementations.
Using the Database Utilities >>SET Example 3 :RUN DBUTIL.PUB.SYS Initiate DBUTIL. . . . >>SET ORDERS BTREEMODE1 = ON,% Sets BTREEMODE1 option on for B-Tree search for DBFIND mode 1 on X or U type having a B-Tree index (explicit or implicit) and in the presence of a wildcard character in the argument. Sets the wildcard character as % in the ORDERS database.
Using the Database Utilities >>SHOW >>SHOW Displays information about the database on a terminal or line printer. This can include a list of processes that have the database open, the status of locks in the database, the log identifier and flags, the current buffer specifications, and the setting for the critical item update option. Displays the capacity expansion information for the database and the data sets.
Using the Database Utilities >>SHOW by account, you must have SM capability. maint word is the current maintenance word for the database. The database creator or the user with SM capability can omit the maintenance word. ALL displays all the information provided with MAINT, BUFFSPECS, LANGUAGE, LOCKS, USERS, LOGID, SUBSYSTEMS, FLAGS, and the last-stored date. Displays number of detail data sets using dynamic capacity expansion and if dynamic capacity expansion is used for master data sets.
Using the Database Utilities >>SHOW SUBSYSTEMS indicates whether subsystems, including user programs, can access the TurboIMAGE/XL database and, if access is allowed, whether it is read only or both read and write. Subsystem access is enforced by the subsystem. USERS displays a list of the processes that have the database open with the program file name and other information. (Refer to examples below.) OFFLINE requests that the information be listed on the line printer.
Using the Database Utilities >>SHOW Example (Show All) . . . >>SHOW ORDERS ALL Display all information for ORDERS database. For database ORDERS MAINTENANCE WORD: SELL Access is enabled. Autodefer is disabled. Dumping is disabled. Rollback recovery is disabled. Recovery is enabled. ILR is disabled. Mustrecover is enabled. Logging is enabled. Prefetch is disabled. Indexing is disabled. HWMPUT is disabled. Add entry into lock table for deadlock detect is enalbled. Restart is disabled.
Using the Database Utilities >>SHOW Example Discussion The listing above indicates that the current buffer specifications provide for 50 buffers to be allocated when there are between 1 and 120 concurrent users of the database. On TurboIMAGE/XL the buffer specifications remain fixed, so the information shown in the above listing is useful only for databases that will be migrated to an MPE V system.
Using the Database Utilities >>SHOW Third Party Indexes are registered in these HPSQL DBEnvironments: DBEname DBEname Refer to the IMAGE/SQL Administration Guide for more information. The example displays, "Dynamic capacity expansion is used for 2 detail sets." Enable this feature for new databases by using the capacity parameters for detail data sets. See chapter 3 for more information. Enable this feature for existing databases by using DBChange Plus or a third-party utility.
Using the Database Utilities >>SHOW Volume set: MPE/iX volname File Name ORDERS.IMAGE.DATAMGT ORDERS01.IMAGE.DATAMGT ORDERS02.IMAGE.DATAMGT ORDERS03.IMAGE.DATAMGT ORDERS04.IMAGE.DATAMGT ORDERS05.IMAGE.DATAMGT ORDERS06.IMAGE.DATAMGT Data Set Name Device Date-Master Customer Product Sup-Master Inventory Sales DISC DISC1 DISC1 DISC1 DISC2 DISC3 DISC2 >> where volname is the name of the volume set in which the database resides.
Using the Database Utilities >>SHOW TurboIMAGE/XL must wait until all existing locks on the current lock item are cleared before it places a lock on the new lock item. During the wait the lock is termed "TEMP." These locks are held very briefly and only under rare circumstances. The Process Identification Numbers (PINs) and job/session numbers listed are the same as those shown by MPE/iX commands, such as SHOWJOB and SHOWQ.
Using the Database Utilities >>SHOW Example 1 (Show Locks) . . . >>SHOW ORDERS LOCKS OFFLINE List the status of locks requested and held in the ORDERS database on the line printer. The line printer listing looks similar to this: HP30391C.00.
Using the Database Utilities >>SHOW Example 2 (Show Locks) Here is another example of a locking list that might appear when the >>SHOW LOCKS command is entered. HP30391C.00.
Using the Database Utilities >>VERIFY >>VERIFY Reports whether a remote database-access (RDBA) file is activated or deactivated and checks the validity of the RDBA file. Syntax >>V[ERIFY] database-access file name For example: VERIFY ORDDBA where ORDDBA is the database-access file name. Parameter database-access file name is the name of a remote database-access file. Example :RUN DBUTIL.PUB.SYS Initiate DBUTIL execution. . . .
Using the Database Utilities >>VERIFY 464 Chapter 8
Using a Remote Database 9 Using a Remote Database You can access a TurboIMAGE/XL database that resides on one HP 3000 computer system while operating a session on another HP 3000 computer system if both systems are configured with Network Services capability. You can access a TurboIMAGE/V database from an MPE/iX system or a TurboIMAGE/XL database from an MPE V system.
Using a Remote Database Access Through a Local Application Program Access Through a Local Application Program If you want to access a remote database using a local application program, you have three methods to choose from. • Establishing communications link and remote session interactively. • Using the COMMAND intrinsic. • Using a database-access file. In all three cases, a local program accesses a remote database and the data is passed across the communication line.
Using a Remote Database Access Through a Local Application Program To use this method you must issue a REMOTE HELLO command (either with the DSLINE parameter or issue the DSLINE as a separate command) and a FILE equation by calling the COMMAND intrinsic for each of these commands. Use of the COMMAND intrinsic is explained in the MPE/iX Intrinsics Reference Manual, and information about accessing remote files is given in the NS3000/XL User/Programmer Reference Manual. Figure 9-3.
Using a Remote Database Access Through a Local Application Program Figure 9-4. Using Method 3 Using the database-access file, only one database can be accessed using each database-access file per DSLINE. For example, if two computers are linked through two DSLINEs, you can open one database on each line. When the user or an application program calls DBOPEN with the database-access file name, the remote session is established and the remote database is opened.
Using a Remote Database Access Through a Local Application Program Creating a Database-Access File The content of the database-access file should be created in the format shown below. Syntax Record 1 FILE dbname1=dbname2:nodename Record 2 DSLINE nodename[; . . .] (See NS3000/XL document for applicable parameters.) Record 3 lusername.lacctname[,lgroupname]=HELLO rusername [/rupasw] .racctname[/rapasw][,rgroupname[/rgpasw]] . . . (See MPE/iX commands document for additional parameters.
Using a Remote Database Access Through a Local Application Program remote account. It follows the same rules as username. An at-sign (@) can be used to indicate rusername as with lusername. (Required parameter.) rupasw is the password assigned to username. (Optional parameter.) racctname is the name of the logon account on the remote HP 3000. It follows the same rules as lacctname. An at-sign (@) can be used to indicate racctname is the same as lacctname. (Required parameter.
Using a Remote Database Access Through a Local Application Program Example Record 1 FILE ORDERS=ORDERS:NODEX Record 2 DSLINE NODEX Record 3 USERA.ACCTA,GROUPA=HELLO USERB.ACCTA,GROUPB Record 4 @.ACCTA,GROUPA=HELLO USERA.ACCTA,GROUPA Record 5 USERB.ACCTB,@=HELLO USERB.ACCTX,@ End of file If a user logs on with the logon identification indicated in the first column below, TurboIMAGE/XL uses the corresponding USER.
Using a Remote Database Access Through a Local Application Program Activating a Database-Access File After you have constructed a database-access file, you must use the DBUTIL utility program to activate the file. The complete syntax for running the utility program is given in chapter 8. Here is a summary of the operating instructions: :RUN DBUTIL.PUB.SYS . . .
Using a Remote Database Access Through a Local Application Program DBUTIL. The remaining keyword parameters are checked by the command interpreter at DBOPEN time. If all of the above conditions are met, DBUTIL successfully activates the database-access file, by changing the file code to the TurboIMAGE/XL reserved code −402, which makes it a privileged (PRI V) file.
Using a Remote Database Access Through a Local Application Program Figure 9-5. Preparing a Database-Access File 1 2 3 :HELLO MEMBER1.PAYACCT . . . :EDITOR HP32201A.00.00 EDIT/3000 FRI, SEP 6, 1991, 3:30 PM (C) HEWLETT-PACKARD CO. 1985 /ADD 1 FILE ORDERS=ORDERS:NODEX 2 DSLINE NODEX 3 MEMBER1.PAYACCT=HELLO MEMBER1.PAYACCT 4 MEMBER2.PAYACCT=HELLO @.PAYACCT 5 // 4 /KEEP ORDDBA,UNN /END 5 :RUN DBUTIL.PUB.
Using a Remote Database Access Through a Local Application Program In this sample case, after logging on to the local system, the user runs the program named APPLICAN from the local session. The base array in this program contains ORDDBA. When a call to DBOPEN is executed, TurboIMAGE/XL establishes a communication line and remote session. When the program closes the database, TurboIMAGE/XL closes the line and terminates the remote session. Figure 9-6.
Using a Remote Database Access Using QUERY/3000 Access Using QUERY/3000 When you use QUERY/3000 to retrieve information from a database, you must specify a database name, password and access mode before you can actually access the database. The "DATABASE=" prompt can be answered with a remote database name or the database-access file name.
Internal Structures and Techniques 10 Internal Structures and Techniques In addition to the data elements discussed in chapter 2, TurboIMAGE/XL uses a number of internal structures and techniques to provide rapid and efficient access to the database content. This chapter describes these structures and techniques to give you an overview of the way TurboIMAGE/XL works. NOTE Chapter 10 In this manual a word is a 32-bit storage unit and a halfword is a 16-bit storage unit. One byte is 8 bits.
Internal Structures and Techniques Data Set Internal Structures Data Set Internal Structures The following internal structures are used by TurboIMAGE/XL to manage the information in data sets. Pointers TurboIMAGE/XL uses pointers to link one data set record to another. A pointer is a value containing the block number in the first three bytes plus one byte that contains the offset within the block for a given data entry.
Internal Structures and Techniques Data Set Internal Structures path. Figure 10-1. Media Record for Detail Entry Media Records of Master Data Sets Media records of master data entries are composed of the following: • A 10-byte field serving as a synonym chain head for primary entries or a synonym chain link for secondary entries. • A 3 times n word field in which the chain heads of all related detail chains are maintained. n is the number of paths defined for the master data set.
Internal Structures and Techniques Data Set Internal Structures Figure 10-3. Media Record for Secondary Entry When more than one detail chain head is present, they are physically ordered left-to-right in the order that the associated paths are specified in the schema. Primary Entries Selection of record addresses for master entries begins with a calculated address determined by a hashing algorithm applied to the value of each entry's key item. The algorithm is described later in this chapter.
Internal Structures and Techniques Data Set Internal Structures The first two bytes of the 10-byte link in the media record of each secondary entry are always zero. The remaining eight bytes consist of two pointers bi-directionally linking the secondary entries of the synonym chain to each other. As with detail chains, the first member of this chain of secondary entries contains a zero backward pointer, and the last member of the chain contains a zero forward pointer.
Internal Structures and Techniques Dynamic Data Set Expansion Dynamic Data Set Expansion The capacity of non-jumbo (less than or equal to 4 GB in size) master and detail data sets can be expanded dynamically during DBPUT, or implied DBPUT for automatic master. The expansion can occur only if the data set is enabled for dynamic expansion, that is, if the required capacity parameters are set prior to the expansion.
Internal Structures and Techniques Dynamic Data Set Expansion You can select data sets which need dynamic expansion based on anticipated growth.
Internal Structures and Techniques Dynamic Data Set Expansion expanded area is controlled using the pointer to a delete chain head and an end-of-file pointer (high-water mark) as in detail data sets. To elaborate further, when a DBPUT for manual master, or implied DBPUT to an automatic master, is processed, the address where the new entry resides is based on the following: 1. If the primary address in the original area is not occupied, the new entry resides there.
Internal Structures and Techniques Scalability Scalability In versions prior to C.07.00, TurboIMAGE/XL serialized the execution of DBPUT, DBDELETE, and DBUPDATE when critical item update (CIU) is enabled, to protect the structural integrity of the database. This serialization is done via a semaphore known as PUTDELETE semaphore. This translates into processing only one DBPUT, DBDELETE, or DBUPDATE with CIU enabled at a time for every database.
Internal Structures and Techniques Scalability In the above diagram, the independent sub-databases are: 1. M1 2. D1 3. D2 and M2 4. D3 and M3 5. D4 and M3 6. D5, M4 and M5 7. D6, M5 and M6 There are several different scenarios when concurrent modifications can be in progress. For example: M1 at all times as there is no dependency. D1 at all times as there is no dependency. Other masters M2, M3, M4, M5, and M6 if the depending detail is not being modified. Other details D2, D3 or D4, and D5 or D6.
Internal Structures and Techniques Large Size Datasets in TurboIMAGE/iX Large Size Datasets in TurboIMAGE/iX Dataset Size Limitations The IMAGE database management system has been around for more than two decades. When HP first introduced the product, the maximum size of a dataset was limited to the MPE file size. However, when users felt the need for much larger dataset sizes, the 'JUMBO' feature was introduced.
Internal Structures and Techniques Large Size Datasets in TurboIMAGE/iX database needs to be created in the entrynumber format, there is a new $CONTROL LARGESET directive in DBSCHEMA. Once DBSCHEMA encounters this directive, it will create the root file to support large datasets, and set the 'root version' to 'C6'. It may be noted that a database, as a whole, will need to support large size datasets (in other words, one can not define a particular dataset alone to be in entrynumber format).
Internal Structures and Techniques Large Size Datasets in TurboIMAGE/iX Bit # Value/ Description 09 1: Database uses new limits (# of sets = 240, # of items = 1200, # paths per masters = 64) 0: Database uses old limits (# of sets = 199, #of items = 1024, # paths per master = 16) 08-01 Unused Migration Utility Existing databases can be moved to support large datasets through the migration utility provided with the solution. The migration utility is DBBIGSET.PUB.
Internal Structures and Techniques Run-Time TurboIMAGE/XL Control Blocks Run-Time TurboIMAGE/XL Control Blocks As mentioned in chapter 4, TurboIMAGE/XL uses control blocks resident in privileged mapped files to provide and control user access to a database through the TurboIMAGE/XL procedures. The contents of these control blocks are maintained by TurboIMAGE/XL.
Internal Structures and Techniques Run-Time TurboIMAGE/XL Control Blocks account as the database. NOTE If you have an existing file with the same name that TurboIMAGE/XL would assign to the permanent mapped file (that is, dbnameGB), you will get the following message for status code −9: CANNOT CREATE DBG : MPE ERROR The DBG is derived mostly from the root file and contains global information required by TurboIMAGE/XL intrinsics during run-time.
Internal Structures and Techniques Run-Time TurboIMAGE/XL Control Blocks The TURBOGTX is a permanent file, TURBOGTX.PUB.SYS, that is created by DBXBEGIN (if it does not exist beforehand). Thereafter, it is opened for all users who employ dynamic multi-database transaction(s) (DMDBX). Each system has only one TURBOGTX file, and it remains on the system even after the system is rebooted. It is used for tracking DMDBX.
Internal Structures and Techniques Internal Techniques Control Block Sizes It is not necessary to predict the exact length of the control blocks used by TurboIMAGE/XL to manage user accesses to databases. However, the exact length of the DBU and the exact current length of the DBG are returned in the status array by DBOPEN. These lengths can be truncated to 32767 if the control block is greater than 32767.
Internal Structures and Techniques Internal Techniques result in poor DBPUT performance. This method should be used only if you have determined that the potential poor performance consequences cannot occur. The intent of the two primary address algorithms is to spread master entries as uniformly as possible throughout the record space of the data file. This uniform spread reduces the number of synonyms occurring in the master data set.
Internal Structures and Techniques Internal Techniques before the record is added, the assigned record address is the primary address. If the bit is a one before the record is added, it indicates that an entry already exists. If this existing entry is a primary entry, a search is done to find a free location, secondary address, for the new entry.
Internal Structures and Techniques Internal Techniques Buffer Management TurboIMAGE/XL maintains a set of buffer partitions in the DBB for all users of an open database. DBFIND, DBGET, DBUPDATE, DBPUT, and DBDELETE locate a buffer header from one of these partitions. Each partition is allocated its own buffer header pool, hash table, and free list. The buffer header pool is a set of buffer headers allocated for the accessors of its corresponding partition.
Internal Structures and Techniques MPE/iX Transaction Management MPE/iX Transaction Management When AUTODEFER is not enabled, TurboIMAGE/XL uses an internal MPE/iX service, called Transaction Management (XM), to ensure physical consistency of the database, to reduce physical disk I/O, to perform Intrinsic Level Recovery (ILR), and to perform dynamic roll-back recovery. When XM is used, modifying intrinsics (DBPUTs, DBDELETEs, and DBUPDATEs) are bracketed as XM transactions.
Internal Structures and Techniques System Limits System Limits The following is a table that shows the current limits in TurboIMAGE. The left column describes the resource(s) based on the unit. The right column is the maximum number it can have. For example, ‘Opened databases/system’ means ‘numbers of databases that can concurrently be opened on a system’; ‘Data items/database’ means ‘numbers of items that can be defined within a database’.
Internal Structures and Techniques System Limits Table 10-1. Static System Limits Resource Limit Opened databases / system 2004 Data items / database 1200 Data sets / database 240 Passwords / database 63 Data items / data set 255 Paths / data set (Master --Detail) 64 Paths / data set (Detail--Master ) 16 No.
Internal Structures and Techniques System Limits 500 Chapter 10
B-Tree Indices Overview of B-Tree Indices 11 B-Tree Indices This chapter is new with the release which includes the enhancement to support B-Tree indices (C.07.00). This chapter gives an overview of the B-Tree index enhancement. It addresses changes in TurboIMAGE/XL utilities and intrinsics, and presents a quick start for using B-Tree indices.
B-Tree Indices Overview of B-Tree Indices have keys that satisfy the DBFIND criteria. The total of all corresponding chains in a detail data set is referred to as a super-chain. TurboIMAGE/XL fetches each qualifying master entry in order to determine the total number of associated detail entries to calculate the sum of the chain counts. To retrieve all qualified entries in a detail data set using DBGET, TurboIMAGE "walks" (traverses) this super-chain. B-Tree Search is the same as B-Tree DBFIND.
B-Tree Indices Overview of B-Tree Indices Key Points These are the key points of TurboIMAGE/XL B-Tree indices: • You can create a B-Tree index only on the key item of the master data set. • Although you can create a B-Tree index only for the key item of a master data set, you can still perform a B-Tree search using the search items of all of its corresponding detail sets as well.
B-Tree Indices Overview of B-Tree Indices b. DBFIND modes with added functionality pertaining to B-Tree indices: 1 can continue to work as it does in releases prior to the release of B-Tree index feature (C.07.00), despite the presence of a B-Tree index, or it can be used for a B-Tree search if BTREEMODE1 is ON. 4 used for B-Tree index searches on numeric as well as ASCII types and returns accurate chain (super-chain) counts. Requires a structured argument.
B-Tree Indices External Commands and Utilities Affected the master data set key value. No pointer information is present in the B-Tree index records. d. The KSAM file has the Native Language Support language specified to match the language of the database, if the key is a text (X or U) data type. • Record zero of the root file contains "C4" for the root file version if at least one B-Tree index file exists for the database.
B-Tree Indices External Commands and Utilities Affected Example NAME: Employeename, MANUAL /INDEXED(10,20/30); DBUTIL DBUTIL has three new commands: • ADDINDEX • DROPINDEX • REBUILDINDEX Syntax for ADDINDEX ADDI[NDEX] database name [/maintword] FOR { ALL setnamelist setnumlist } Syntax for DROPINDEX DROPI[NDEX] database name [/maintword] FOR { ALL setnamelist setnumlist} Syntax for REBUILDINDEX REBUILDI[NDEX] database name [/maintword] FOR { ALL setnamelist setnumlist} Parameters setnamelist is the lis
B-Tree Indices External Commands and Utilities Affected language of the database, if the key is an ASCII (X or U) data type. When using the ALL option and there is no master data set, a warning is generated, but the command is considered to be successful. Other DBUTIL Commands The following lists the impact of B-Tree indices on other DBUTIL commands: • CREATE does an implicit ADDINDEX command for each data set marked by DBSCHEMA as indexed. • ERASE erases any associated B-Tree index (.
B-Tree Indices External Commands and Utilities Affected >> show ORDERS all For database ORDERS ... Dynamic capacity expansion is not used. BTREEMODE1 is off, wildcard = "@" Logid is not present. ... New Syntax for SHOW SHOW has a new option INDEX, alternatively INDEXES or INDICES. SHOW database name [/maintword] INDEX >>SHOW ORDERS INDEX For database ORDERS Database root version < "C"4; there are no indexes. >>addindex orders for all Found 4 master datasets.
B-Tree Indices External Commands and Utilities Affected NOTE General use of privileged mode can seriously damage your system, if not used wisely. Mode 13 Mode 13 is used to perform functions related to B-Tree index files. The caller must be privileged. Exclusive database access is required for adding, dropping, and rebuilding B-Tree index, that is functions 1, 2, and 3. Qualifier has a structured record containing data set information and directives.
B-Tree Indices External Commands and Utilities Affected Element Contents 1 Function code: 0 mode support inquiry (returns "OK" in status, and ignores the rest of the record). That is, to validate if mode 14 is supported in the TurboIMAGE software on the system. 1-6 reserved for internal use. 7 set wildcard (in root file, not DBU). Wildcard is in lower 8 bits of the second element of qualifier. An error is returned if the value is less than ASCII 33, or greater than ASCII 126.
B-Tree Indices External Commands and Utilities Affected Supported Modes of DBFIND These are modes of DBFIND supported by the B-Tree index feature: 1 do a B-Tree DBFIND if all of the following are true: • BTREEMODE1 is on. • The item type is X or U. • The item has a B-Tree index (explicit or implicit). • The argument contains wildcard character. Otherwise execute DBFIND as done without this feature.
B-Tree Indices External Commands and Utilities Affected TPI Modes of DBFIND Not Supported for B-Tree Indices Third-Party Indexing (TPI) adds more DBFIND modes. The TPI modes 1 and 10 are similar to B-Tree index modes 1 and 10. NOTE These are the known Third Party Indexing (TPI) modes of DBFIND which are NOT supported for B-Tree searches: 11 do a B-Tree index DBFIND when the key is binary. 12 is a keyword search. other 1nn, 2nn, 3nn, 4nn, and 5nn are other unsupported TPI DBFIND modes.
B-Tree Indices External Commands and Utilities Affected c. The chain count is the sum of all chain counts (that is, the number of entries in the super-chain for a B-Tree DBFIND). Record number for the last entry is obtained from the last entry in the last chain. For first entry, record number of the first entry in the first chain is obtained. For masters, the chain count reflects the total number of master entries qualified, and last entry and first entry values are zeroes. d.
B-Tree Indices External Commands and Utilities Affected @c wildcard search. Scan argument for the first wildcard character. (Call that character position n, 1-based). Search for keys that match first n−1 characters of argument. If c is non-blank and non-null, then it is the wildcard character that will be used. Some examples are: @* and @@. If c is a blank or null, then the current default wildcard (stored in the root file) is used.
B-Tree Indices External Commands and Utilities Affected {*REAL* dbf_arg1_data is variable sized} {*REAL* dbf_arg2_data is variable sized} spare_area : packed array [1..256] of {8 @ x} char; {if present, arg2 data starts at record + 8 + arg1_bytes} end; {8 + 256 + 256} Examples of Structured Argument Three examples of using the structured argument type are given below.
B-Tree Indices External Commands and Utilities Affected arg arg arg arg arg arg [2] [3] [4] [5] [6] [7] = = = = = = (char) (char) (char) (char) (char) (char) 0; 0; 0; 20; 0; 0; /* /* /* /* /* /* upper half of version */ bottom half of version */ upper half of arg1 size field */ bottom half of arg1 size field */ upper half of arg2 size field */ bottom half of arg2 size field */ strcpy (arg [8], "SMITH@"); Example 4 I2 field, looking for keys >= 123 and <= 45698, using SPL: double array arg'd (0 : 3)
B-Tree Indices External Commands and Utilities Affected DBINFO DBINFO has new modes 113 and 209. Mode 113 DBINFO mode 113 reports the wildcard character in use for the database, and the value of BTREEMODE1. The qualifier is ignored.
B-Tree Indices External Commands and Utilities Affected DBPUT, DBDELETE, and DBUPDATE DBPUT and DBDELETE trigger similar operation to the associated B-Tree index file for all adds or deletes to or from a master data set. DBUPDATE to a master is not allowed even when critical item update is on. Adding a record to the B-Tree index file is done with an FWRITE call. The KSAM files do not have the DUP option, so KSAM will reject FWRITEs that attempt to add a duplicate key value.
B-Tree Indices Limits Limits These are some limits on the use of B-Tree indices: • Key limits KSAM limits keys up to 255 bytes. TurboIMAGE/XL limits keys to 510 bytes (255 halfwords). TurboIMAGE items are always an even number of bytes in length, with 2 bytes for internal use. This means that the maximum TurboIMAGE key that can be indexed is 252 bytes. Attempting to build an index for a master data set whose key is greater than 252 bytes will not succeed, and will generate an error message.
B-Tree Indices Quick Start for Using B-Tree Indices Quick Start for Using B-Tree Indices If you are interested in generic trailing-@ searches only and want to get started quickly without making any application changes, you may use the following steps. 1. Identify the masters with ASCII key item and can benefit from B-Tree indices. 2. Create B-Tree indices using either of these methods: a. Use the INDEXED option of DBSCHEMA for new databases. b. Use the ADDINDEX command of DBUTIL for existing databases. 3.
Error Messages A Error Messages TurboIMAGE/XL issues three different types of error messages: • Schema Processor Error Messages • Library Procedure Error Messages • Utility Error Messages Schema processor error messages result from errors detected during processing of the database schema. The library procedure error messages are returned to the calling program from the library procedures. The utility error messages are caused by errors in execution of the database utility programs.
Error Messages Schema Processor Error Messages Schema Processor Error Messages The Schema Processor accesses three files: • The text file (DBSTEXT) containing the schema records and Schema Processor commands for processing. • The list file (DBSLIST) containing the schema listing, if requested, and error messages, if any. • The root file, if requested, created as a result of an error-free schema.
Error Messages Schema Processor Error Messages Schema Processor File Errors Various file error messages are listed in this section. Each such message is preceded by the character string: ****** FILE ERROR ****** Additionally, the Schema Processor prints a standard MPE file information display on the $STDLIST file. MESSAGE FILE ALREADY EXISTS; UNABLE TO CLOSE file name MEANING FCLOSE error occurred on specified file. Can be caused by duplicate file in group with same name as root file.
Error Messages Schema Processor Error Messages MESSAGE WRITE ERROR ON file name MEANING FWRITE error occurred on the specified file. ACTION Change database name or purge file of same name. Or, be sure correct file and file name used. Check MPE FILE commands used. If other cause, consult MPE/iX Intrinsics Reference Manual for similar message.
Error Messages Schema Processor Error Messages Schema Processor Command Errors Various Schema Processor command error messages are listed in this section. Each such message is preceded by the character string: ***** ERROR ****** MESSAGE COMMAND CONTINUATION NOT FOUND MEANING If the schema processor command is continued to the next record, the last non-blank character of the preceding line must be an ampersand (&) and the continuation record must start with a dollar sign ($).
Error Messages Schema Processor Error Messages ACTION 526 Examine the schema text file to find any incorrect commands. Edit the text file, and run the Schema Processor again.
Error Messages Schema Processor Error Messages Schema Syntax Errors Database definition syntax errors can be detected by the Schema Processor. Their existence does not cause termination but does prohibit root file creation. Discovery of one can trigger others which disappear after the first is corrected. Also, detection of one can preclude detection of others which appear after the first is corrected.
Error Messages Schema Processor Error Messages MESSAGE BAD DATA SET TYPE MEANING The data set type designator is not AUTOMATIC (or A), MANUAL (or M), or DETAIL (or D). ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE BAD DEVICE CLASS NAME MEANING The device class name specified contains an invalid character. The name must be less than eight characters and begin with a letter.
Error Messages Schema Processor Error Messages MESSAGE BAD PATH SPECIFICATION DELIMITER MEANING Name of master data set following search item name in detail data set definition is not followed by a right parenthesis ")" or by a sort item name in parentheses. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again.
Error Messages Schema Processor Error Messages MESSAGE BAD TERMINATOR- ';' OR ',' EXPECTED MEANING Items within an entry definition must be separated from each other with commas and terminated with a semicolon. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE BAD TYPE DESIGNATOR MEANING Data item defined in schema item part is not defined as type I, J, K, R, U, X, Z, or P. ACTION Examine the schema text file to find the error.
Error Messages Schema Processor Error Messages MESSAGE DATABASE HAS NO DATA SETS MEANING No data sets were defined in the set part of schema. The database must contain at least one data set. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE DATABASE NAME TOO LONG MEANING Database name has more than six characters. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again.
Error Messages Schema Processor Error Messages MESSAGE 'ENTRY:' EXPECTED MEANING Each set defined in the set part of schema must contain ENTRY statement followed by the data item names of the data items in entry. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE ENTRY LENGTH SHOULD BE LESS THAN 2048 MEANING Entry length exceeds 2047 halfwords. ACTION Examine the schema text file to find the error.
Error Messages Schema Processor Error Messages MESSAGE ILLEGAL USER CLASS NUMBER MEANING User class number defined in schema password part is not an integer between 1 and 63. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE INCREMENT NUMBER TOO LARGE MEANING The increment number of entries, or the entries calculated from the percent, exceeded maximum capacity minus initial capacity.
Error Messages Schema Processor Error Messages the Schema Processor again. MESSAGE ITEM TOO LONG MEANING The length of a single data item cannot exceed 2047 halfwords. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE 'LANGUAGE:' EXPECTED MEANING The Schema Processor expected to find a LANGUAGE statement after the comma following the BEGIN DATABASE name statement. ACTION Examine the schema text file to find the error.
Error Messages Schema Processor Error Messages MESSAGE MORE THAN ONE KEY ITEM MEANING A master data set cannot be defined with more than one key item. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE MORE THAN ONE PRIMARY MASTER MEANING User has defined more than one primary path for a detail data set. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again.
Error Messages Schema Processor Error Messages MESSAGE REFERENCED SET NOT MASTER MEANING The data set referenced by the detail data set search item is another detail data set instead of a master data set. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again.
Error Messages Schema Processor Error Messages MESSAGE SORT ITEM OF BAD TYPE MEANING Data item defined as sort item must be of type U, K, or X. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE SORT ITEM NOT IN DATA SET MEANING Detail data set's entry definition does not include an item which is specified as a sort item for another item in the entry. ACTION Examine the schema text file to find the error.
Error Messages Schema Processor Error Messages MESSAGE TOO MANY PATHS IN DATA SET MEANING Detail data set entries cannot have more than 16 search items. ACTION Examine the schema text file to find the error. Edit the text file, and run the Schema Processor again. MESSAGE UNDEFINED ITEM REFERENCED MEANING A data item appearing in the data set definition was not previously defined in the item part of schema. ACTION Examine the schema text file and find the incorrect statement.
Error Messages Library Procedure Error Messages Library Procedure Error Messages The success of each call to a TurboIMAGE/XL library procedure is reflected upon return to the user by the condition code and the value of the return status in the first element of the status area. If the procedure fails to execute properly, the condition code is set to CCL (Condition Code Less) and the return status is a negative integer.
Error Messages Library Procedure Error Messages Abort Conditions In general, four types of error conditions can cause TurboIMAGE/XL to abort the calling process: 1. A call from a Compatibility Mode user process with the hardware DB register not pointing to the process stack. 2. A structurally damaged database. 3. An internal error in an MPE file intrinsic which the calling procedure cannot correct. 4. An internal inconsistency in the database or the DBG, DBB, or DBU discovered by a library procedure.
Error Messages Library Procedure Error Messages Library Procedure File System and Memory Management For return status values −1 through −6, the second element of the calling program's status area is the data set number for which file error occurred (zero indicates root file). The third element is the MPE failure code returned by the FCHECK intrinsic. Refer to MPE documentation for meaning of this code.
Error Messages Library Procedure Error Messages -3 -4 -5 -6 -7 -8 542 MESSAGE MPE file error nn returned by FREADDIR on root file or data set nn MEANING This is an exceptional error (as −2 above) and is returned by DBOPEN, DBFIND, DBGET, DBUPDATE, DBPUT, DBDELETE. ACTION Notify system manager of error.
Error Messages Library Procedure Error Messages -9 -10 Appendix A MESSAGE Cannot create control block name: MPE file error %nn MEANING This is an exceptional error returned when DBOPEN fails to call HPFOPEN to create a control block. ACTION Notify system manager or HP support personnel. MESSAGE MPE file error %nn returned by FFILEINFO on root file or data set nn MEANING This is an exceptional error returned when DBOPEN fails to call FFILEINFO on the root file.
Error Messages Library Procedure Error Messages Library Procedure Calling Errors -11 -12 -12 -13 -14 544 MESSAGE Bad base reference MEANING For DBOPEN, the first two characters in base are not blank, or database name contains special characters other than period. For all other procedures, either first two characters in base do not contain the value assigned by DBOPEN or the parameters passed to the procedure are incorrect in type, sequence, or quantity.
Error Messages Library Procedure Error Messages mode 5, 6, 7, or 8. -15 -21 -21 ACTION Modify program or notify current user that operation cannot be performed. MESSAGE Setup for RDBA failed MEANING DBOPEN will issue a DSLINE command and a REMOTE HELLO on behalf of the user if a DBA file is being used for RDBA. One of these commands failed. ACTION Check your DBA file to make sure the DSLINE and REMOTE HELLO commands are correct.
Error Messages Library Procedure Error Messages -21 MESSAGE Bad data item reference (See above for additional status code −21 messages.) MEANING For DBINFO (modes 101, 102, and 204), data item reference is: • Numeric but out of range of the number of data items in database • An erroneous data item name • A reference to data item which is inaccessible to user class established when database opened. An erroneous data item name can arise when a terminating semicolon or blank is omitted.
Error Messages Library Procedure Error Messages -31 -32 MESSAGE Bad mode MEANING This error occurs in all procedures when the mode parameter is invalid. For DBGET, mode is 7 or 8 and referenced data set is a detail, or mode is 5 or 6 and referenced data set is a detail without search items. ACTION Correct mode in procedure call.
Error Messages Library Procedure Error Messages -51 MESSAGE Bad list length MEANING For DBGET, DBUPDATE, and DBPUT, the list is too long. This can occur if list is not terminated with a semicolon or blank. It can also occur for otherwise legitimate lists which are too long for TurboIMAGE/XL's work area. It will never occur for numeric lists. -52 ACTION Shorten list array contents. If necessary, change to numeric list.
Error Messages Library Procedure Error Messages -61 -80 -81 -82 -88 Appendix A MESSAGE Error while obtaining information about file equation. MEANING HPSWITCHTOCM procedure failed while trying to evaluate the file equation used for DBOPEN. ACTION Correct the file equation. If that does not resolve the error, notify your system manager.
Error Messages Library Procedure Error Messages -89 -90 -91 -92 -93 550 MESSAGE Database bad: Restructuring was in process (restore database). MEANING DBChangePlus is restructuring the database or was restructuring the database but failed in the middle. ACTION Notify database administrator. Restore the database and redo restructuring if failed. MESSAGE Root file bad: unrecognized state: %octal integer MEANING For DBOPEN, this error is returned if the root file is in an unrecognized state.
Error Messages Library Procedure Error Messages -94 -95 -96 -97 -98 Appendix A MESSAGE Database bad - Output deferred; may not be accessed in mode nn MEANING For DBOPEN, referenced database was damaged while being modified in deferred output. ACTION Either DBLOAD from backup tape; or DBUNLOAD to ERASE data and then DBLOAD.
Error Messages Library Procedure Error Messages -99 MESSAGE UNSUPPORTED FEATURE. MEANING A feature unavailable in TurboIMAGE is attempted. ACTION Change the application to not use the feature that has not been implemented. Return statuses −100 through −107 are communication errors. For −100 through −102, the third element of the calling program's status area is the MPE failure code returned by DSCHECK intrinsics.
Error Messages Library Procedure Error Messages -104 -105 -106 -107 -108 -109 Appendix A MESSAGE Remote 3000 does not support TurboIMAGE/XL MEANING This is an exceptional error and is returned by DBOPEN on the remote system. ACTION Notify system manager of problem. MESSAGE Remote 3000 cannot create TurboIMAGE control block. MEANING This is an exceptional error and is returned by DBOPEN on the remote system. ACTION Notify system manager of problem.
Error Messages Library Procedure Error Messages -110 -111 -112 -113 -114 -120 554 MESSAGE MPE OPENLOG intrinsic failure MEANING OPENLOG returned error number nn to DBOPEN. This error can occur following a call to DBOPEN when a database is enabled for logging. Refer to MPE/iX Intrinsics Manual for listing of second values of status array and error messages. ACTION Notify system manager or HP support personnel.
Error Messages Library Procedure Error Messages -121 -123 -124 -125 -126 -127 Appendix A MESSAGE Descriptor count error MEANING DBLOCK detected an error in the descriptor count (first element of qualifier array) in locking mode 5 or 6. ACTION Count must be a positive integer. MESSAGE Illegal relop in a descriptor MEANING DBLOCK encountered a relop field containing characters other than >=, <=, = or =. ACTION Check contents of qualifier array. MESSAGE Descriptor too short.
Error Messages Library Procedure Error Messages -128 -129 -130 -131 -132 -133 556 MESSAGE Value field too short in a descriptor MEANING A value field in a DBLOCK lock descriptor must be at least as long as the data item for which it is specified. ACTION Check the length of the value field. MESSAGE P-type item longer than P28 specified MEANING DBLOCK does not allow P-type data items longer than 28 in lock descriptors (27 digits plus sign).
Error Messages Library Procedure Error Messages -134 -135 -136 -137 -139 -140 Appendix A MESSAGE Two descriptors conflict MEANING DBLOCK has detected two lock descriptors in the same call that lock the same or part of the same database entity. (For example, lock on set and database in same request.) ACTION Check qualifier array contents for conflicting lock descriptors.
Error Messages Library Procedure Error Messages -141 -142 -143 -144 -145 558 MESSAGE All MDBX databases must be on same system. MEANING An attempt was made to begin a multiple database transaction (MDBX) on remote databases when all databases were not located on the same system (node). ACTION Modify your application program to only perform multiple database transactions on databases which are located on the same system. MESSAGE All MDBX databases must log to the same log file.
Error Messages Library Procedure Error Messages -146 -147 -148 -151 -152 -153 Appendix A MESSAGE Invalid transaction ID. MEANING The transaction ID used in a call to DBBEGIN and in the call to its corresponding DBEND do not match. ACTION Contact your database administrator or application programmer. MESSAGE Mode doesn't match DBBEGIN mode. MEANING The DBBEGIN mode and its corresponding DBEND mode must match. ACTION Contact your database administrator or application programmer.
Error Messages Library Procedure Error Messages -160 -161 -166 -167 -168 -169 560 MESSAGE ILR log file name conflict MEANING A user file has the same name as the ILR log file name. ACTION Replace the user file with a valid MPE ILR log file. MESSAGE Cannot check for an ILR log file conflict: file system error nn MEANING DBUTIL DISABLE command or call to DBOPEN failed to open ILR log file. ACTION Check file system error number.
Error Messages Library Procedure Error Messages -170 -172 -173 -174 -175 -176 Appendix A MESSAGE Cannot open ILR log file: file system error nn MEANING DBUTIL DISABLE command or call to DBOPEN was not able to open ILR log file due to file system error. ACTION Check file system error number. MESSAGE Cannot read ILR log file: file system error nn MEANING DBUTIL DISABLE command or call to DBOPEN was not able to read ILR log file due to file system error.
Error Messages Library Procedure Error Messages -177 -178 -179 -180 -181 562 MESSAGE MPE log file is not in the same volume set as the database. MEANING MPE transaction recovery requires that the user log file must reside in the same volume set as the database. ACTION Build the MPE user log file in same volume set as database. NOTE: Because all files in a group are in same volume set, the MPE LISTGROUP command indicates the volume set where a database resides.
Error Messages Library Procedure Error Messages GROUP= option to restore the database. To avoid this error, disable ILR when moving a database from one group and account to another group and account. -182 -183 -184 Appendix A MESSAGE ILR log invalid - internal account name does not match root file MEANING DBUTIL DISABLE command or call to DBOPEN attempted to open ILR log file, but account names do not match. (See error −180 for possible cause.
Error Messages Library Procedure Error Messages -187 -188 -189 -190 -191 -192 -193 564 MESSAGE ILR is already enabled for this database MEANING DBUTIL ENABLE command attempted to enable a database for ILR when ILR was already enabled. ACTION Warning only. MESSAGE ILR is already disabled for this database MEANING DBUTIL DISABLE command attempted to disable a database for ILR when ILR was already disabled. ACTION Warning only.
Error Messages Library Procedure Error Messages -194 -195 -196 -197 -198 -199 -200 Appendix A MESSAGE Invalid DBB MEANING The database buffer control block has been corrupted. ACTION Notify HP support personnel. MESSAGE Invalid DBG MEANING The database global control block has been corrupted. ACTION Notify HP support personnel. MESSAGE DBB control block is full MEANING The database buffer control block is full. ACTION Notify HP support personnel.
Error Messages Library Procedure Error Messages -201 -202 -204 -205 -206 566 MESSAGE Native Language Support not installed MEANING NLS/3000 internal structures have not been built at system start-up. The collating sequence table of the language of the database is unavailable; DBOPEN cannot open the database. ACTION Notify system manager. MESSAGE MPE Native Language Support error nn returned by NLINFO MEANING The error number given was returned by NLS/3000 on a NLINFO call in DBOPEN.
Error Messages Library Procedure Error Messages -208 -209 -210 -211 -212 -213 -214 Appendix A MESSAGE MPE error nn returned by FLABELINFO for MPE XL XM MEANING MPE file system error nn was returned by the intrinsic FLABELINFO. ACTION Notify HP support personnel. MESSAGE Invalid mode for MPE XL XM DETACH MEANING An internal error has occurred. ACTION Notify HP support personnel.
Error Messages Library Procedure Error Messages -215 -216 -217 -218 -219 -220 568 ACTION Correct the application. MESSAGE M error nn encountered when rolling out a dynamic transaction. MEANING This is an internal error. ACTION Notify your system manager and HP support personnel. MESSAGE Cannot end a dynamic transaction with DBEND MEANING A transaction started by DBXBEGIN cannot use DBEND. ACTION Replace the DBEND call with a call to DBXEND.
Error Messages Library Procedure Error Messages -221 -222 -223 -224 -225 -226 Appendix A MESSAGE Cannot begin a transaction when a dynamic transaction is active MEANING Each DBOPEN can have only one dynamic transaction active at one time. ACTION Check the application to make sure that only one dynamic transaction is active at one time.
Error Messages Library Procedure Error Messages -227 -228 -229 -230 -231 -232 570 ACTION Notify your database administrator and HP support personnel. MESSAGE Error occurred in 00 file recovery MEANING An internal error has occurred. ACTION Notify your database administrator and HP support personnel. MESSAGE BXBEGIN encountered XM error nn when starting a dynamic transaction MEANING An internal error has occurred. ACTION Notify your database administrator and HP support personnel.
Error Messages Library Procedure Error Messages transaction. -233 -234 -235 -236 -237 Appendix A ACTION Move the DBCLOSE call outside of the dynamic transaction, or, if appropriate, change the DBCLOSE mode to 3. MESSAGE Key data found in database does not match that in the memo record MEANING An internal error has occurred. ACTION Notify your database administrator and Hewlett-Packard support personnel.
Error Messages Library Procedure Error Messages -238 -240 -241 -242 -243 -244 -245 572 MESSAGE MDBX, MODES OF DBXBEGIN/DBXEND DON'T MATCH. MEANING DBXUNDO or DBXEND call, including the mode, does not match with the dynamic multi-database transaction started by DBXBEGIN. ACTION Correct the application. MESSAGE ERROR IN DYNAMIC ROLLBACK. MEANING The dynamic transaction could not be rolled back successfully. ACTION Notify HP support personnel. MESSAGE BAD TAG FOR TURBOLKT TABLE.
Error Messages Library Procedure Error Messages -246 -250 -251 -253 -254 -255 Appendix A MESSAGE ERROR IN TURBOGTX OPERATION RELATED TO ATC TRANSACTION. MEANING Internal error encountered while updating the table, TURBOGTX.PUB.SYS, as there is still an active SQL transaction in the table. ACTION Notify HP support personnel. MESSAGE CBINIT FAILED ON nn MEANING The initialization of a semaphore failed. ACTION Notify HP support personnel. MESSAGE DBS WAS OBTAINED BUT NOT RELEASED.
Error Messages Library Procedure Error Messages -256 -257 -258 -259 -260 -261 574 MESSAGE Third-party index for path nn is full MEANING This message is returned if you are using third-party indexing (TPI). The index file for the indicated path is full; nn represents the path number. ACTION Consult your third-party vendor documentation. MESSAGE Third-party index for path nn is damaged MEANING This message is returned if you are using third-party indexing (TPI).
Error Messages Library Procedure Error Messages -262 -263 -264 -265 -266 -267 Appendix A MESSAGE OLDER/INCOMPATIBLE VERSION OF IMAGE/SQL. MEANING The version of IMAGE/SQL on the system is incompatible with TurboIMAGE/XL. ACTION Notify your system administrator. MESSAGE INVALID PCODE RETURNED BY TPI. MEANING The third-party indexing product returned an unsupported or invalid pcode to IMAGE/SQL. ACTION Notify your system administrator or third-party vendor.
Error Messages Library Procedure Error Messages -268 -269 -270 -3nn -305 -306 -307 -308 576 MESSAGE INVALID PCODE RETURNED BY TPS MEANING The third-party shadowing product returned an unsupported or invalid pcode to IMAGE/SQL. ACTION Notify your HP personnel. MESSAGE WRITE ERROR FOR TPS FILES. MEANING The transaction management encountered error while writing to third-party shadowing files. ACTION Notify your HP personnel.
Error Messages Library Procedure Error Messages -309 -310 -312 -314 -322 -323 -331 -332 -333 Appendix A MESSAGE BUFFER IO NOT YET COMPLETE. MEANING An internal error encountered while performing internal buffer I/O of the data set. ACTION Notify your HP personnel. MESSAGE ERROR RELATED TO END OF FILE. MEANING An internal error encountered while obtaining the end of file information. ACTION Notify your HP personnel. MESSAGE INTERNAL ERROR ENCOUNTERED WHILE READING DATABASE BLOCK.
Error Messages Library Procedure Error Messages -420 -421 -422 -423 -424 -425 -426 -427 578 ACTION Notify your HP personnel. MESSAGE FEATURE NOT IMPLEMENTED. MEANING Use of a feature not supported for B-Tree indices is detected. ACTION Correct your application. MESSAGE BTE: unknown qualifier value for DBCONTROL mode 13. MEANING The function code in the qualifier that passed to DBCONTROL is invalid. ACTION Modify the program. MESSAGE BTE: data set# not in valid range.
Error Messages Library Procedure Error Messages -428 -429 -430 -431 -432 -433 -434 -436 Appendix A MESSAGE BTE: Rebuildindex failed. MEANING The process of rebuilding the B-Tree failed. ACTION Check the third and fourth halfword of the qualifier parameter you passed to DBCONTROL for the status. This value should provide extra error information in HPERRMSG format. Notify HP support personnel. MESSAGE BTE: DBFIND argument version is bad.
Error Messages Library Procedure Error Messages -437 -438 -439 -440 -441 -442 580 ACTION Check the third and fourth halfword of the qualifier parameter you passed to DBCONTROL for the status. This value should provide extra error information in HPERRMSG format. Notify HP support personnel. MESSAGE BTE: Failed to convert @c to [] dbfind. MEANING Failed to convert wildcard or "greater than relation" into a "range relation". ACTION Notify HP support personnel.
Error Messages Library Procedure Error Messages -443 -444 -446 -447 Appendix A MEANING Releasing the B-Tree file from GROUP/ACCOUNT security has failed in DBCONTROL mode 13 call. ACTION Check the third and fourth halfword of the qualifier parameter you passed to DBCONTROL for the status. This value should provide extra error information in HPERRMSG format. Notify HP support personnel. MESSAGE BTE: SECURE of index file failed.
Error Messages Library Procedure Error Messages -448 -449 -451 -452 -458 -1000 582 MESSAGE BTE: Failed to setup information for userlabel 0 of data set. MEANING The procedure that writes data to user label #0 of a data set has failed. ACTION Notify HP support personnel. MESSAGE BTE: Failed to position index at start of key range. MEANING The procedure to position the B-Tree pointer to the first key that satisfies the current DBFIND has failed. ACTION A REBUILDINDEX may solve the problem.
Error Messages Library Procedure Error Messages returned from that subsystem. -1001 Appendix A ACTION Notify HP support personnel. MESSAGE Switch to CM failed on CX'PCBXIMAGE MEANING Internal error. This error is returned when DBOPEN calls CM CX'PCBXIMAGE and encounters a switch to CM failure. ACTION Notify HP support personnel.
Error Messages Library Procedure Error Messages -1002 -1003 -1004 -1025 584 MESSAGE HPLOADCMPROCEDURE failed on CX'PCBXIMAGE MEANING Internal error. This error is returned when DBOPEN calls HPLOADCMPROCEDURE for CM CX'PCBXIMAGE and fails. ACTION Notify HP support personnel. MESSAGE Switch to NM failed on DBxxx, INFO nn SUSSYS nn MEANING The switch to Native Mode failed. DBxxx is the TurboIMAGE/XL intrinsic. SUBSYS nn is the subsystem that failed.
Error Messages Library Procedure Error Messages Library Procedure Exceptional Conditions 10 11 12 13 14 15 Appendix A MESSAGE Beginning of file MEANING DBGET has encountered beginning of file during a backward serial read. (No entries exist before the one previously accessed.) ACTION Appropriate action depends on program design. MESSAGE End of file MEANING DBGET has encountered the end of file during a forward serial read. (No entries exist beyond the most recently accessed one.
Error Messages Library Procedure Error Messages 16 16 16 16 586 MESSAGE Data set full MEANING DBPUT has discovered that data set is full and cannot add a record as requested. (Message received when return status word 1 is 16, and word 3 is 0.) ACTION Restructure database with larger capacity for this data set. (See chapter 8 for information on changing data set capacity in conjunction with DBUNLOAD and DBLOAD.
Error Messages Library Procedure Error Messages 17 17 18 MESSAGE No master entry (See below for additional status code 17 message.) MEANING DBFIND is unable to locate master data set entry (chain head) for specified detail data set's search item value. ACTION Appropriate action depends on program design. MESSAGE No entry (See above for additional status code 17 message.
Error Messages Library Procedure Error Messages 20 22 23 24 25 588 MESSAGE Database locked or contains locks MEANING DBLOCK Mode 2: The database cannot be locked. Refer to value of status element three: If 0, database already locked; if 1, database contains locked sets or entries. Mode 4, 6: The lock cannot be granted because the whole database is already locked. ACTION Appropriate action depends on program design.
Error Messages Library Procedure Error Messages 26 41 Appendix A MESSAGE Lock not performed since deadlock would result. MEANING If it is a self-deadlock, the database or data set is already locked by the same process but with a different open count. If it is locked by another process, it is because of the DBLOCK call from another user that the real deadlock is encountered. ACTION To avoid the self-deadlock, modify the program. If it is a real deadlock caused by another process, call DBUNLOCK.
Error Messages Library Procedure Error Messages 41 41 590 MESSAGE DBUPDATE: No chain head (master entry) for path decimal integer: nn MEANING User has called DBUPDATE to update a detail data set entry with a search item value that does not match any existing key item value in the corresponding manual master data set. The digits nn identify the offending path number established by the sequence in which the detail data set search items appear in the set part of the schema.
Error Messages Library Procedure Error Messages 41 41 42 Appendix A MESSAGE DBUPDATE: Full automatic master for path decimal integer: nn (See above and below for additional status code 41 messages.) MEANING Automatic master data set is full. User has called DBUPDATE to update a search item in a detail data set, and the corresponding key item value could not be added to the automatic master data set.
Error Messages Library Procedure Error Messages 43 44 49 50 51 592 MESSAGE Duplicate key item value MEANING DBPUT has been asked to insert a data entry into a master data set with a key item value which already exists in the data set. ACTION Appropriate action depends on program design. MESSAGE Can't delete master entry with non-empty detail chains MEANING DBDELETE has been asked to delete a master data set entry which still has one or more non-empty chains.
Error Messages Library Procedure Error Messages 52 53 60 61 62 Appendix A MESSAGE INVALID PARAMETER FOR BASIC - IMAGE INTERFACE. MEANING The call to TurboIMAGE/XL intrinsic has invalid parameters. ACTION Correct the application. MESSAGE INVALID PARAMETER TYPE FOR BASIC - IMAGE INTERFACE. MEANING The call to TurboIMAGE/XL intrinsic has invalid type for the parameter(s). ACTION Correct the application.
Error Messages Library Procedure Error Messages 63 MESSAGE DBG disabled; potential damage; only DBCLOSE allowed MEANING Another process sharing the database has aborted because of logical inconsistency or internal error in TurboIMAGE/XL, leaving DBG in potentially inconsistent state. All user accesses through existing DBG are disabled (except for DBCLOSE, mode 1). Returned by all intrinsics. If the database has been enabled for dumping, an I and a J file should exist.
Error Messages Library Procedure Error Messages 68 MESSAGE Bad DBB MEANING Another process sharing the database has aborted because of logical inconsistency or internal error in TurboIMAGE/XL, leaving DBB in potentially inconsistent state. All user accesses through existing DBB are disabled (except for DBCLOSE, mode 1). Returned by all intrinsics. If the database has been enabled for dumping, an I and a J file should exist. These files can help determine the cause of the error.
Error Messages Library Procedure Error Messages 1nn 2nn 3nn 596 MESSAGE No chain head (master entry) for path decimal integer: nn MEANING User has attempted to add detail data entry with a search item value that does not match any existing key item value in corresponding manual master data set. The digits represented by nn identify the offending path number established by the order in which the search items occur in the set part of the schema.
Error Messages Library Procedure Error Messages 4nn 944 Others MESSAGE Full automatic master synonym chain for path decimal integer: nn MEANING User has attempted to add a detail data set search item associated with an automatic master data set that cannot accommodate another new value on the synonym chain for that path number. The digits nn identify the offending path number established by the sequence in which the detail data set search items appear in the set part of the schema.
Error Messages Library Procedure Error Messages MESSAGE CRITICAL READ ERROR ON data set MEANING While reading database file, MPE file read error was encountered. ACTION Notify the database administrator and possibly HP support personnel. Save FID information if it is printed. You might need to perform database recovery procedures. (See chapter 7). MESSAGE ERROR intrinsic name STATUS return status; DBERROR/DBEXPLAIN FAILED I info S subsys MEANING The specified intrinsic encountered an error.
Error Messages Library Procedure Error Messages MESSAGE NEGATIVE MOVE ATTEMPT: n MEANING An internal software inconsistency has been found while attempting to move data to or from user's stack. ACTION Notify the database administrator and HP support personnel if necessary. MESSAGE THE intrinsic name parm PARAMETER NOT ALIGNED ON A 16-BIT BOUNDARY MEANING The designated parameter, parm, is 8-bit aligned. ACTION Modify your application so that the parm parameter is 16-bit (halfword) aligned.
Error Messages Library Procedure Error Messages MESSAGE WRONG NUMBER OF PARAMETERS OR BAD ADDRESS FOR PARAM #n MEANING An address referenced by one of the parameters is not within the user's stack area in memory. The n is a positional number of the parameter in the procedure's calling sequence. The first parameter is #1, the second #2, and so on. ACTION Modify your application so that the parm parameter is 16-bit (halfword) aligned.
Error Messages Utility Error Messages Utility Error Messages Two types of error messages are generated by the utility programs. The first type is conditional errors, which occur when a utility cannot begin a function. Conditional errors do not cause utility program termination; this is discussed in more detail below. The second type is unconditional errors, which occur when a utility cannot complete a function. Unconditional errors usually cause program termination.
Error Messages Utility Error Messages MESSAGE AUTODEFER MUST BE DISABLED BEFORE ILR CAN BE ENABLED MEANING AUTODEFER option in DBUTIL has been enabled for the database. ROLLBACK or ILR cannot be enabled while deferred output is enabled. ACTION Use DBUTIL to disable AUTODEFER and enable ILR or ROLLBACK for the database. MESSAGE AUTODEFER MUST BE DISABLED BEFORE ROLLBACK CAN BE ENABLED MEANING The rollback recovery option cannot be used when the database has been enabled for AUTODEFER.
Error Messages Utility Error Messages MESSAGE CANNOT OPEN DATABASE MEANING The database cannot be opened at this time. It could already be open in a mode that does not allow concurrent access. ACTION Try the DBUTIL command again later. MESSAGE CANNOT PARSE LOG FILE NAME MEANING Internal error. ACTION Contact your database administrator. MESSAGE Cannot process data set file filename MEANING Cannot read/write to the file due to a file system error.
Error Messages Utility Error Messages MESSAGE CURRENT SINGLE TRANSACTION DOESN'T MATCH LOG TRANSACTION MEANING Internal error. ACTION Contact your database administrator. MESSAGE CURRENT TRANSACTION DOESN'T MATCH LOG FILE TRANSACTION MEANING Internal error. ACTION Contact your database administrator. MESSAGE DATABASE-ACCESS FILE DOES NOT EXIST MEANING No such file exists in the logon user or account. ACTION Check the files in group to determine the correct file name.
Error Messages Utility Error Messages MESSAGE DATABASE CONFIGURED FOR INDEXING USING third-party product name MEANING This message is returned if you are using third-party indexing (TPI). The message is generated from the DBUTIL ENABLE database name FOR INDEXING command if this database has already been enabled for indexing. ACTION This message is generated from the DBUTIL ENABLE command, and you can disregard it if you want the database to remain enabled for indexing.
Error Messages Utility Error Messages MESSAGE DATABASE CONTAINS INVALID LOGGING IDENTIFIER MEANING The log identifier in the database root file does not exist in the MPE logging identifier table. ACTION Use DBUTIL to set a valid log identifier into the database. MESSAGE DATABASE HAS BEEN MODIFIED SINCE LAST RESTORE MEANING The DBSTORE flag has not been reset. This can mean a backup database has not been restored, or that there have been modifications since the last restoration.
Error Messages Utility Error Messages MESSAGE DATABASE IS REMOTE MEANING You must be logged on to the same group and account containing the root file to use DBUTIL. ACTION Do a remote logon and run DBUTIL from your remote session. MESSAGE DATABASE LANGUAGE NOT SYSTEM SUPPORTED MEANING The language of the database is not currently configured on your system. ACTION Notify the database administrator.
Error Messages Utility Error Messages MESSAGE DATABASE REQUIRES CREATION MEANING The database creator must run the DBUTIL program in CREATE mode prior to executing DBUNLOAD, DBLOAD, or DBUTIL in ERASE mode. ACTION In session mode, correct the error or press return to terminate the program. MESSAGE DATA SET n IS MISSING MEANING The data set could have been purged, or was not restored. ACTION Contact your database administrator or system manager.
Error Messages Utility Error Messages MESSAGE DETACH FAILED FROM DBEnvionment name MEANING This message is returned if you are using ALLBASE/Turbo CONNECT (ATC). The message is generated from the DBUTIL PURGE command used with the DETACH option. The database is attached to the indicated ALLBASE/SQL database environment (DBEnvironment), but the DETACH option is unsuccessful due to ATC error nn. The PURGE command will continue processing after the warning is issued.
Error Messages Utility Error Messages MESSAGE EMBEDDED BLANK IN DBNAME2 MEANING One of the periods separating the user name from the group name or the group name from the account name was preceded or followed by a blank. ACTION Use EDITOR to change the MPE FILE command. MESSAGE ERROR READING ROOT FILE LABEL MEANING DBUTIL is unable to read the root file. ACTION Contact your HP systems engineer. MESSAGE ERROR READING ROOT FILE RECORD MEANING DBUTIL is unable to read a root file record.
Error Messages Utility Error Messages MESSAGE FCHECK FAILURE FCLOSE FAILURE FCONTROL FAILURE FENTRY FAILURE FGETINFO FAILURE MEANING These are exceptional errors indicating a hardware or software failure. ACTION Notify your database administrator of the failure. MESSAGE FFILEINFO INTRINSIC FAILED MEANING Internal error. ACTION Contact your database administrator. MESSAGE FGETINFO CANNOT VERIFY THAT FILE IS TYPE "LOG" MEANING Internal error. ACTION Contact your database administrator.
Error Messages Utility Error Messages MESSAGE FILE NAME MORE THAN SIX CHARACTERS MEANING The file name part of dbname2 is too long. ACTION Use EDITOR to change the FILE command. MESSAGE FOPEN FAILURE ON logfilename:ferrmsg MEANING You cannot open the log file. ACTION Examine ferrmsg to determine the cause. MESSAGE FREAD ERROR ON ASCII ACCESS FILE MEANING Exceptional errors indicate a hardware or software failure. ACTION Notify the database administrator of the error.
Error Messages Utility Error Messages MESSAGE INCOMPLETE DBNAME2 MEANING The file name or group name is followed by a period and the rest of the record is empty. Or the next character is a semicolon (;). ACTION Use EDITOR to change the FILE command. MESSAGE INCOMPLETE LOCAL PART MEANING The period following the local user name was missing, or the account name was missing, or a comma followed the account name and the group name was missing.
Error Messages Utility Error Messages MESSAGE INVALID CHARACTER IN PASSWORD MEANING Password does not consist of allowed characters. ACTION Check the password specified and reenter the command. MESSAGE INVALID COMMAND MEANING Command is unknown to the utility. ACTION Check spelling or see manual for legal commands.
Error Messages Utility Error Messages ACTION Reenter the command with the correct name. MESSAGE INVALID DB INTRINSIC CODE IN LOG RECORD CODE FIELD MEANING Internal error. ACTION Contact your database administrator. MESSAGE INVALID DELIMITER MEANING The command or a space is incorrectly positioned. ACTION Use HELP to check command syntax and reenter the command. MESSAGE INVALID FIRST LOG FILE NAME MEANING Internal error. ACTION Contact your database administrator.
Error Messages Utility Error Messages MESSAGE INVALID LOG DEVICE TYPE IN LOG RECORD MEANING Internal error. ACTION Contact your database administrator. MESSAGE INVALID LOG FILE DEVICE TYPE MEANING Internal error. ACTION Contact your database administrator. MESSAGE INVALID MAINTENANCE WORD MEANING An incorrect maintenance word was used. ACTION Check the maintenance word specified and reenter the command.
Error Messages Utility Error Messages MESSAGE INVALID (x) IN COLUMN y MEANING The x represents the invalid character found in column y. ACTION Use EDITOR to change the database-access file record which returns the error message. MESSAGE LANGUAGE MUST NOT BE LONGER THAN 16 CHARACTERS MEANING The language name is too long. ACTION Retype the correct language name. MESSAGE LANGUAGE NOT SUPPORTED MEANING The language is not supported on your system or is not a valid language name.
Error Messages Utility Error Messages MESSAGE LOG BUFFER OVERFLOW DURING GET NEXT LOGICAL LOG RECORD MEANING Internal error. ACTION Contact your database administrator. MESSAGE LOG FILE AND DATABASE IDs DO NOT MATCH MEANING Internal error. Database is not using the correct log file. ACTION Contact your database administrator. MESSAGE LOGFILE AND DATABASE LOGID'S DO NOT MATCH MEANING The restored database does not match the log file.
Error Messages Utility Error Messages MESSAGE LOGID MUST NOT BE LONGER THAN 8 CHARACTERS MEANING The logid name is too long. ACTION Retype the correct logid to set into the database. MESSAGE LOGID PASSWORD IS INCORRECT MEANING The password has been altered, or you are using the wrong password. ACTION Set the logid with the correct password into the database.
Error Messages Utility Error Messages MESSAGE MAXIMUM ERROR COUNT HAS BEEN EXCEEDED MEANING DBRECOV keeps track of all the errors that were encountered. If the number goes past a certain threshold (default is 0, but can be configured up to a maximum of 3000), DBRECOV will abort. ACTION Correct the problems causing the errors. If the user specifies an error count, this count could also be increased.
Error Messages Utility Error Messages MESSAGE MISSING REMOTE PART MEANING The remote-ID-sequence of the database-access file is missing. ACTION Use EDITOR to add the remote part. MESSAGE MISSING REMOTE PASWD MEANING HELLO was not followed by text, or was followed by a semicolon (;). ACTION Using the EDITOR, change the HELLO command. MESSAGE MISSING SEMI-COLON MEANING DEV= was not preceded by a semicolon (;) ACTION Use EDITOR to change the FILE command.
Error Messages Utility Error Messages MESSAGE MUSTRECOVER & ROLLBACK MUST BE DISABLED BEFORE DISABLING LOGGING MEANING Logging cannot be disabled if either MUSTRECOVER or roll-back recovery is active. ACTION Disable both MUSTRECOVER and roll-back recovery before disabling Logging. MESSAGE NEGATIVE CURRENT RECORD NUMBER IN BACKSPACE REQUEST MEANING Internal error. ACTION Contact your database administrator. MESSAGE NEGATIVE NUMBER OF BACKSPACES REQUESTED MEANING Internal error.
Error Messages Utility Error Messages MESSAGE NO INDEXING PRODUCT CONFIGURED; CANNOT ENABLE INDEXING MEANING This message is returned if you are using third-party indexing (TPI). The message is generated by the DBUTIL ENABLE database name FOR INDEXING command when the database is not yet configured for third-party indexing using the third-party utility. The database must be configured for indexing before it can be enabled for indexing.
Error Messages Utility Error Messages MESSAGE NOT A DATABASE ROOT FILE MEANING The specified file is not a database root file. ACTION Check the specified database name and try the command again. MESSAGE NOT A PRIVILEGED DATABASE ACCESS FILE MEANING The database-access file has not been activated. ACTION Check the command and reenter it correctly.
Error Messages Utility Error Messages MESSAGE PARSE OF FILE REFERENCE FAILED MEANING Internal error. ACTION Contact your database administrator. MESSAGE PASSWORD IS INCORRECT MEANING The logid password in the database is not the same as the password in the MPE table. ACTION Set the logid and correct password into the database. Or, use the MPE ALTLOG command to alter the password in the MPE table so it matches the one in the database.
Error Messages Utility Error Messages MESSAGE RELEASE OF ENTRY FROM RECOVERY TABLE FAILED MEANING Internal error. ACTION Contact your database administrator. MESSAGE REMOTE ACCOUNT racctname TOO LONG MEANING racctname is more than eight characters long. ACTION Use EDITOR to change the HELLO command. MESSAGE REMOTE ACCT PASSWORD TOO LONG MEANING rupasw is more than eight characters. ACTION Use EDITOR to change the HELLO command.
Error Messages Utility Error Messages MESSAGE ROLLBACK MUST BE DISABLED BEFORE AUTODEFER CAN BE ENABLED MEANING Deferred output option (AUTODEFER) cannot be used when the database has been enabled for ROLLBACK. ACTION Disable ROLLBACK and enable AUTODEFER using DBUTIL. (Refer to chapters 7 and 8 for more information on AUTODEFER.) MESSAGE ROLLBACK MUST BE DISABLED BEFORE LOGGING CAN BE DISABLED MEANING An attempt was made to disable logging while rollback was still enabled.
Error Messages Utility Error Messages MESSAGE UNABLE TO COPY GLOBAL AND TABLE INFORMATION TO RESTART FILE MEANING Internal error. ACTION Contact your database administrator. MESSAGE UNABLE TO GET NEXT LOGICAL LOG RECORD MEANING Internal error. ACTION Contact your database administrator. MESSAGE UNABLE TO GET PRIOR LOGICAL LOG RECORD MEANING Internal error. ACTION Contact your database administrator.
Error Messages Utility Error Messages MESSAGE WARNING: MUSTRECOVER IS ENABLED AND DATABASE NEEDS RECOVERY MEANING The database is enabled for MUSTRECOVER and the database needs to be recovered. ACTION Use DBRECOV to recover the database. MESSAGE WARNING: ROOT FILE ATC FLAG IS ON, BUT dbnameTC FILE IS MISSING MEANING This message is returned if you are using ALLBASE/Turbo CONNECT. The message is generated from the DBSTORE and the DBUTIL SHOW database name ALL commands.
Error Messages Utility Error Messages MESSAGE WARNING: ROOT FILE ATC FLAG IS OFF, BUT dbnameTC FILE EXISTS MEANING This message is returned if you are using ALLBASE/Turbo CONNECT (ATC). The message is generated from the DBSTORE and the DBUTIL SHOW database name ALL commands. The ATC flag in the root file indicates that the database is not attached to an ALLBASE/SQL database environment (DBEnvironment), but its corresponding ATC file exists.
Error Messages Utility Error Messages Utility Unconditional Error Messages MESSAGE AUTOMATIC MASTER IS FULL ON PATH #n MEANING DBLOAD is unable to load a detail entry because the automatic master set associated with path n of the detail set is full. ACTION Re-create the root file with a larger capacity for automatic master. Rerun the necessary utilities. MESSAGE ***BAD DATABASE*** MEANING This message is issued by DBSTORE, DBRESTOR, and DBUNLOAD.
Error Messages Utility Error Messages MESSAGE CAN’T CREATE NEW COPY OF FILE x (FS ERROR #) MEANING MPE intrinsic FOPEN failed while creating a temporary file. ACTION Check the file system error. Possible reasons: The specified device does not exist or has insufficient space. MESSAGE CAN'T GET SPECIFICATIONS VIA FGETINFO FOR THIS FILE x (FS error #) MEANING MPE intrinsic FGETINFO failed. DBUTIL cannot get information for the specified file. ACTION Check the file system error to determine cause.
Error Messages Utility Error Messages MESSAGE CHAIN IS FULL ON PATH #n MEANING DBLOAD is unable to load a detail entry because the chain count for path number n of detail set exceeds 231 −1 (or 2,147,483,647 entries). ACTION Delete some of the entries and reload or change the database design. MESSAGE ***COPY FAILED*** MEANING An error occurred while copying the file. DBUTIL has encountered a problem reading or writing the files. (It is possible the disk pack is bad.
Error Messages Utility Error Messages MESSAGE COULDN'T OPEN THE DATABASE MEANING No root file exists for the specified file. The file specified might not be part of the database. ACTION Check the file or database. Try the operation again with the correct file name. MESSAGE DATABASE STATE DOES NOT ALLOW MOVE TO BE DONE MEANING The database is in a state in which a move cannot be performed. ACTION Check the database. If the database has not been created, use the DBUTIL CREATE command to create it.
Error Messages Utility Error Messages MESSAGE DBEND FOUND TRANSACTION WHICH ALREADY ENDED MEANING Internal error. ACTION Contact your database administrator. MESSAGE ***DBSTORE FAILED - NO DATABASE STORED*** MEANING A file error or other message follows explaining the problem. ACTION Contact your database administrator. MESSAGE Dynamic capacity expansion in progress flag is on MEANING The data set is being expanded by DBPUT in another process.
Error Messages Utility Error Messages MESSAGE FILE EQUATE FOR DBSTORE DBRESTOR DBLOAD DBUNLOAD ONLY MAY USE DEV MEANING If you specify an input/output file with an MPE FILE command for any of these utility programs, only the file designators and DEV= parameters are allowed. ACTION Enter the MPE FILE command again and rerun program. MESSAGE FILE NOT ON TAPE MEANING Issued by DBRESTOR if the database to be restored is not on the tape. ACTION Check your MPE FILE command and/or the tape you mounted.
Error Messages Utility Error Messages MESSAGE INTERNAL ERROR--DATABASE SHOULD NOT BE OPEN AT THIS TIME MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--DBBEGIN FOUND PROCESS ALIVE, BUT TRAN STATE INACTIVE MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--EXPECTED DATABASE TO BE OPEN FOR THIS PROCESS MEANING Internal error. ACTION Contact your database administrator.
Error Messages Utility Error Messages MESSAGE INTERNAL ERROR--FWRITELABEL INTRINSIC FAILED MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--HEAP STAGING AREA OVERFLOWED MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--INVALID DATABASE TABLE ADDRESS MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--INVALID DBTAB'PROC'TAIL MEANING Internal error.
Error Messages Utility Error Messages MESSAGE INTERNAL ERROR--NO PROCESS TABLE ENTRY EXISTS MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--PROBLEM RETURNING HEAP MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--PROCESS NOT IN PROCESS TABLE MEANING Internal error. ACTION Contact your database administrator. MESSAGE INTERNAL ERROR--PROCESS TABLE IS FULL MEANING Internal error.
Error Messages Utility Error Messages MESSAGE MOVE OF FILE x NOT ALLOWED: FILE IS NOT CORRECT TYPE (FILE CODE #) MEANING The file specified is not a database file. ACTION Try the MOVE operation again with the correct file name. MESSAGE NO MANUAL ENTRY FOR DETAIL ON PATH #n MEANING DBLOAD is attempting to load detail data set entry n, which is the number of the detail data set path referencing the manual master in question. ACTION Add entry to manual master with application program or QUERY.
Error Messages Utility Error Messages MESSAGE ROLLBACK LOG FILE MUST BE IN THE SAME VOLUME SET AS THE DATABASE MEANING MPE transaction recovery requires that the MPE user log file must reside on the same volume set as the database. ACTION Build the MPE user log file in the same volume set as the database. NOTE: Because all files in a group are in the same volume set, the MPE command LISTGROUP indicates the volume set where the database resides.
Error Messages Utility Error Messages MESSAGE UNABLE TO OBTAIN FILE LABEL INFORMATION FOR FILE x MEANING MPE internal procedure failed. DBUTIL cannot obtain information for the specified file. ACTION Contact your database administrator. MESSAGE UNEXPECTED ROOT FILE STATE MEANING The MOVE process was unable to reset the database flag. The database could be in an inconsistent state. ACTION Contact your database administrator.
Error Messages Utility Error Messages -64 -66 -70 Appendix A MESSAGE SET NUMBERS ARE OUT OF SEQUENCE. TURBOIMAGE FAILED AT xxxxx) MEANING The next set number on the backup volume was not what DBLOAD expected. Status element 0 has the expected set number; status element 1 has the next set number on the backup volume. ACTION An error for a known value that was written to tape with FWRITE was found. The tape or tape drive could be defective. MESSAGE BLOCK NUMBERS ARE OUT OF SEQUENCE.
Error Messages Utility Error Messages -74 MESSAGE THE RECORD JUST READ IS UNRECOGNIZABLE TURBOIMAGE FAILED AT xxxxx) MEANING The record just read from the backup volume was not what DBLOAD expected. The record could be an EOF, EOT, etc. The status element 0 has one of the following codes for the record expected: 0– tape head 1– data file head 2– data file block 3– data file end 4– tape end 97 98 644 ACTION An error for a known value that was written to tape with FWRITE was found.
Error Messages Utility Error Messages 101 401 402 403 404 405 Appendix A MESSAGE DBRESTOR FAILURE IN DBRESTOR AT xxxxx) MEANING The DBRESTOR utility called the MPE RESTORE command, which encountered problems while restoring the database. A detailed error message should follow this message. ACTION Take appropriate action depending on the detail message. MESSAGE DBOPEN FAILURE AT xxxxx) MEANING A detailed error message can be retrieved by calling DBEXPLAIN.
Error Messages Utility Error Messages 406 407 408 409 410 411 646 MESSAGE DBUPDATE FAILURE AT xxxxx) MEANING A detailed error message can be retrieved by calling DBEXPLAIN. ACTION For more information, see "Library Procedure Error Messages" earlier in this appendix. MESSAGE DBPUT FAILURE AT xxxxx) MEANING A detailed error message can be retrieved by calling DBEXPLAIN. ACTION For more information, see "Library Procedure Error Messages" earlier in this appendix.
Error Messages Utility Error Messages 412 413 414 Appendix A MESSAGE DBBEGIN FAILURE AT xxxxx) MEANING A detailed error message can be retrieved by calling DBEXPLAIN. ACTION For more information, see "Library Procedure Error Messages" earlier in this appendix. MESSAGE DBEND FAILURE AT xxxxx) MEANING A detailed error message can be retrieved by calling DBEXPLAIN. ACTION For more information, see "Library Procedure Error Messages" earlier in this appendix.
Error Messages Utility Error Messages 648 Appendix A
Results of Multiple Access B Results of Multiple Access When opening a database with DBOPEN, TurboIMAGE/XL returns information in the status array describing the results of the procedure call. Figure B-1., “Actions Resulting from Multiple Access of Databases.” can be used to interpret these results when multiple processes are using the database. Each box in Figure B-1. is associated with a requested mode or TurboIMAGE/XL utility routine identified at the far left of the row in which the box appears.
Results of Multiple Access and column headings occurs. Figure B-1.
Database Design Considerations C Database Design Considerations • Keep one-of-a-kind information, such as unique identifiers, in master data sets. Keep duplicate information, such as records of events (sales, purchases, shipments), in detail data sets. • Define a search item in a detail data set if you want to retrieve all entries with a common value for that data item. • Use manual master data sets to prevent entry of invalid data in the detail search item linked to the master through a path.
Database Design Considerations activity on sorted chains to reading and updating (DBUPDATE). • Do all or most of your locking at one level (database, data set, or data entry). • If locking at the data entry level, do all or most of the locking using the same item in each data set. Otherwise, performance will be the same as if you were locking at the data set level. • Avoid holding locks around a terminal read. • Avoid beginning and ending logical transactions around a terminal read.
Database Design Considerations Figure C-1.
Database Design Considerations 654 Appendix C
Multiple Calls to DBLOCK D Multiple Calls to DBLOCK For the purpose of deadlock prevention, the system views any call to DBLOCK in which something is actually locked as a lock on a single resource, even though the call may have specified multiple lock descriptors. Any program which does not have the Multiple RIN (Resource Identification Number) capability (CAP=MR) can only have one resource locked at a time, and thus can only call DBLOCK once without an intervening call to DBUNLOCK.
Multiple Calls to DBLOCK Sort Sequence for Lock Descriptors If it is absolutely necessary to make multiple DBLOCK calls, the following information about how TurboIMAGE/XL performs locking may be useful.
Multiple Calls to DBLOCK Conditional Locks Conditional Locks During a DBLOCK, if TurboIMAGE/XL discovers a lock descriptor that is identical to one previously put into effect by the same user through the same access path, it ignores the latest lock descriptor. For example, the lock descriptor SALES:ACCOUNT = 89393899 is ignored if SALES:ACCOUNT = 89393899 was locked earlier on the same access path. However, it will not be ignored if a lock descriptor such as SALES: @ has been specified earlier.
Multiple Calls to DBLOCK Remote Databases Remote Databases Locking remote database entities is the same as locking database entities with the following exception. If the local system has a user-created process structure, and each process is locking a remote database independently, the programs must have Multiple RIN capability because they are in the same job/session. The only effect using MR capability has on the local system is that the rule prohibiting multiple DBLOCK calls is not enforced.
TurboIMAGE/XL Log Record Formats E TurboIMAGE/XL Log Record Formats This appendix shows the TurboIMAGE/XL log record formats for the DBBEGIN, DBCLOSE, DBDELETE, DBEND, DBMEMO, DBOPEN, DBPUT, DBUPDATE, DBXBEGIN, DBXEND, and DBXUNDO intrinsics. Note that the recovery flag will always be zero in the log file records. This flag is used during recovery if user recovery files are created. NOTE All TurboIMAGE/XL records are contained within MPE/iX "WRITELOG" records.
TurboIMAGE/XL Log Record Formats DBCLOSE HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) - HALFWORD(12) HALFWORD(13) HALFWORD(14) - MPE WRITELOG RECORD TURBOIMAGE/XL LOG RECORD LENGTH DBCLOSE LOG RECORD CODE ("CL") BASE LOGGING ID BIT 0 TO 5 = USER DBOPEN COUNT BIT 6 TO 15 = INDEX TO THE DBS FOR THE DBG USER PROCESS ABORT INDICATOR RESERVED FOR DBRECOV RUN TIME USE RESERVED FOR DBRECOV RUN TIME USE DBDELETE HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) - HALFWORD(12) HALFWORD(13) HALFWORD(
TurboIMAGE/XL Log Record Formats DBEND Mode 4 (MDBXEND) HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) HALFWORD(12) - HALFWORD(13-14) HALFWORD(15) HALFWORD(16) HALFWORD(17) HALFWORD(18) HALFWORD(19-20) HALFWORD(21) HALFWORD(22-23) - MPE WRITELOG RECORD TURBOIMAGE/XL LOG RECORD LENGTH MDBXEND LOG RECORD CODE ("TE") NOT USED SEQUENCE ID BITS 0-3 = RESERVED BITS 4-9 = SEQUENCE NUMBER BITS 10-15 = TOTAL NUMBER OF DBBEGIN/DBEND LOG RECORDS IN THE SEQUENCE TRANSACTION ID LENGTH OF USER BUFFER START OF U
TurboIMAGE/XL Log Record Formats HALFWORD(56) HALFWORD(60) HALFWORD(61) HALFWORD(63) HALFWORD(65) HALFWORD(66) HALFWORD(69) HALFWORD(72) HALFWORD(73) - USER PROGRAM ACCOUNT MODE FROM WHO INTRINSIC CAPABILITY FROM WHO INTRINSIC LOCAL ATTRIBUTE FROM WHO INTRINSIC LOGICAL DEVICE OF JOB/SESSION INPUT PREVIOUS ROLLBACK TIME STAMP (3 HALFWORDS) CURRENT ROLLBACK TIME STAMP (3 HALFWORDS) RESERVED FOR DBRECOV RUN TIME USE RESERVED FOR DBRECOV RUN TIME USE HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) - H
TurboIMAGE/XL Log Record Formats DBUPDATE HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) - HALFWORD(12) HALFWORD(13) HALFWORD(15) HALFWORD(16) HALFWORD(17) HALFWORD(19) HALFWORD(20) HALFWORD(21) HALFWORD(22) HALFWORD(23) HALFWORD(24) - MPE WRITELOG RECORD TURBOIMAGE/XL LOG RECORD LENGTH DBUPDATE LOG RECORD CODE ("UP") BASE LOGGING ID BIT 0 TO 5 = USER DBOPEN COUNT BIT 6 TO 15 = INDEX TO THE DBS FOR THE DBG RECOVERY FLAG ("NO"-FAILED,"OK"-RECOVERED) TRANSACTION NUMBER (1 WORD) DATA SET NUMBER DATA
TurboIMAGE/XL Log Record Formats DBXUNDO HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) - HALFWORD(12) HALFWORD(13) HALFWORD(15) HALFWORD(16) - MPE WRITELOG RECORD TURBOIMAGE/XL LOG RECORD LENGTH DBXEND LOG RECORD CODE ("XU") BASE LOGGING ID BIT 0 TO 5 = USER DBOPEN COUNT BIT 6 TO 10 = INDEX TO THE DBS FOR THE DBG RECOVERY FLAG ("NO"-FAILED,"OK"-RECOVERED) TRANSACTION NUMBER (1 WORD) LENGTH OF USER BUFFER START OF USER BUFFER QOPEN HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) HALFWORD(12-7
MPE/iX Log Record Formats F MPE/iX Log Record Formats This appendix lists the MPE/iX Log Record Formats for log files and user recovery files.
MPE/iX Log Record Formats CLOSELOG HALFWORD(0) HALFWORD(2) HALFWORD(3) HALFWORD(3) HALFWORD(4) HALFWORD(6) HALFWORD(7) HALFWORD(11) HALFWORD(12) HALFWORD(24) - RECORD NUMBER (1 WORD) CHECKSUM SUBSYSTEM IDENTIFIER (1ST BYTE) LOG RECORD CODE (2ND BYTE - 3) TIME DATE LOGGING IDENTIFIER LOG NUMBER USER NAME, GROUP, ACCOUNT PIN# - RECORD NUMBER (1 WORD) CHECKSUM 12 RECORD CONTAINS THE previous FILE IN THE SET 13 RECORD CONTAINS THE next FILE IN THE SET TIME DATE LOGID SEQUENCE NUMBER OF THE CURRENT FILE CRE
MPE/iX Log Record Formats NULL HALFWORD(0) HALFWORD(2) HALFWORD(3) - RECORD NUMBER (1 WORD) CHECKSUM RECORD CODE (BLANK BLANK) - RECORD NUMBER (1 WORD) CHECKSUM SUBSYSTEM IDENTIFIER (1ST BYTE) LOG RECORD CODE (2ND BYTE - 5) TIME DATE LOGGING IDENTIFIER TRAILER HALFWORD(0) HALFWORD(2) HALFWORD(3) HALFWORD(3) HALFWORD(4) HALFWORD(6) HALFWORD(7) Appendix F 667
MPE/iX Log Record Formats 668 Appendix F
Recovery and Logging Quick Reference Recovery Quick Reference G Recovery and Logging Quick Reference Recovery Quick Reference The following pages offer a very brief outline of the recovery options in TurboIMAGE/XL. For more information regarding dynamic roll-back recovery, Intrinsic Level Recovery (ILR), roll-forward recovery and roll-back recovery refer to chapter 7, "Logging and Recovery," and chapter 8, "Using the Database Utilities.
Recovery and Logging Quick Reference Recovery Quick Reference Intrinsic Level Recovery (ILR) • Should only be used to force flushing to disk after a call to DBPUT or DBDELETE. • Not required with TurboIMAGE/XL, because physical integrity is automatic and transparent to the user. The same physical integrity is available through Transaction Management (XM) on MPE/iX without enabling ILR. Using XM instead of ILR requires less overhead.
Recovery and Logging Quick Reference Recovery Quick Reference • When the roll-forward process finishes, the RESTART option in user logging can be used or a new logging cycle can be started. Remember to purge the log files before starting the new logging cycle. • May not recover all transactions. If using DBEND mode 2, transactions will be flushed to the log file at DBEND time; therefore, transactions will not be lost. • You should consider how often to store the database.
Recovery and Logging Quick Reference Recovery Quick Reference • Should not be disabled if roll-back recovery must be used later because it will reset the logging time stamp, therefore recovery cannot be performed. The database will be considered correct and cannot be rolled back. • Transactions are not lost during a start recovery operation because they are not held in the memory buffer. (A start recovery operation must be performed after a system failure.
Recovery and Logging Quick Reference Logging Device Quick Reference Logging Device Quick Reference The lists below outline both the benefits and disadvantages of logging to disk and logging to tape. Refer to chapter 7, "Logging and Recovery" for more information on user logging. You must determine which type of logging device to use based on equipment, operations staff, number of users and size of the database, and other considerations listed here.
Recovery and Logging Quick Reference Sample Job Streams • Must do a start recovery operation after a soft system crash to write a crash log record to the log file. • Has overhead comparable to logging to tape. NOTE In the event of a system failure and subsequent start recovery operation and when using private volumes, logging will not resume until these private volumes have been mounted. Enter the MPE VMOUNT command into the SYSSTART file to resume logging.
Recovery and Logging Quick Reference Sample Job Streams Figure G-1. Sample Job Stream for Starting Logging Cycle :JOB MGR.DATAMGT :GETLOG ORDERLOG;LOG=ORDER001,DISC Acquire log identifier. :BUILD ORDER001;DISC=200000,20,7;CODE=LOG Build new log file. :RUN DBUTIL.PUB.SYS SET ORDERS LOGID=ORDERLOG Response to logid password prompt. ENABLE ORDERS FOR LOGGING DISABLE ORDERS FOR ACCESS ENABLE ORDERS FOR RECOVERY ENABLE ORDERS FOR MUSTRECOVER EXIT :RUN DBSTORE.PUB.
Recovery and Logging Quick Reference Sample Job Streams Figure G-2. Sample Job Stream for Roll-Forward Recovery :JOB MGR.DATAMGT :RUN DBUTIL.PUB.SYS DISABLE ORDERS FOR ACCESS ENABLE ORDERS FOR RECOVERY EXIT :RUN DBSTORE.PUB.SYS ORDERS :RUN DBUTIL.PUB.SYS PURGE ORDERS EXIT :RUN DBRESTOR.PUB.SYS ORDERS :RUN DBUTIL.PUB.SYS DISABLE ORDERS FOR ACCESS ENABLE ORDERS FOR RECOVERY ENABLE ORDERS FOR MUSTRECOVER EXIT :RUN DBRECOV.PUB.SYS RECOVER ORDERS FILE PART1,SYS/P1D1.MKTG,0,3 FILE PART2,SYS/P1D1.
Recovery and Logging Quick Reference Sample Job Streams Figure G-3. Sample Job Stream for Roll-Back Recovery :JOB MGR.DATAMGT :RUN DBUTIL.PUB.SYS DISABLE ORDERS FOR ACCESS ENABLE ORDERS FOR RECOVERY EXIT Set the flags in the database root file. A DBSTORE of the database at this time is recommended. :RUN DBRECOV.PUB.SYS CONTROL NOSTORE DBSTORE flag is set. ROLLBACK ORDERS FILE PART1,SYS/P1D1.MKTG,0,3 FILE PART2,SYS/P1D1.MKTG,0,3 FILE PART3,SYS/P1D1.MKTG,0,3 RUN EXIT :LOG ORDERLOG,RESTART :RUN DBUTIL.PUB.
Recovery and Logging Quick Reference Sample Job Streams Figure G-4. Sample Job Stream for Starting Logging Cycle :JOB MGR.DATAMGT :GETLOG ORDERLOG;LOG=ORDER001,DISC;AUTO optional. Acquire log identifier. :BUILD ORDER001;DISC=200000,20,7;CODE=LOG Build new log file. :RUN DBUTIL.PUB.SYS SET ORDERS LOGID=ORDERLOG Response to logid password prompt.
Recovery and Logging Quick Reference Sample Job Streams Figure G-5. Sample Job Stream for Backup with Database Open for Access :JOB MGR.DATAMGT :FILE ORDERBK2;DEV=TAPE :STORE ORDERS;*ORDERBK2;ONLINE=START access. :EOJ cycle after ORDER999. Mount tape. Store database while it is open for Assume that you will start a new log The next example in Figure G-6. uses roll-forward recovery and TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option).
Recovery and Logging Quick Reference Sample Job Streams Storing and purging the damaged database prior to restoring it is optional. After recovery has completed, logging can either be restarted (with the current log file) or the log file can be purged and a new log file built. The next example in Figure G-7. uses roll-back recovery. A backup of the database using DBSTORE or TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option) can be done at this time; however, this is optional.
TurboIMAGE/XL versus TurboIMAGE/V Overview H TurboIMAGE/XL versus TurboIMAGE/V TurboIMAGE/XL is available on the HP 3000 Series 900. This database management system is very similar to TurboIMAGE/V. However, some differences exist due to the architecture of the 900 series and the MPE/iX features of which TurboIMAGE/XL takes advantage.
TurboIMAGE/XL versus TurboIMAGE/V Overview retrievals, and sorted sequential searches on any database that is enabled for third-party indexing. • A logical transaction bracketed by DBXBEGIN and DBXEND can be dynamically rolled back. This dynamic transaction can be of 1 to 15 databases. • A data set can be a jumbo set exceeding 4 gigabytes. • B-tree indices on key items of master data sets allow generic and range searches on key items of master sets as well as corresponding detail data set search items.
TurboIMAGE/XL versus TurboIMAGE/V Overview For more detailed migration information, refer to the Migration Process Guide. Table H-1. TurboIMAGE/XL Differences Area Affected Changes/Additions Data Set Size – The maximum data set size is 4 gigabytes unless it is a jumbo data set. DBEXPLAIN – Information for DBEXPLAIN is stored in the Database User Local Control Block (DBU). – Calls to DBEXPLAIN must be made immediately after receiving an error status.
TurboIMAGE/XL versus TurboIMAGE/V Overview Table H-1. TurboIMAGE/XL Differences Area Affected Changes/Additions – If logging to disk, the user log file and the database must be in the same volume set. If logging to tape, the database must be on the system volume set. – Mapped files are used for control blocks. – A control block called the Database User Local Index (DBUX), which is unique to a process, has been added.
TurboIMAGE/XL versus TurboIMAGE/V Intrinsic Level Recovery Intrinsic Level Recovery Intrinsic Level Recovery (ILR) is not required to protect the structural integrity of the database, because in default recovery mode TurboIMAGE/XL takes advantage of an internal MPE/iX file system service, called Transaction Management (XM), to provide intrinsic level backup and recovery.
TurboIMAGE/XL versus TurboIMAGE/V Intrinsic Level Recovery • On TurboIMAGE/XL, only completed DBPUTs and DBDELETEs are recovered by ILR if the database was enabled for ILR. If these intrinsics are interrupted by a system failure or other abnormal termination, they are not recovered. On TurboIMAGE/V, if the database is enabled for ILR, the last DBPUT or DBDELETE, which was interrupted by a system failure or other abnormal termination, will be completed.
TurboIMAGE/XL versus TurboIMAGE/V Control Blocks Control Blocks Run-time control blocks are created differently on MPE/iX. A new control block called the Database User Local Index (DBUX), which is unique to each process, has been added. Also, four new global tables to monitor system-wide database activity are added.
TurboIMAGE/XL versus TurboIMAGE/V Control Blocks stored in an unnamed/new mapped file. One DBUX is created per process. The database ID number serves as an index into the DBUX and points to the virtual addresses of all current DBU/DBRs belonging to that process. 127 entries are allowed, meaning that each user (process) is allowed 127 DBOPENs (63 per database). Refer to the discussion of DBOPEN in Chapter 5 for additional information.
TurboIMAGE/XL versus TurboIMAGE/V Status Area Status Area All addresses on MPE/iX are 32 bits. This has necessitated a change in some of the information returned in the status area by TurboIMAGE/XL library procedures. Major Differences Because TurboIMAGE/XL uses MPE/iX mapped files, DBOPEN calls HPFOPEN to open these mapped files. If an error occurs during this process, the condition code −9, formerly used to indicate an MPE/iX GETDSEG failure, is now used to indicate an MPE/iX HPFOPEN failure.
TurboIMAGE/XL versus TurboIMAGE/V Status Area • DBEXPLAIN cannot find complete information in the status area for its explanation. To solve this problem, TurboIMAGE/XL places the missing information in the DBU, which DBEXPLAIN now references. However, the application must call DBEXPLAIN immediately after the status information is received.
TurboIMAGE/XL versus TurboIMAGE/V Moving from MPE/iX to MPE V Moving from MPE/iX to MPE V If you need to move a TurboIMAGE database from MPE/iX to MPE V, you need to perform the following tasks: 1. If the TurboIMAGE/XL database you stored has taken advantage of dynamic roll-back recovery, check for the presence of a dbname00 file. If the dbname00 file exists, the database needs to be recovered. Open the database and close it again. The recovery occurs automatically with the call to DBOPEN. 2.
TurboIMAGE/XL versus TurboIMAGE/V Moving from MPE/iX to MPE V Buffer Specifications For databases that will be moved to MPE V, the DBUTIL >>SET command can be used to specify the number of input/output buffers to be allocated by TurboIMAGE/V in the Database Buffer Area Control Block (DBB) depending on the number of users concurrently accessing the database.
TurboIMAGE/XL versus TurboIMAGE/V Moving from MPE/iX to MPE V particular number of users, the default number of buffers is used. These are the default settings assigned by TurboIMAGE on MPE V: b(1/2) b+1(3/4) b+2(5/6) b+3(7/8) b+4( 9/10) b+5(11/12) b+6(13/14) b+7(15/16) b+8(17/18) b+9(19/120) The value of b is equal to the largest number of search items in any detail data set in the database plus 3, or it is equal to 8, whichever is larger.
TurboIMAGE/XL versus TurboIMAGE/V Moving from MPE/iX to MPE V Number of buffers must not decrease for increased users as below: specifications. Here the buffers are increased for the first 30 users. However, the previous buffer setting remains the same for the other users.
Index A abort and recovery, 314 conditions, 540, 597 ABORTS parameter, of DBRECOV, 392, 395 access class password, modifying, 448 disable, 428 enable, 432 granting, 649 option, 428, 432 ACCESS option, of DBUTIL, 428, 432 ACTIVATE command, of DBUTIL, 421 activate DBA file, 421 ADDINDEX command of DBUTIL, 423 syntax, 506 address primary, 480 algorithms, primary address calculation, 493 ALL option, of DBUTIL, 453 ALTLOG command, of MPE/iX, 327 argument simple, 502 structured, 502, 513 at-sign in DBA file, 470
Index creating a database, 309 creator, database, 379 critical item update, 448 D data chain, 478 prefetching, 428, 432 data set creating, 424 expansion, 481, 493 initializing, 424 naming conventions, 424 purging, 441 reinitializing, 435 size, 683 space allocation, 495 database administrator, access to log file, 404 attached to a DBEnvironment, 441 backup copy, 332 backup copy, flags, 330 backup using TurboSTORE/iX 7X24, 333 consistency, 315 creating, 309 creator, 379 detaching from a DBEnvironment, 441 ex
Index DBUNLOAD utility, 412 and broken chains, 414 DBUPDATE with B-Tree index, 518 DBUTIL with B-Tree index, 506 DBUTIL utility, 419 ACCESS option, 428, 432 AUTODEFER option, 428, 432 DUMPING option, 428, 432 ILR option, 428, 432 INDEXING option, 428, 432 LOGGING option, 428, 432 MUSTRECOVER option, 428, 432 PREFETCH option, 428, 432 RECOVERY option, 428, 432 ROLLBACK option, 428, 432 DBUTIL utility commands ACTIVATE, 421 ADDINDEX, 423 CREATE, 424 DEACTIVATE, 426 DETACH, 427 DISABLE, 428 DROPINDEX, 431 ENA
Index ILR, 432 indexing, 432 logging, 432 MUSTRECOVER, 432 PREFETCH, 432 recovery, 432 ROLLBACK, 432 ENABLE command, of DBUTIL, 432 entries migrating secondaries, 494 primary, 480 secondary, 480 entryname, 487 entrynumber, 487 EOF parameter, of DBRECOV, 392, 395 ERASE command, of DBUTIL, 435 erasing the database, and logging, 435 error messages, 384, 521 errors calling, 544 library procedures, 539 Schema Processor, 522 ERRORS parameter, of DBRECOV, 392, 395 EXIT command of DBRECOV, 396 of DBUTIL, 437 expan
Index file system and memory management error messages, 541 LISTLOG command, of MPE/iX, 327 lock area, 496 lock descriptors sort sequence, 656 locking accessor entries, 496 and dynamic transactions, 319 and transactions, 318 descriptor entries, 496 requirements, 317 set entries, 496 locking/unlocking and logging, 314 conditional, 657 internals, 496 performance, 652 remote databases, 658 LOCKS option, of DBUTIL, 453 locks, showing, 459 LOG command, of MPE/iX, 339 log file building, 326 size, determining, 37
Index MPE/iX commands ALTLOG, 327 BUILD, 326 CHANGELOG, 341 GETLOG, 327 LISTLOG, 327 LOG, 339 RELLOG, 327 SHOWLOGSTATUS, 326 MR capability, 655 multiple access, 649 database transactions, 315, 347 RIN capability, 655 semaphores, 485 MUSTRECOVER option, of DBUTIL, 428, 432 disable, 428 enable, 432 N names data set, 424 Network Services (NS/3000), 465 NOABORTS parameter, of DBRECOV, 395 NOMDBX parameter, of DBRECOV, 395 NOSTAMP parameter, of DBRECOV, 395 NOSTATS parameter, of DBRECOV, 392, 395 NOSTORE parame
Index overview, 312 performing DBRECOV STOP-RESTART, 369 performing roll-back recovery, 356 performing roll-forward recovery, 350 post-recovery options, 365 PRINT command, of DBRECOV, 361 quick reference, 669 record numbers, 395 RECOVER command, of DBRECOV, 361 roll-back time stamp, 355 RUN command, of DBRECOV, 357, 362 statistics, 395, 404 statistics files, 363 stream file, 353 tables, 363 transferring log files, 366 RECOVERY option, of DBUTIL, 428, 432 recovery options, 312 default mode, 312 dynamic roll
Index SHOWLOGSTATUS command, of MPE/iX, 326 simple argument, 502 sort items design considerations, 651 updating values, 451 sort sequence for lock descriptors, 656 sorted chains, 651 space allocation for detail data sets, 495 master data sets, 494 special capability multiple RIN, 655 STAMP parameter, of DBRECOV, 392, 395 start recovery operation, 353, 358 STATS parameter, of DBRECOV, 395 status area information, 539 information and multiple access, 649 MPE V versus MPE/iX, 689 STOPTIME parameter, of DBRECO
Index W wildcard character, 502 WRITELOG records, MPE/iX, 659 Index 703
