HP 3000 MPE/iX Computer Systems TurboIMAGE/XL Database Management System Reference Manual ABCDE HP Part No. 30391-90001 Printed in U.S.A.
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 tness 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.
Printing History The following table lists the printings of this document, together with the respective release dates for each edition. The software version indicates the version of the software product at the time this document was issued. Many product releases do not require changes to the document. Therefore, do not expect a one-to-one correspondence between product releases and document editions.
iv
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 nd 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.07.04 or later includes the following enhancements: Jumbo Data Sets By using the JUMBO option of $CONTROL, data sets can be greater than 4 GBytes. B-Tree Indices Provides the capability for wildcard and range searches. A new chapter 11 was added on this topic. Dynamic Roll-Back of Multiple Database Transactions This enhancement is an extension of the dynamic roll-back (DBX) feature to include multiple databases.
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 de nitions of terms used to describe the module precede the reference speci cations. 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 (30367-90007) MPE/iX Intrinsics Reference Manual (32650-90028) MPE/iX Commands Reference Manual (32650-90003) Native Language Programmer's Guide (32650-90022) NLS/3000 Reference Manual (32214-90001) Query/V Reference Manual (30000-90042) NS3000/XL User/Programmer Reference Manual (36920-90001) TurboIMAGE/XL Database Management System DBChange Plus User's Guide (36386-90001) TurboIMAGE/XL Database Management Sys
Conventions UPPERCASE In a syntax statement, commands and keywords are shown in uppercase characters. The characters must be entered in the order shown; however, you can enter the characters in either uppercase or lowercase.
Conventions (continued) [ ... ] In a syntax statement, horizontal ellipses enclosed in brackets indicate that you can repeatedly select the element(s) that appear within the immediately preceding pair of brackets or braces. In the example below, you can select parameter zero or more times. Each instance of parameter must be preceded by a comma: [,parameter][...
Contents 1. Introduction General Overview . . . . . . . . . . Data Security . . . . . . . . . . Rapid Data Retrieval and Formatting Program Development . . . . . . . Program Maintenance . . . . . . . Program File Independence . . . . File Consolidation . . . . . . . . . Special Information Needs . . . . . Database Personnel . . . . . . . . . How to Use TurboIMAGE/XL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creator-Only Access . . . . . . . . . . . . . Sample Read and Write Class Lists . . . . . . . Null and Absent Lists . . . . . . . . . . . . . . Database Access Modes and Data Set Write Lists . . . Granting a User Class Access . . . . . . . . . . . . User Classes and Locking . . . . . . . . . . . . . Protection in Relation to Library Procedures . . . . . Protection Provided by the TurboIMAGE/XL Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Entering Data in the Database . . . . . . . . . . Sequence for Adding Entries . . . . . . . . . . Coordinating Additions to a Database . . . . . . Access Mode and User Class Number . . . . . . Key and Search Items . . . . . . . . . . . . . Reading the Data . . . . . . . . . . . . . . . . Current Path . . . . . . . . . . . . . . . . . Reading Methods . . . . . . . . . . . . . . . Directed Access . . . . . . . . . . . . . . . Serial Access . . . . . . . . . . . . . . . . Calculated Access . . . . . . . . . .
Checking Subsystem Flag . . . Closing the Database or a Data Set Checking the Status of a Procedure Interpreting Errors . . . . . . . Abnormal Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37 4-37 4-38 4-39 4-39 5. TurboIMAGE/XL Library Procedures Using TurboIMAGE/XL Intrinsics . Intrinsic Numbers . . . . . . . .
C . . . . . . COBOL II . . FORTRAN 77 Pascal . . . . RPG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20 6-26 6-47 6-53 6-59 7. Logging and Recovery Database Utilities Used in Logging and Recovery . . . . Recovery Options . . . . . . . . . . . . . . . . . . . Logging and Recovery Considerations . . . . . . . . .
MPE/iX Cleanup Mode and Roll-Back Recovery . . . . . . . . DBRECOV Commands Used with Roll-Forward and Roll-Back Recovery CONTROL Command . . . . . . . . . . . . . . . . . . . . . FILE Command . . . . . . . . . . . . . . . . . . . . . . . PRINT Command . . . . . . . . . . . . . . . . . . . . . . RECOVER Command . . . . . . . . . . . . . . . . . . . . . ROLLBACK Command . . . . . . . . . . . . . . . . . . . . RUN Command . . . . . . . . . . . . . . . . . . . . . . . Recovery Tables . . . . . . . . . . . . .
>>ERASE . . . . . >>EXIT . . . . . >>HELP . . . . . >>MOVE . . . . . >>PURGE . . . . >>REBUILDINDEX >>REDO . . . . . >>RELEASE . . . >>SECURE . . . . >>SET . . . . . . >>SHOW . . . . . >>VERIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bu er Management . . . . . . Locking Internals . . . . . . . Accessor Entries . . . . . . Set Entries . . . . . . . . . Descriptor Entries . . . . . . MPE/iX Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11. B-Tree Indices Overview of B-Tree Indices . . . . . . . . . Terminology . . . . . . . . . . . . . . Key Points . . . . . . . . . . . . . . . External Commands and Utilities A ected . . Root File . . . . . . . . . . . . . . . DBSCHEMA . . . . . . . . . . . . . .
A. Error Messages Schema Processor Error Messages . . . . . . . . . . . . Schema Processor File Errors . . . . . . . . . . . . . Schema Processor Command Errors . . . . . . . . . . Schema Syntax Errors . . . . . . . . . . . . . . . . Library Procedure Error Messages . . . . . . . . . . . Abort Conditions . . . . . . . . . . . . . . . . . . I and J Files . . . . . . . . . . . . . . . . . . . . Library Procedure File System and Memory Management Library Procedure Calling Errors . . . . . . . . . . .
H. TurboIMAGE/XL versus TurboIMAGE/V Overview . . . . . . . . . . . . . . Moving to TurboIMAGE/XL . . . . . Intrinsic Level Recovery . . . . . . . . Control Blocks . . . . . . . . . . . . Status Area . . . . . . . . . . . . . Moving from MPE/iX to MPE V . . . . Bu er Speci cations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figures 1-1. 2-1. 2-2. 2-3. 2-4. 2-5. 2-6. 2-7. 2-8. 3-1. 3-2. 3-3. 3-4. 3-5. 4-1. 4-2. 4-3. 5-1. 5-2. 5-3. 6-1. 7-1. 7-2. 7-3. 8-1. 9-1. 9-2. 9-3. 9-4. 9-5. 9-6. 10-1. 10-2. 10-3. 10-4. 10-5. B-1. C-1. G-1. G-2. G-3. G-4. How to Use TurboIMAGE/XL . . . . . . . . . . . . . . CUSTOMER Data Set Sample . . . . . . . . . . . . . . Master and Detail Data Set Relationships . . . . . . . . . Master and Detail Data Sets Example . . . . . . . . . . . Adding Entries to a Sorted Chain . . . . . . . . . . . . .
G-5. Sample Job Stream for Backup with Database Open for Access . . . . . . G-6. Sample Job Stream for Roll-Forward Recovery . . . . . . . . . . . . . G-7. Sample Job Stream for Roll-Back Recovery . . . . . . . . . . . . . . .
Tables 2-1. 2-2. 2-3. 3-1. 3-2. 3-3. 3-4. 3-5. 3-6. 3-7. 4-1. 4-2. 4-3. 4-4. 5-1. 5-2. 5-3. 5-4. 5-5. 5-6. 5-7. 5-8. 5-9. 5-10. 5-11. 5-12. 5-13. 5-14. 5-15. 5-16. 5-17. 5-18. 5-19. 5-20. 5-21. 5-22. 5-23. 5-24. 5-25. 5-26. 7-1. 8-1. 11-1. Sample Read/Write Class Lists . . . . . . . . . . . . . Enabling a User Class to Perform a Task . . . . . . . . . Sample Read and Write Class Lists . . . . . . . . . . . Additional Conventions . . . . . . . . . . . . . . . . Type Designators . . . . . . . . . . . . . . .
G-1. G-2. H-1. H-2. H-3. H-4. Roll-Forward Flag Settings . . . . . . . . . Roll-Back Flag Settings . . . . . . . . . . TurboIMAGE/XL Di erences . . . . . . . DBINFO Mode 402 Changes . . . . . . . . Condition Code 09 Status Array . . . . . . Status Area Changes for MPE/iX Applications Contents-14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 Introduction General Overview TurboIMAGE/XL is a set of programs and procedures that you can use to de ne, create, access, and maintain a database. A database is a collection of logically-related les containing both data and structural information. Pointers within the database allow you to gain access to related data and to index data across les. The primary bene t of the TurboIMAGE/XL database management system is time savings.
Rapid Data Retrieval and Formatting Conventional le organization frequently requires using multiple le 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.
Program File Independence Conventional le structures tend to be rigid and in exible. The nature of conventional le management systems requires that the logic of application programs be intricately interwoven with le design. When it is necessary to alter the structure of a le, a program must be written to change the le and programs that access the le must be changed to re ect the le change.
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. The database administrator is also responsible for system backup and recovery.
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.
Figure 1-1.
2 Database Structure and Protection This chapter describes the structure of a TurboIMAGE/XL database. The discussion de nes 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 de ne a database. Database Elements A database is a named collection of related data. The formal description of this data is called a schema.
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 199 data sets.
Figure 2-1.
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 identi ed by triangles and detail data sets by trapezoids. Figure 2-2.
Figure 2-3.
Automatic and Manual Masters A master data set is de ned as either automatic or manual. The characteristics of both are described below: Manual Master Automatic Master Can be standalone (not related to any detail data Must serve as an index to one or more detail data sets. set) or can serve as an index for one or more detail data sets. Must contain a key item and can contain other data items. Must contain only one data item, the key item. The user must explicitly add or delete all entries.
Automatic masters serve as indexes to detail data sets and save time when the search item values are unpredictable or so numerous that manual addition and deletion of master entries is undesirable. Whenever a single data item is su cient for a master data set, the database designer must decide between the control of data entry available through manual masters and the program simplicity o ered by automatic masters.
to the rst and last entries of the chain whose search item value matches the master data set entry's key item value and a count of the number of entries in the chain. This is called a chain head. The format of chain heads is given in chapter 10. For example, the DATE-MASTER data entries each contain two sets of pointers, one for PURCH-DATE chains and one for DELIV-DATE chains. TurboIMAGE/XL automatically maintain the chain heads.
If you depend on extended sort elds to sort a chain, do not call DBUPDATE to modify any of the values in the extended sort elds because the chain will not be automatically resorted according to the new extended sort data values. Instead, call DBDELETE and DBPUT to re-enter the records with modi ed values. DBUPDATE only recognizes extended sort items when the actual search or sort item is changed. Chapter 5 describes DBUPDATE, DBDELETE, and DBPUT in detail.
Figure 2-4.
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 de ned 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.
Figure 2-6.
Database Files Database elements are stored in privileged MPE/iX disk les. In addition to the root le which contains the database de nition, other les that contain data are called data sets. Root File The root le serves as a common point of entry to, and a source of information about, the database. The root le is a single-extent MPE/iX disk le; that is, the entire le occupies contiguous sectors on the disk.
Blocks The media records in a data le physically reside together in a group called a block. Each block corresponds to one MPE le 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 le. Chapter 3 contains more information about block size and blocking factors. The format of blocks is given in chapter 10.
Protecting the Database TurboIMAGE/XL prevents unauthorized persons from gaining access to the database. It provides external protection through the MPE/iX privileged le, account, and group constructs and, in addition, provides the database designer and database manager with methods to re ne security within the database. Privileged File Protection All TurboIMAGE/XL database les are privileged les. (Refer to the MPE/iX Intrinsics Reference Manual for a description of the MPE/iX privileged le capability.
you may only need to de ne a few passwords for your database. You may want to relate the user class number to the user's job position; for example, the ORDERS database is de ned with these user classes and passwords: User Class 11 12 13 14 18 Password CREDIT; BUYER; SHIP-REC; CLERK; DO-ALL; When you initiate access to the database, you must supply a password to establish the user class.
Note Database access modes 2, 5, 6, 7, and 8 do not allow write access. Programs that open the database in these modes must pass data set and data item level security. For additional information, refer to chapter 4 and to \Database Access Modes and Data Set Write Lists" later in this chapter. Update Access. A user class that has update access can change the values of a particular data item in an existing data entry. However, the user class cannot add or delete entries from the data set.
Table 2-1. Sample Read/Write Class Lists CUSTOMER (data set ) CREDIT-RATING (data item ) Read Class List Write Class List 11,14 11,18 14 14 Because a write class list of 14 implies that user class 14 is in the read class list, the CREDIT-RATING read class list is redundant. However, it could be included as a reminder in the schema of the total capability granted to user class 14. Table 2-2 later in this chapter contains examples of the e ects of read and write class lists.
Granting a User Class Access Figure 2-7 and Table 2-2 illustrate the use of read and write class lists from two di erent perspectives. Figure 2-7 shows what capability user class 11 has if it appears in the lists as shown. The same rules apply to any user class. The access mode must be as indicated. Figure 2-7.
Table 2-2. Enabling a User Class to Perform a Task Task Read Data Item Data Set Database Access Mode Security Rules 1, 3, or 4 User class must be in data set write list, or User class must be in data set read list and pass data item security. 2, 5, 6, 7, or 8 Update Data Item 1, 3, or 4 Add or Delete Data Entries 1, 3, 4 User class must be in read or write list. User class must be in data set User class must be in read or read or write list and pass data write list. item security.
Specify the user class number in the data item write class list. This grants the user class the ability to update or change the data item value. Master data set key item values cannot be updated. Detail data set search or sort item values can be updated in database access mode 1, 3, or 4 if permitted by the critical item update (CIUPDATE) option settings for the database and the current process. Because the user class is implied to be in the read class list, the user class can also read the item.
Figure 2-8.
Table 2-3 contains more illustrations of the e ects 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 e ects 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.
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 les which are not directly accessible to database users.
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 le. Figure 3-1 illustrates the steps in de ning the database. Figure 3-1. Database Definition Process Database Description Language The database description, called a schema, can exist in the MPE/iX system as an ASCII le.
Language Conventions The conventions used in describing the database language are the same as those described on the conventions page at the beginning of this manual. In addition, these conventions apply. Table 3-1. Additional Conventions Convention Punctuation Comments Description All punctuation appearing in format statements must appear exactly as shown. Comments take this form: <> Comments can contain any characters and can appear anywhere in the schema except embedded in another comment.
Password Part The password part de nes 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 password is an integer between 1 and 63, inclusive. User class numbers must be unique within the password part.
Item Part The item part de nes 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 de ned in the set part de nition. 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. It must be unique within the item part.
Data Item Length Each data item value is allotted a storage location whose length is equal to the product of the item's sub-item length and its sub-item count. The unit of measure for the length 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.
TurboIMAGE/XL and Program Language Data Types The type designator, sub-item count, and sub-item length you specify for a data item de nes its length. TurboIMAGE/XL does not perform any conversions of data or examine the item to check its validity as it is being added to the database. The only data item values that TurboIMAGE/XL checks are those speci ed as part of a lock descriptor in calls to the DBLOCK procedure. Refer to the discussion on DBLOCK in chapter 5.
Table 3-3. TurboIMAGE/XL Data Types and Programming Languages (continued) Data BBASIC Type C COBOL II FORTRAN 77 Pascal P4 char[2] Computational-3 S9(3) Packed array [1..2] of charz P8 char[4] Computational-3 S9(7) Packed array [1..
Data Items of Type P The bits used to represent the sign of a packed decimal value can vary depending on whether the value is entered using QUERY/3000, a COBOL II program, or an RPG program.
Data Item Identifiers When using the TurboIMAGE/XL procedures described in the chapter 5, you can reference a data item by name or number. The data item number is determined by the item's position in the item part of the schema. The rst item de ned is item 1, the second is item 2, and so forth.
Set Part The set part of the schema de nes 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 de nes 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.
detail data sets. Refer to chapter 2 for more information about paths. A path count must be speci ed 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. A manual master de ned in this way is not linked to any detail data set. An automatic master has one item that must have a path count greater than zero. maximum capacity is the maximum number of entries the data set can contain: that is, the data set's capacity.
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. Examples NAME: ENTRY: SUP-MASTER,MANUAL /INDEXED (13/12,18),DISC1; SUPPLIER(1), STREET-ADD, CITY, STATE, ZIP; CAPACITY: 2001,501,20%; Description The example also shows the data set SUP-MASTER which will reside on Disc1.
For existing databases, use DBChange Plus or a third-party utility to specify the expansion parameters. Note Detail Data Sets The set part syntax and parameters for detail data sets are provided below. The maximum capacity, the initial capacity, and the incremental amount are new parameters for the detail data set CAPACITY de nition.
master set name is the name of a previously de ned master data set. When a master set name follows an item name, the data item is a search item linking the detail set to the named master. Up to 16 search items can be de ned for a 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.
leading to severe disk fragmentation. If it is very high, DBPUT may take a long time to complete which could impact other database users. The number of entries de ned, or the entries calculated from the percent, cannot exceed the maximum entry count minus the initial allocation. The increment is adjusted to represent an even multiple of the blocking factor. The increment is an optional parameter.
Master Key and Detail Search Items The master key items and detail search items (also called critical items) that de ne a path between two data sets must have identical type designators and simple sub-item lengths when they are de ned in the item part. The sub-item lengths must be simple because the key and search items cannot be compound items.
Schema Processor Operation The Schema Processor is a program that accepts a text le containing the schema as input, scans the schema and if no errors are detected, optionally produces a root le. The Schema Processor prints a heading, an optional list of the schema, and summary information on a list le . The Schema Processor executes as either an MPE/iX job or session. For further information about sessions and jobs, refer to the MPE/iX Commands Reference Manual .
Table 3-6. Examples of RUN and FILE Commands :RUN DBSCHEMA.PUB.SYS Uses all default les. Prompts for lines of schema in session mode. :FILE DBSTEXT=ORDERSSC :RUN DBSCHEMA.PUB.SYS;PARM=1 Processes schema from a user disk text le named ORDERSSC. Outputs listing to $STDLIST. :FILE DBSLIST;DEV=LP :RUN DBSCHEMA.PUB.SYS;PARM=2 Prompts for lines of schema and outputs the listing to a line printer. :FILE DBSTEXT=ORDERSSC :FILE DBSLIST=ORDERLST :RUN DBSCHEMA.PUB.
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. 1985 /ADD 1 $PAGE "SCHEMA OF DATA BASE ORDERS" 2 $CONTROL ERRORS=5, BLOCKMAX=256 3 BEGIN DATABASE ORDERS; . . . 59 END. 60 // ... /KEEP ORDERSSC /EXIT :FILE DBSLIST;DEV=LP :FILE DBSTEXT=ORDERSSC :RUN DBSCHEMA.PUB.SYS;PARM=3 HP30391C.03.
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 rst character of the record, immediately followed by the command name, which must be completely spelled out. If a parameter list is included with the command, it must be separated from the command name by at least one blank.
$PAGE The $PAGE command causes the list le 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. A quotation mark within a character-string is speci ed by a pair of quotation marks.
$TITLE The $TITLE command speci es 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 speci ed by a pair of quotation marks.
$CONTROL The $CONTROL command allows you to specify options in relation to processing the schema. Syntax LIST $CONTROL NOLIST 2 2 ,BLOCKMAX=nnnn ,ERRORS=nnn 3 ,TABLE ,NOTABLE 32 ,LINES=nnnnn ,JUMBO ,NOJUMBO 3 ,ROOT ,NOROOT Parameters LIST NOLIST ERRORS=nnn LINES=nnnnn ROOT NOROOT BLOCKMAX=nnnn TABLE NOTABLE JUMBO NOJUMBO causes each source record of the schema to be printed on the list le. speci es that only source records with errors be printed on the list le.
Description The default parameters are LIST, ROOT, TABLE, and NOJUMBO. If no $CONTROL command is used, the results are the same as if the following $CONTROL command is used: $CONTROL LIST,ERRORS=100,LINES=60,ROOT,BLOCKMAX=512,TABLE The parameters can be placed in any order but must be separated by commas. To specify a jumbo data set, the JUMBO option must be included in the schema before de ning any jumbo data sets.
Schema Processor Output The Schema Processor prints the following heading on the rst 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 di erent from the list le, an abbreviated product identi cation is also printed on $STDLIST.
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 ( elds) in each entry of the data set. PT CT Path count. For a master data set, this is the number of paths speci ed for the data set key item.
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 le. BUFFER LENGTH is the length in halfwords of each of the data bu ers (unused by TurboIMAGE/XL but provided for compatibility with TurboIMAGE on MPE V; refer to the discussion on bu er speci cations in appendix H).
Schema Processor Example Figure 3-5 contains the list le output printed when the schema of the sample ORDERS database is processed. The database has 5 passwords and contains 23 data item de nitions and 6 data set de nitions. The Schema Processor summary information is printed following the schema.
PAGE 1 HEWLETT-PACKARD 30391C.05.00 TurboIMAGE/3000: DBSCHEMA MON, JAN 10, 1994, 3:32 PM (C) HEWLETT-PACKARD CO.
PAGE 2 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(1), STREET-ADDRESS, CITY, STATE, ZIP; 201; INVENTORY,DETAIL(12,14/13,18),DISC2; <> STOCK#(PRODUCT), ONHANDQTY, SUPPLIER(!SUP-MASTER), <> UNIT-COST, LASTSHIPDATE(DATE-MASTER), BINNUM; 1800,450,10%; SALES
4 Using the Database After you design the database, create the root le, 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 speci cations used by the Report Program Generator to make calls to the TurboIMAGE/XL procedures for you.
Database Control Blocks TurboIMAGE/XL executes using data stored in di erent types of control blocks stored in privileged mapped les or virtual data objects: the Database System Control Block (DBS), the Database Globals Control Block (DBG), the Database Bu er 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-database Transaction Table (TURBOGTX), DBQU
The TurboLock Table is a permanent le, TURBOLKT.PUB.SYS, that is created by DBOPEN (if it does not exist beforehand). Thereafter, it is opened when the rst user opens any database on the system. It is purged when the system is rebooted. Each system has only one TURBOLKT le. It is used to avoid deadlocks for all IMAGE/SQL users. Additionally, it is also used to detect potential deadlock for TurboIMAGE/XL users if, and only if, deadlock detection is activated by DBCONTROL mode 7.
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. CIUPDATE is discussed later in this chapter.
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. If an access mode 3 or 7 user is currently accessing the database, it cannot be opened until that user closes the database.
The programmer must be aware of the possibility that other access mode 2 users are simultaneously updating data entries. In many applications, it may be possible to arrange for each user's process to update unique data entries or data items so that the database will correctly re ect all changes, even data items in the same entry updated by di erent processes. On the other hand, if two or more processes update the same data items of the same entry, the database will re ect only the latest values.
Selecting a Database Access Mode When deciding which access mode to use, the following are two important considerations: Use the minimum capability required to accomplish the task. For example, select a read-only access mode (5, 6, 7, or 8) if the program does not alter the database in any way. Read access modes allow concurrent database STORE operations and do not set the MPE/iX \ le modi ed" ag. Allow concurrent users to have as much capability as is required for successful completion of the task.
Access Mode 6 Access Mode 7 Access Mode 8 changes during one or more read operations. Because concurrent access mode 1 processes are allowed, programs performing chained reads should lock the chain (see the discussion of DBGET in chapter 5). Can be used if it is not important what other processes are doing to 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 bu er containing values for these items.
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. TurboIMAGE/XL coordinates calls to DBPUT to ensure that one database user's DBPUT activity does not interfere with calls made by other users accessing the same database.
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. Key and Search Items TurboIMAGE/XL performs checks on the values of detail data set search items before adding an entry to a data set. When adding records to a manual master, TurboIMAGE/XL veri es that the master data set key item value is unique for the set (that is, no entry currently contains a key item with the same value).
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 speci c 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.
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). Other numbers that can be used for directed reads are the forward and backward pointers returned in status halfwords 7-8 and 9-10.
calling program's bu er. If no such entry exists, the program is noti ed by an exceptional condition return, such as end-of- le, beginning-of- le, or no entry. This access method can be used with any type of data set and is useful in situations where the calling program has already determined the record number of the entry to be read.
Note When using serial access with master data sets, you should be aware of migrating secondaries. These are described in chapter 10. Locking. If concurrent users are allowed to modify the data set (access mode 1), you may wish to lock the data set or database before you begin the serial access sequence. Locking prevents entries from being added, modi ed, moved, or removed by the other processes.
Chained access to master data sets retrieves the next entry in the current synonym chain. The use of synonym chains applies to only a limited number of special situations. They are discussed in chapter 10. Chained access to detail data sets is particularly useful when you want to retrieve information about related events such as all inventory records for the H&S Surplus supplier in the ORDERS database.
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. Note that if a DBFIND procedure call has been made, the current record is zero and a request to reread the entry causes DBGET to return an exceptional condition indicating that the current record contains no entry.
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.
The password you use to open the database must grant update capability to the data items you intend to change. The user class number associated with the password must either be in the write class list of the data set containing the items to be updated, or in both the read class list of the data set and in the write class list of the data item.
Programmers should review the design of any of their applications that are used to update the values of data items to ensure that the data will be updated as expected. Applications that open the database in access mode 2 do not need to be modi ed, because only access modes 1, 3, and 4 can be used with CIUPDATE.
11. If the status code is zero and this is a logical transaction, call DBEND or, alternatively, DBXEND to declare the end of the modi cations. However, if this is a dynamic transaction and DBXUNDO was used to roll back the transaction, your program logic should ensure that the subsequent call to DBXEND is not processed. 12. Call DBUNLOCK to release all of the locks.
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 rst 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.
Access Modes and User Class Numbers To update data items, the database must be opened with access mode 1, 3, or 4. If it is opened with access mode 1, the DBLOCK procedure must be used to lock the detail data entry, data set, or database before an entry can be deleted and DBUNLOCK should be called after one or all desired entries have been deleted.
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.
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.
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 speci ed 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.
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.
Choosing a Locking Level Because TurboIMAGE/XL needs more information to lock data entries than to lock the whole database, program complexity tends to increase as locks are employed at lower and lower levels. Locking the whole database or a single data set is the simplest operation, followed in increasing order of complexity by locking multiple data sets and locking data entries.
Strong Locking and Dynamic Transactions Dynamic transactions, which are described later in this chapter, are only allowed with a database access mode that enforces locking, because strong locking is required for this type of transaction. TurboIMAGE/XL requires that dynamic transactions be independent of all other types of transactions. This is guaranteed when the database access mode is 3 or 4, because the mode guarantees exclusive modify access.
Table 4-3. 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. Lock the data set before determining which data entry is needed.
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. DBFIND the CUSTOMER master data set entry with ACCOUNT = 89393899 in order to prepare to read the chain of SALES data entries with the same ACCOUNT value. 3. DBGET each entry in the chain and display it to the user until the correct order is located. 4.
that execute successfully using TurboIMAGE/XL locks in a single process environment will not execute in a process-handling environment without MR (Multiple RIN) capability. (Refer to appendix D for more information on the MR capability.) Releasing Locks The locks held by a process for a particular access path of a database are relinquished when the process calls DBUNLOCK; they are automatically relinquished when the process closes the database, terminates, aborts, or is aborted by an operator.
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.
TurboIMAGE/XL calls the MPE/iX logging intrinsics OPENLOG, WRITELOG, and CLOSELOG in order to log information to the log le. When a database is opened, DBOPEN calls the OPENLOG intrinsic using the log identi er and password stored in the database root le. If this call succeeds, DBOPEN calls WRITELOG to log a DBOPEN log record containing information about the database and the new user.
DBXEND, to mark the beginning and end of a sequence of calls which constitute a single logical transaction. For reasons explained more fully under \Locking Requirements for Logical Transactions" in chapter 7, the following sequence of operations should be followed as closely as possible when performing modi cations: 1. Call DBLOCK to lock all data which must not be changed by other processes during the transaction. This includes data to be read and data to be modi ed. 2.
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.
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.
Checking the Status of a Procedure Each time a procedure is called, TurboIMAGE/XL returns status information in a bu er speci ed by the calling program and, if the program is in Compatibility Mode, sets the CM condition code maintained by MPE/iX. The CM condition code, or the TurboIMAGE/XL return status (described later), should be checked immediately after TurboIMAGE/XL returns from the procedure to the calling program before another procedure call is made.
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 bu er speci ed by the calling program.
5 TurboIMAGE/XL Library Procedures Using TurboIMAGE/XL Intrinsics This chapter contains the reference speci cations for the TurboIMAGE/XL library procedures (also known as intrinsics), arranged alphabetically. Table 5-1 gives a summary of the procedures with a brief description of their function. On the following pages, the calling parameters for each procedure are de ned in alphabetical order for easy look-up rather than the order in which they appear in the call statement.
Table 5-1. TurboIMAGE/XL Procedures Procedure Function DBBEGIN When logging, designates the beginning of a transaction and optionally writes user information to the log le. DBCLOSE Terminates access to a database or a data set, or resets the pointers of a data set to their original state. DBCONTROL Allows a process operating in exclusive mode to enable or disable the deferred output (AUTODEFER) option.
Table 5-1. TurboIMAGE/XL Procedures (continued) Procedure Function DBUPDATE Modi es the values of data items. Cannot be used to update master data set key items. Can be used to update detail data set search and sort items in database access mode 1, 3, or 4 if permitted by the critical item update (CIUPDATE) option settings for the database and the current process. DBXBEGIN Designates the beginning of a dynamic transaction.
Unused Parameters When calling some procedures for a speci c purpose, one of the parameters can be ignored; however, it still must be listed in the call statement. An application program may nd it useful to set up a variable named Not Used Parm or DUMMY to be listed as the unused parameter as a reminder that the value of the parameter does not a ect the procedure call. Refer to the examples in chapter 6. The Status Array The status array is a communication area.
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 le. DBBEGIN is used in conjunction with DBEND to begin and end a static or multiple database transaction.
DBBEGIN database transaction. DBBEGIN mode 3 (with base IDs 11, 12, and 13 speci ed in the baseidlist parameter) generates the following log record sequence: DBBEGIN (11, 1/3) DBBEGIN (12, 2/3) DBBEGIN (13, 3/3) . . . database. updates . . DBEND (11, 1/3) DBEND (12, 2/3) DBEND (13, 3/3) Mode 4: where the notations 1/3, 2/3, 3/3 in the log records indicate \ rst of three," \second of three," and \third of three." Refer to chapter 7 for more details about user logging.
DBBEGIN Discussion DBBEGIN is called to designate the beginning of a sequence of TurboIMAGE/XL procedure calls which are jointly considered a single logical transaction. The transaction is either a static or multiple database transaction, based on the mode. The end of such a sequence is designated by a matching call to DBEND. If the calling process is logging, DBBEGIN causes a log record to be written to the log le which includes such information as the time, date, and user text bu er.
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 dset mode is the name of an array used as the base parameter when opening the database. The rst element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.
DBCLOSE status is the name of an array of 10 halfwords in which TurboIMAGE/XL returns status information about the procedure. If the procedure executes successfully, the status array contents are: Element Contents 1 If the procedure succeeds, the return status is 0. Table 5-6 describes the contents of element 1 when the procedure does not succeed. 2-4 Unchanged from previous procedure call using this array. 5-10 Procedure call information.
DBCLOSE 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.
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. It can also be used to set BTREEMODE1 option to ON or OFF and specify the wildcard character for the current DBOPEN or for the database (permanent).
DBCONTROL Mode 6: Mode 7: Mode 9: Mode 10: Mode 13: Mode 14: Mode 15: 5-12 current process unless an intervening call to DBCONTROL mode 6 disabled the option. If the CIUPDATE ag is DISALLOWED, a call to mode 5 returns an error. The CIUPDATE option is available only in database access modes 1, 3, and 4. Disable the critical item update option.
DBCONTROL Mode 16: status corresponding search items in details, if the key item has a B-Tree index. In other words, turn on the BTREEMODE1 ag for the current database open. The rst byte of the quali er is examined. If it is null or blank, then the current wildcard character is not changed. If it is in the ASCII range (33 . . . 126), then the wildcard character is changed to that value for the current DBOPEN. If the quali er is any other value, DBCONTROL returns an error.
DBCONTROL In TurboIMAGE/XL default mode, MPE/iX Transaction Management (XM) is used to log database modi cations (DBPUTs, DBDELETEs, DBUPDATEs) to the XM log le. With deferred output, MPE/iX Transaction Management is not used. Instead, the MPE/iX le system default mode is used. This mode keeps data pages in memory for as long as possible, either until le close time or until no more memory is available.
DBCONTROL Consult appendix A for more information about the conditions for the return status values shown in Table 5-7. Table 5-7. DBCONTROL Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: -4 -168 -175 -176 -178 -179 -189 -11 -14 -31 -80 -81 -82 -222 -224 -421 -422 -423 -424 -425 -426 -427 -428 -432 -434 -436 -440 -441 -442 -443 -451 -452 Communications Errors: Exceptional Conditions: 92 -102 63 FREADLABEL failure.
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 dset mode status 5-16 is the name of the array used as the base parameter when opening the database. The rst element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.
DBDELETE 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. When deleting entries from master data sets, the following rules apply: All pointer information for chains indexed by the entry must indicate that the chains are empty.
DBDELETE dynamic transaction, 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. DBXUNDO will abort the entire transaction. DBXEND will terminate the dynamic transaction; the modi cations completed thus far within the transaction will remain in the database. Table 5-8.
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 le. DBEND is used in conjunction with DBBEGIN to begin and end a static or multiple database transaction.
DBEND Mode 3: End of multiple database transaction. If user logging is enabled for the databases, mode 3 generates multiple entries in the log le in order to mark multiple database transactions. For example, assume that base IDs 11, 12, and 13 are involved in a multiple database transaction. DBEND mode 3 (with base IDs 11, 12, and 13 speci ed in the baseidlist parameter) generates the following log record sequence: DBBEGIN (11, 1/3) DBBEGIN (12, 2/3) DBBEGIN (13, 3/3) . . . database. updates . .
DBEND textlen is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes to be logged. Length can be zero. Discussion DBEND is called to designate the end of a sequence of TurboIMAGE/XL procedure calls which are collectively considered a static or multiple database transaction. The beginning of such a sequence is designated by a previous call to DBBEGIN. Note DBEND is not valid if a transaction was begun with DBXBEGIN.
DBEND Table 5-9. DBEND Return Status Values Calling Errors: -11 -31 -146 -147 -148 -151 -153 -216 -222 Communications Errors: -102 -106 -107 -111 -113 -193 63 Logging System Failures: Exceptional Conditions: Bad database reference. Bad mode. Invalid transaction ID. Mode doesn't match DBBEGIN mode. Base ID list doesn't match DBBEGIN base ID list. Text length greater than 512 bytes. No transaction in progress to end. Cannot end a dynamic transaction with a DBEND.
DBERROR DBERROR INTRINSIC NUMBER 419 Moves a message, as an ASCII character string, to a bu er speci ed 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,bu er,length Parameters status bu er length Note is the name of the array used as the status parameter in the TurboIMAGE/XL procedure call about which information is requested.
DBERROR 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.
DBERROR Table 5-10.
DBERROR Table 5-10. DBERROR Messages (continued) Return Status DBERROR Message -91 ROOT FILE (DATABASE) NOT COMPATIBLE WITH CURRENT TURBOIMAGE INTRINSICS -92 DATABASE REQUIRES CREATION (VIRGIN ROOT FILE) -93 DATABASE ALREADY EXISTS.
DBERROR Table 5-10. DBERROR Messages (continued) Return Status DBERROR Message -112 CLOSELOG RETURNED ERROR NUMBER nn TO intrinsic name LOG PROCESS TERMINATED [3] LOG FILE CAN'T OBTAIN NECESSARY DISC SPACE [12] END OF FILE ON LOGFILE [15] -113 FLUSHLOG RETURNED ERROR NUMBER nn TO DBEND -114 ROLLBACK ENABLED WITHOUT ENABLING LOGGING -120 OUT OF STACK SPACE TO PROCV.
DBERROR Table 5-10.
DBERROR Table 5-10.
DBERROR Table 5-10.
DBERROR Table 5-10.
DBERROR Table 5-10. DBERROR Messages (continued) Return Status 5-32 DBERROR Message -332 ERROR IN QLOCK OPERATION. -333 ERROR IN QOPEN OPERATION. -420 FEATURE NOT IMPLEMENTED. -421 BTE:UNKNOWN QUALIFIER VALUE FOR DBCONTROL MODE 13. -422 BTE: DATA SET # NOT IN VALID RANGE. -423 BTE: B-TREE ALREADY EXISTS. -424 MESSAGE nBTE: FAILED TO CREATE B-TREE. -425 MESSAGE nBTE: DB NOT OPENED EXCLUSIVELY. -426 BTE: B-TREE DOESN'T EXIST. -427 BTE: FCLOSE, PURGE FAILED.
DBERROR Table 5-10. DBERROR Messages (continued) Return Status DBERROR Message -446 BTE: ARGUMENT 2 SPECIFIED FOR RELOP OF (=/>). -447 BTE: FAILED TO BUILD RECORD HOLDING ROOT DATA INFORMATION. -448 BTE: FAILED TO SETUP INFORMATION FOR USERLABEL 0 OF DATASET. -449 BTE: FAILED TO POSITION INDEX AT START OF KEY RANGE. -451 BTE: ROOT VERSION LESS THAN "C4". -452 BTE: KEY LENGTH GREATER THAN 252 BYTES (MAXIMUM INDEX KEY SIZE). -458 DBOPEN FAILED.
DBERROR Table 5-10.
DBERROR Table 5-10. DBERROR Messages (continued) Return Status DBERROR Message 51 STACK OVERFLOW FOR BASIC - IMAGE INTERFACE. 52 INVALID PARAMETER FOR BASIC - IMAGE INTERFACE. 53 INVALID PARAMETER TYPE FOR BASIC - IMAGE INTERFACE. 60 DATABASE ACCESS DISABLED 61 PROCESS HAS THE DATABASE OPEN 63 TIMES; NO MORE ALLOWED 62 DBG CONTROL BLOCK FULL 63 DBG DISABLED; POTENTIAL DAMAGE; ONLY DBCLOSE ALLOWED 64 NO ROOM FOR DBG ENTRY IN PCBX (MPE PORTION OF STACK) 65 CAN'T GRANT BUFFER REQUEST.
DBEXPLAIN INTRINSIC NUMBER 418 Prints a multiline message on the $STDLIST device describing a TurboIMAGE/XL procedure call and explaining the call's results as recorded in the calling program's status array. Syntax DBEXPLAIN,status Parameters status is the name of the array used as the status parameter in the TurboIMAGE/XL procedure call about which information is requested.
DBEXPLAIN Table 5-11.
DBEXPLAIN Table 5-10. DBEXPLAIN Message Format (Continued) Parameter Explanation message A description of the result based on the condition word and other status array information. The message is generated by the DBERROR procedure which is also described in this chapter. See Table 5-9 for all possible messages returned in line 4. hex display A listing of each halfword of status printed as a string of 4 hex digits.
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.
DBFIND mode must be an integer equal to 1, 4, 10, 21, or 24. If your database is enabled for third-party indexing, refer to your vendor's documentation for additional DBFIND modes. Mode Method 1 Used for both B-Tree or non-B-Tree DBFIND. Perform a B-Tree DBFIND if ALL of the following conditions prevail: Item type is X or U (ASCII).
DBFIND will have 231 01 and 7-8 and 9-10 will have zeroes. The argument is in structured format described under argument . status item argument The third-party indexing (TPI) modes of DBFIND which are NOT supported for B-Trees are: 11, 12, and various TPI DBFIND modes 1nn, 2nn, 3nn, 4nn, and 5nn. If your database is enabled for TPI, refer to your vendor documentation for additional DBFIND modes. The section on DBUTIL in chapter 8 of this book has a brief description of the TPI option.
DBFIND Bytes Meaning 1-2 Type of generic search.
DBFIND If a wildcard character is present in the argument(s), the wildcard will be considered as part of the value for these B-Tree search types: =t, t, >=, [ ], or PK on ASCII types. If your database is enabled for third-party indexing (TPI), refer to your vendor documentation for information on DBFIND arguments. The section on DBUTIL in chapter 8 of this book has a brief description of the TPI option.
DBFIND Note A call to DBOPEN does not open individual data sets. Thus, a call to DBFIND (or DBGET) that accesses a data set for the rst time (or after the data set has been closed), must open the data set, as well as the B-Tree index le (if applicable). This causes extra overhead not incurred by subsequent calls to the same data set by DBFIND or DBGET. Consult appendix A for more information about the conditions for the DBFIND return status values shown in Table 5-12.
DBFIND Table 5-12. DBFIND Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: Communications Errors: Exceptional Conditions: -1 -3 -4 -168 -169 -175 -176 -178 -209 -11 -21 -31 -51 -52 -222 -258 -259 -260 -426 -429 -430 -431 -432 -433 -434 -436 -437 -438 -439 -444 -446 -449 -102 -106 -107 -193 -3nn -314 17 63 FOPEN failure. FREADDIR failure. FREADLABEL failure. Cannot attach n to MPE XL XM: le system error nn . Invalid mode for XM attach options.
DBGET INTRINSIC NUMBER 405 Provides eight di erent methods for accessing the entries of a data set. Syntax DBGET,base,dset,mode,status,list,bu er,argument Parameters base dset mode is the name of the array used as the base parameter when opening the database. The rst element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about base ID.
DBGET parameter is ignored). Super-chains are traversed for detail data sets. 7 8 status list If your database is enabled for third-party indexing (TPI), refer to your vendor documentation for additional information. Calculated Read. (Master data sets only.) Read the entry with a key item value that matches the value speci ed in argument . The entry is in the master data set speci ed by dset . Primary Calculated Read. (Master data sets only.
DBGET The current list is unchanged until a di erent list is speci ed in a subsequent call to DBGET, DBPUT, or DBUPDATE for the same access path and data set. bu er argument Some special list constructs are allowed. These are described in Table 5-20 with the DBPUT procedure. List processing is a relatively high overhead operation which can be shortened in subsequent calls by using the asterisk construct to specify that the current list is to be used.
DBGET Table 5-13. DBGET Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: Communications Errors: Exceptional Conditions: -1 -3 -4 -168 -169 -175 -176 -178 -209 -11 -21 -31 -51 -52 -222 -102 -106 -107 10 11 12 13 14 15 17 18 49 50 62 63 -193 -3nn -332 -333 FOPEN failure. FREADDIR failure. FREADLABEL failure. Cannot attach n to MPE XL XM: le system error nn . Invalid mode for XM attach options. Cannot attach n to MPE XL XM: XM error nn .
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.
DBINFO Table 5-14. DBINFO Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: -1 -4 -168 -169 -175 -176 -178 -209 -11 -21 -31 -222 Communications Errors: -102 -106 -107 -206 Exceptional Conditions: 49 50 63 FOPEN failure. FREADLABEL failure. Cannot attach n to MPE XL XM: le system error nn . Invalid mode for XM attach options. Cannot attach n to MPE XL XM: XM error nn . Cannot detach n from MPE XL XM: XM error nn .
DBINFO Mode 101: Item Number Mode 101 de nes the type of access available for a speci c item. Quali er identi es the data item name or number for which the information is requested. Bu er returns the following (each element is a halfword or two bytes): Element 1 Contents +/0 Data item number If the data item number is positive, the user class has only read access to the data item.
DBINFO Mode 103: Items in Database Mode 103 identi es 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 de ned in the item section of the schema but are not referenced by at least one data set. Quali er is ignored. Bu er returns the following (each element is a halfword or two bytes): Element Contents 1 Item count x 2 .. . +/0 Data item number 1 .. .
DBINFO Mode 113: BTREEMODE1 and Wildcard Character Mode 113 gives the settings of BTREEMODE1 and wildcard character in the root le as well as current DBOPEN (DBU). Quali er is ignored. Bu er 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 o in the root le 1 if BTREEMODE1 is on in the root le 2 The rst byte (8 bits) is always 0. The second byte (8 bits) represents c , where c is the current wildcard character.
DBINFO Mode 201: Set Number Mode 201 de nes the type of access available for a speci c data set. Quali er identi es the data set name or number for which the information is requested. Bu er returns the following (each element is a halfword or two bytes): Element 1 Contents +/0 Data set number If the data set number is positive, the user class has only read access. If the number is negative, the user class has both read and write access. Mode 202: Set Name Mode 202 describes a speci c data set.
DBINFO Mode 203: Sets in Database Mode 203 identi es all data sets available in a database and the type of access allowed. If you are using third-party indexing, this mode does not show third-party index les. Quali er is ignored. Bu er returns the following (each element is a halfword or two bytes): Element Contents 1 Set count x 2 .. . +/0 Data set number 1 .. .
DBINFO Mode 205: Set Capacity Mode 205 is an extension of mode 202 with dynamic capacity expansion information. Quali er identi es the data set name or number for which the information is requested.
DBINFO Mode 206: Number of Data Set Chunks Mode 206 gives the number of chunks in a data set in short format. Quali er identi es the data set name or number for which the information is requested. Bu er returns the following (each element is a halfword or two bytes): DBINFO Mode 206 Element 1 Contents # of chunks in a jumbo data set If the data set is not a jumbo data set, zero is returned for the number of chunks.
DBINFO Mode 208: Primary and Actual Capacity Mode 208 returns the primary and actual capacity. Quali er identi es the data set name or number for which the information is requested. Bu er must be at least a 64-byte record and returns the following (each element is a 32-bit Word): Element Contents 1 Primary (hashing) capacity for masters, 0 for details 2 Current capacity, including expansions 3 Maximum capacity 4 Expansion threshold: -1 . . .
DBINFO Mode 209: B-Tree Attachment Mode 209 informs whether or not a B-Tree exists for a master. Quali er is a master data set name or number. Bu er must be at least a 64-byte record and returns the following (each element is a 32-bit Word): Element 1 Contents 0 if no B-Tree index exists 1 if B-Tree index exists 2 0 if attached B-Tree not damaged or index does not exist 1 if the attached B-Tree index is damaged 3 . . .
DBINFO Mode 301: Paths Mode 301 identi es the paths de ned for a speci ed data set. Quali er identi es the data set name or number for which the information is requested. Bu er returns the following (each element is a halfword or two bytes): Element Contents 1 Path count x 2 Data set number of path 1 3 Search item number of path 1 4 .. . Sort item number of path 1 .. .
DBINFO Mode 302: Key or Search Item Mode 302 identi es the key or search item for a speci ed data set. For this mode the two quali ers are shown separately. Quali er identi es the master data set name or number for which the information is requested. Bu er returns the following (each element is a halfword or two bytes): Element Contents 1 Key item number 2 0 If quali er speci es a master data set, the key item number is the number in the master set.
DBINFO Mode 401: Logging Mode 401 obtains information related to logging. Quali er is ignored. Bu er returns the following (each element is a halfword or two bytes): Element 1{4 Contents Log identi er name 5 Database log ag 6 User log ag 7 Transaction ag 8{9 User transaction number The log identi er name is left-justi ed and padded with blanks if shorter than 8 characters. If the database is enabled for logging, the database log ag is 1; otherwise it is 0.
DBINFO Mode 402: ILR Mode 402 returns information about Intrinsic Level Recovery (ILR). Quali er is ignored. Bu er returns the following (each element is a halfword or two bytes): Element Contents 1 ILR log ag 2 Calendar date (mmddyy ) 3{4 Clock time (one word in format hhmmsstt ) 5 0 6{14 t 15{16 Reserved If the database is enabled for ILR, the ILR log ag is 1; otherwise it is 0. The calendar date is the date ILR was enabled. The clock time is the time ILR was enabled.
DBINFO Mode 403: Dynamic Roll-Back Mode 403 obtains information related to dynamic transaction activity on a given database. Quali er is ignored.
DBINFO Mode 404: Logging Subsystem Information Mode 404 returns information about multiple database transactions. Quali er is ignored.
DBINFO Mode 406: Database Information Mode 406 returns information about fully quali ed database name and open mode. Quali er is ignored. Bu er returns the following (each element is a halfword or two bytes): Element Contents 1-14 Fully quali ed database name, left justi ed, blank trailing. 15 Open mode for current DBOPEN. 16 Root le version of the database. In the form Cn where C is uppercase ASCII and n is a number. For example, C2 or C3. 17-24 For internal use. 25-32 Reserved.
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. Quali er is ignored.
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,quali er,mode,status Parameters base quali er mode Note is the name of the array used for the base parameter when opening the database. The rst element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about base ID.) Modes 1 and 2: Ignored.
DBLOCK 3 4 5-10 If the return status is 20, this element contains 0 if the database is locked, 1 if the data set or entries are locked. Reserved: Contents unde ned. Information about the procedure call and its results. Refer to \Library Procedure Error Messages" in appendix A for a complete description of this information. Concurrent processes running in a process-handling environment must have MR capability if they call DBLOCK.
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 quali er parameter is ignored. 2 Base Conditional DBLOCK applies a conditional lock to the database and returns immediately. A return status of zero indicates success. A non-zero return status indicates the reason for failure.
DBLOCK Figure 5-2. Qualifier Array Format for Locking Modes 5 and 6 Figure 5-3.
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 eld 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-justi ed, 16 characters long or, if shorter, terminated with a blank or semicolon (for example, SALES;).
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.
DBLOCK Table 5-17. DBLOCK Return Status Values Calling Errors: -11 -31 -121 -123 -124 -125 -126 -127 -128 -129 -130 -131 -132 -133 -134 -135 -136 -222 Communications Errors: -102 -103 -106 -107 Exceptional Conditions: 20 22 23 24 25 26 62 63 -192 -241 Bad database reference. Bad mode value. Descriptor count error. Illegal relop in a descriptor. Descriptor too short. Must be greater than or equal to 9. Bad set name/number. Bad item name/number. Attempt to lock using a compound item.
DBMEMO INTRINSIC NUMBER 414 Used to log user data (ASCII or binary) to the log le. Syntax DBMEMO,base,text,mode,status,textlen Parameters base text mode status textlen is the name of the array used as the base parameter when opening the database. The rst element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.
DBMEMO Table 5-18. DBMEMO Return Status Values Calling Errors: -11 -31 -151 -222 Communications Errors: -102 -106 -107 -111 -193 63 Logging System Failures: Exceptional Conditions: Bad database reference. Bad mode. Text length greater than 512 bytes. Only DBXUNDO allowed when a dynamic transaction encounters an error. DSWRITE failure. Remote 3000 data inconsistent. NS 3000 or DS 3000 system error. WRITELOG failure. DBU control block is full. DBG disabled; potential damage; only DBCLOSE allowed.
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.
DBOPEN If either the password or the user identi er 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. The user identi er is used by the program DBRECOV to distinguish between users logged on under the same name and account.
DBOPEN If your database is enabled for third-party indexing (TPI), refer to your vendor documentation for additional DBOPEN mode information. The section on DBUTIL in chapter 8 of this book has a brief description of the TPI option. 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.
DBOPEN expansion had not completed. Recovery correctly adjusts the data set free count and the root le data set capacity elds using the actual data set le size. Use the SHOW CAPACITY command in DBUTIL to detect if recovery is required for the data set. If the message, \dynamic capacity expansion in progress ag is on," is displayed for the data set, and asterisks are in the \no. of entries" and \%max cap" elds, then recovery is required for the data set(s).
DBOPEN Table 5-19. DBOPEN Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: -1 -2 -3 -4 -5 -6 -8 -9 -10 -168 -169 -175 -176 -177 -178 -179 -198 -208 -209 -210 -211 -11 -13 -21 -22 -31 -32 -34 -90 -91 -92 -94 -95 -96 -220 Communications Errors: -15 -60 -61 -100 -101 -102 -103 -104 -105 -106 -107 5-82 HPFOPEN or FOPEN failure. FCLOSE failure. FREADDIR failure. FREADLABEL failure. FWRITEDIR error. FWRITELABEL error. FUNLOCK failure.
DBOPEN Table 5-19. DBOPEN Return Status Values (continued) Logging System Failures: Native Language Support Errors: -110 -111 -114 -200 -201 -202 Exceptional Conditions: -167 -191 -199 -220 -226 -227 -234 -236 -250 -253 -331 -332 -333 60 61 62 63 64 66 68 OPENLOG failure. WRITELOG failure. Roll-back enabled without logging. Database language not system supported. Native Language Support not installed. MPE Native Language Support error decimal integer returned by NLINFO.
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,bu er Parameters base dset mode status list 5-84 is the name of the array used as the base parameter when opening the database. The rst element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about base ID.
DBPUT for data items in the list array. Search or sort items de ned for the entry must be included in the list array. Fields of unreferenced items are lled with binary zeros. The list array can contain a left-justi ed 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.
DBPUT Discussion for Master Data Sets When adding entries to master data sets, the following rules apply: The data set must be a manual master. The key item must be referenced in the list array and its value in the bu er array must be unique in relation to other entries in the master. Space must be available in the master set, or must be dynamically expandable to add an entry.
DBPUT a sorted chain is determined by a backward search of the chain beginning at the last entry. The position is maintained by logical pointers rather than physical placement in the le. Proper Native Language collating sequence must be maintained for chain sorting. If dynamic capacity expansion is allowed for the detail data set, when the detail data set reaches the end of the current allocation (that is, data set free count is zero), expansion is requested by the incremental amount.
DBPUT Table 5-21. DBPUT Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: -1 -3 -4 -5 -6 -167 -168 -169 -175 -176 -178 -199 -209 -11 -12 -14 -21 -23 -24 -31 -51 -52 -53 -222 Communications Errors: Logging System Failures: 5-88 -102 -106 -107 -111 FOPEN failure. FREADDIR failure. FREADLABEL failure. FWRITEDIR failure. FWRITELABEL failure. Cannot begin MPE XL XM transaction: XM error nn . Cannot attach n to MPE XL XM: le system error nn .
DBPUT Table 5-21. DBPUT Return Status Values (continued) Exceptional Conditions: -193 -196 -212 -264 -312 -314 -322 -332 16 18 43 62 63 1nn 2nn 3nn 4nn DBU control block is full. DBB control block is full. Database corruption detected. XM write procedure returned 1030 or 1040. Internal error encountered while reading database block. Error while obtaining path information for set. Error returned by process list. Error in QLOCK table operation. Data set full.
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 e ect for the speci ed access path are unlocked. If DBUNLOCK is called when a dynamic transaction is active and a modify intrinsic (DBPUT, DBDELETE, or DBUPDATE) has already been used in the dynamic transaction (that is, the database is modi ed), the DBUNLOCK fails.
DBUNLOCK Table 5-22. DBUNLOCK Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: -4 -6 -167 -199 -11 -31 -215 -222 -230 -231 Communications Errors: Exceptional Conditions: -102 -106 -107 63 MPE le error nn returned by DBUNLOCK on FREADLABEL. MPE le error nn returned by DBUNLOCK on FWRITELABEL. Cannot begin MPE XL XM transaction: XM error nn . Cannot end MPE XL XM transaction: XM error nn . Bad database reference. Bad mode.
DBUPDATE INTRINSIC NUMBER 406 Modi es values of data items in the entry residing at the current record address of a speci ed 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 modi cations made by other users.
DBUPDATE 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. If the corresponding bu er array values are the same as the current data item values, the list array can include data items to which the user has read access only, such as, key, search and sort items. This feature permits reading and updating with the same list array contents.
DBUPDATE Table 5-23. DBUPDATE Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: -1 -3 -4 -5 -167 -168 -169 -175 -176 -178 -199 -209 -11 -12 -14 -21 -31 -51 -52 -82 -222 Communications Errors: Logging System Failures: Exceptional Conditions: -102 -106 -107 -111 -193 -264 -3nn -312 -314 -332 17 41 42 49 50 62 63 68 FOPEN failure. FREADDIR failure. FREADLABEL failure. FWRITEDIR failure. Cannot begin MPE XL XM transaction: XM error.
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 le. DBXBEGIN is used in conjunction with DBXEND to begin and end a dynamic transaction.
DBXBEGIN status textlen mode 3 generates multiple entries in the log le, 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: Element Contents 1 If the procedure succeeds, the return status is 0. Table 5-24 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.
DBXBEGIN Table 5-24. DBXBEGIN Return Status Values File System, Memory Management, and Transaction Management Failures: Calling Errors: -4 -228 FREADLABEL error. DBXBEGIN encountered XM error nn when starting dynamic transaction. -11 -31 -139 -140 -151 -152 -217 -218 -219 Bad database reference. Bad (unrecognized) DBXBEGIN mode: n . Invalid number of base IDs. Bad base ID list. Text length greater than 512 bytes. DBXBEGIN called while a transaction is in progress.
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 le. DBXEND is used in conjunction with DBXBEGIN to begin and end a dynamic transaction.
DBXEND 5-10 textlen 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. Discussion DBXEND is called to designate the end of a sequence of TurboIMAGE/XL procedure calls that are collectively considered a dynamic transaction.
DBXUNDO INTRINSIC NUMBER 422 Rolls back the active sequence of TurboIMAGE/XL procedure calls which are considered a dynamic transaction. Syntax base ,text,mode,status,textlen DBXUNDO , baseidlist Parameters base baseidlist text mode status 5-100 is the name of the array used as the base parameter when opening the database. The rst element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.
DBXUNDO textlen is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes. Length can be zero. Discussion DBXUNDO is called to dynamically roll back a sequence of TurboIMAGE/XL procedure calls that completed successfully inside a dynamic transaction. The beginning of such a sequence is designated by a previous call to DBXBEGIN.
DBXUNDO Caution After DBXUNDO is called, the current record pointer, current path, current list, and chronological order prior to the call to DBXBEGIN may not be restored. DBXUNDO cannot be called to roll back a transaction started by DBBEGIN. DBXUNDO returns an error condition if it is called without a prior matching call to DBXBEGIN. DBXEND is not necessary after DBXUNDO. DBXUNDO rolls back the entire transaction, and then transactions continue according to the logic of the program.
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 speci c programming languages for use with Native Mode only. For Compatibility Mode examples, refer to the TurboIMAGE/V Database Management System Reference Manual .
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.
PAGE 1 HEWLETT-PACKARD 30391C.05.
PAGE 2 SCHEMA FOR DATABASE ORDERS NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: NAME: ENTRY: CAPACITY: END.
Model Program Conventions The following conventions are used throughout the model. 4n5 Refers to the option number assigned to each function shown in the main body of the program. t Indicates an intentional blank. ACCESS Indicates the user access mode, or how the database was opened for a particular routine. Note that for this model the user access mode is always 1 (shared modify access). Bu er Name is made up of Indicates that a data structure is being used.
RETURN START LOOP 6-6 Host Language Access Transfers control to the beginning of the iterative block in which it is used. Indicates the beginning of an iterative block.
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.
ORDERS Database Model Program 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 option = 9 Then CALL Rewind_Customer_Set and RETURN If option = 10 Then CALL Get_Data_Item_Info and RETURN If option
ORDERS Database Model Program OBTAIN DBname OBTAIN Password 0 "ttORDERS;" 0 "DO-ALL;" CALL DBOPEN (DBname, Password, Mode1_SMA, Status) ERROR CHECKING END ROUTINE Retrieving All the Records on a Chain (with Item Level Locking) 2 (USER SELECTS 4 5 TO RETRIEVE SALES DATA) ROUTINE: Get_Sales_For_Date * * * * * * * * * * * * * * * * * OBJECTIVE: This routine demonstrates chained access, forward chained read, and data item locking.
ORDERS Database Model Program OBTAIN OBTAIN OBTAIN OBTAIN OBTAIN OBTAIN Number_Of_Elements Length_Of_Descriptor Data_Set_Of_Descriptor Data_Item_Of_Descriptor Relative_Operator_For_Data_Item Value_For_Data_Item OBTAIN List OBTAIN Search_Item_Name OBTAIN Search_Item_Value 01 0 21 0 "SALES;" 0 "PURCH-DATE;" 0 "t=" 0 "881012" 0 0 0 "@;" "PURCH-DATE;" "881012" CALL DBLOCK (DBname, Lock_Descriptor_Sales_Array_Type, Mode5_Unconditional, Status) ERROR CHECKING CALL DBFIND (DBname, Sales_Detail, Mode1_Chained
ORDERS Database Model Program ____________________________________________________________________ Account Stock# Quantity Price Tax Total Purch-Date Deliv-Date EXIT LOOP if end of chain END LOOP CALL DBUNLOCK (DBname, Lock_Desc_Array, Mode1_Unlock, Status) ERROR CHECKING END ROUTINE Retrieving a Data Entry Using a Record Number 3 (USER SELECTS 4 5 TO RETRIEVE CUSTOMER DATA) ROUTINE: Get_A_Customer_Record * * * * * * * * * * * OBJECTIVE: This routine demonstrates directed access by retrieving a custom
ORDERS Database Model Program ____________________________________________________________________ Account Last-Name First-Name Initial Street-Address City. . . END ROUTINE Retrieving Master Data Using a Key Value 4 (USER SELECTS 4 5 TO RETRIEVE PRODUCT DATA) ROUTINE:Get_A_Product_Record * * * * * * * * * OBJECTIVE: This routine demonstrates calculated access by retrieving a product record from a master data set based on a user-defined key item value.
ORDERS Database Model Program Customer_Buffer is made up of: Account Last-Name First-Name Initial Street-Address City State Zip Credit-Rating CALL DBLOCK (DBname, Customer_Master, Mode3_Unconditional, Status) ERROR CHECKING 0 OBTAIN List "Account, Last-Name, First-Name, Initial;" START LOOP CALL DBGET (DBname, Customer_Master, Mode2_Forward, Status, List, Customer_Buffer, Not_Used_Parm) ERROR CHECKING DISPLAY List ____________________________________________________________________ Account Last-Name Fi
ORDERS Database Model Program Product_Buffer is made up of: Stock# Description 0 0 0 OBTAIN Stock# OBTAIN Description OBTAIN List user input user input "@;" CALL DBLOCK (DBname, Product_Master, Mode3_Unconditional, Status) ERROR CHECKING OBTAIN Text OBTAIN Textlen 0 0 "Add entry to Product set Begintt" 16 CALL DBBEGIN (DBname, Text, Mode1_Xbegin, Status, TextLen) ERROR CHECKING CALL DBPUT (DBname, Product_Master, Mode1_Put, Status, List, Product_Buffer) ERROR CHECKING OBTAIN Text OBTAIN Textlen 0 0
ORDERS Database Model Program * * * * * * * * CALLS: DBGET in mode 7 (calculated) DBLOCK in mode 5 (unconditional) DBBEGIN in mode 1 (transaction begin) DBGET in mode 1 (re-read) DBUPDATE in mode 1 (update) DBEND in mode 1 (transaction end) DBUNLOCK in mode 1 (unlock) BEGIN ROUTINE Customer_Buffer, Customer_Buffer_New, and Customer_Buffer_Old are made up of: Account Last-Name First-Name Initial Street-Address City State Zip Credit-Rating Lock_Descriptor_Customer_Type is made up of: Length_Of_Descriptor
ORDERS Database Model Program OBTAIN Textlen 0 18 CALL DBBEGIN (DBname, Text, Mode1_Xbegin, Status, Textlen) ERROR CHECKING CALL DBGET (DBname, Customer_Master, Mode1_Reread, Status, List, Customer_Buffer, Not_Used_Parm) ERROR CHECKING If Customer_Buffer is the same as Customer_Buffer_Old Then continue Otherwise Let the user know that the entry has been modified by another user, end the transaction, and release the locks.
ORDERS Database Model Program * * * * * DBBEGIN in mode 1 (transaction begin) DBGET in mode 7 (calculated read) DBDELETE in mode 1 (delete) DBEND in mode 1 (transaction end) DBUNLOCK in mode 1 (unlock) BEGIN ROUTINE Product_Buffer is made up of: Stock# Description CALL DBLOCK (DBname, Product_Master, Mode3_Unconditional, Status) ERROR CHECKING OBTAIN OBTAIN OBTAIN OBTAIN List Text Textlen Key_Item_Value 0 0 0 0 "@;" "Delete entry from Product set Begin t" 18 "STK30040" CALL DBBEGIN (DBname, Text, Mod
ORDERS Database Model Program BEGIN ROUTINE CALL DBCLOSE (DBname, Customer_Master, Mode2_Rewind, Status) ERROR CHECKING END ROUTINE Obtaining Database Information 10 (USER SELECTS 4 5 TO OBTAIN INFORMATION ABOUT A DATA ITEM) ROUTINE: Get_Data_Item_Info * * * * * * * * OBJECTIVE: This routine obtains information about a data item by calling DBINFO in mode 102.
ORDERS Database Model Program BEGIN ROUTINE Error_Buffer is made up of: Error_Message CALL DBERROR (Status, Error_Buffer, Error_Length) DISPLAY the Error_Buffer ____________________________________________________________________ Error_Message CALL DBEXPLAIN (Status) END ROUTINE Closing the Database 12 (USER SELECTS 4 5 TO CLOSE THE DATABASE) ROUTINE: Close_The_Database * * * * * * * * OBJECTIVE: This routine closes the ORDERS database by calling the DBCLOSE intrinsic.
C This section shows, in C, portions of the model program presented at the beginning of this chapter. The examples perform speci c 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 de ned at the beginning of the sample program. TurboIMAGE/XL intrinsics must be declared for C as external procedures.
C *Equal_Op *Item_List = " =", ="ACCOUNT,STOCK#,PRICE,TAX,TOTAL,PURCH-DATE;"; /* Define all your global variables.
C /* Beginning of subroutines */ Get_Error_And_Explain() { /* Access : Mode 1 - Shared Modified Access The Orders database was opened in mode 1 Called by: Open_The_Database Get_Sales_For_Date Get_A_Product_Record List_All_Customers Add_A_Product Update_A_Customer Delete_A_Product Rewind_Customer_Set Get_Data_Item_Info Close_The_Database Calls DBERROR DBEXPLAIN */ short short int : Error_Buffer[80]; Error_Length; Answer; DBERROR(&Status,Error_Buffer,&Error_Length); printf("---------------------------
C Open_The_Database() { /* ACCESS : Mode 1 - Shared Modify Access (SMA) with locking required Called By: Main Line Calls DBOPEN in mode 1 (SMA) Get_Error_And_Explain : */ Mode =1; } DBOPEN(DBname,Password,&Mode,&Status); if (Status.Condition != 0) Get_Error_And_Explain(); Retrieving All the Records on a Chain (with Item Level Locking) This paragraph implements the GET-SALES-FOR-DATE routine of the sample program.
C level locks on the Sales data set. */ Lock_Descriptor.Num_Of_Elements = 1; Lock_Descriptor.Length_Of_Descriptor = 21; strcpy(Lock_Descriptor.Data_Set_Of_Descriptor,(char *)Sales_D_Set); strcpy(Lock_Descriptor.Data_Item_Of_Descriptor,(char *)Purch_Date); Lock_Descriptor.Relop_For_Data_Item[0] = Equal_Op[0]; Lock_Descriptor.
C } if (Status.Condition == 0) { printf("\n"); printf("%11d",Sales_Buffer.Account_Number); printf("%13.8s",Sales_Buffer.Stock_Number); printf("%8d",Sales_Buffer.Price); printf("%6d",Sales_Buffer.Tax); printf("%7d",Sales_Buffer.Total); printf("%12.6s",Sales_Buffer.Purch_Date); } else { if (Status.Condition == End_Of_Chain) { printf("\n\n\n"); printf ("----> End Of Chain.
COBOL II COBOL II The model program presented at the beginning of this chapter is now shown here in COBOL II. The program performs speci c 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 de ned at the beginning of the sample program.
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 de nes all the data items and records. IDENTIFICATION DIVISION. PROGRAM-ID. RECEIVE. DATE-COMPILED. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES. SYMBOLIC CHARACTERS CLEAR, SCREEN IS 28, 86. DATA DIVISION. WORKING-STORAGE SECTION.
COBOL II 01 01 01 01 01 01 01 01 01 01 01 01 01 01 6-28 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). 05 DELIV-DATE-OUT PIC B(6)X(6). SALES-BUFFER-HEADER. 05 ACCOUNT-NUMBER-HEAD PIC X(13) VALUE "Acct-Number ". 05 STOCK-NUMBER-HEAD PIC X(15) VALUE "Stock-Number ". 05 QUANTITY-HEAD PIC X(05) VALUE "QTY ". 05 PRICE-HEAD PIC X(07) VALUE "Price ". 05 TAX-HEAD PIC X(06) VALUE "Tax ".
COBOL II 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. 05 ACCOUNT-NUMBER PIC S9(9) COMP. 05 LAST-NAME PIC X(16). 05 FIRST-NAME PIC X(10). 05 INITIAL1 PIC X(02). 05 STREET-ADDRESS PIC X(26). 05 CITY PIC X(12). 05 STATE PIC X(02). 05 ZIP PIC X(06). 05 CREDIT-RATING PIC X(08). 01 CUSTOMER-BUFFER-OLD. 05 ACCOUNT-NUMBER PIC S9(9) COMP. 05 LAST-NAME PIC X(16). 05 FIRST-NAME PIC X(10). 05 INITIAL1 PIC X(02).
COBOL II Main Body of Program PROCEDURE DIVISION. 10-MAIN-LINE. PERFORM WITH TEST AFTER UNTIL OPTION = 12 PERFORM 20-DISPLAY-MENU PERFORM 30-DO-ACTION END-PERFORM STOP RUN. 20-DISPLAY-MENU. DISPLAY CLEAR SCREEN DISPLAY MENU-LINE-1 DISPLAY MENU-LINE-2 DISPLAY MENU-LINE-3 DISPLAY MENU-LINE-4 DISPLAY MENU-LINE-5 DISPLAY MENU-LINE-2 DISPLAY MENU-LINE-6 DISPLAY MENU-LINE-7 DISPLAY MENU-LINE-8 DISPLAY MENU-LINE-9 DISPLAY MENU-LINE-10 DISPLAY MENU-LINE-11 DISPLAY MENU-LINE-2 DISPLAY MENU-LINE-1 DISPLAY SPACE.
COBOL II 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. 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.
COBOL II MOVE 1 TO NUM-OF-ELEMENTS MOVE 21 TO LENGTH-OF-DESCRIPTOR MOVE "SALES;" TO DATA-SET-OF-DESCRIPTOR MOVE "PURCH-DATE;" TO DATA-ITEM-OF-DESCRIPTOR MOVE " =" TO RELOP-FOR-DATA-ITEM DISPLAY CLEAR SCREEN DISPLAY " Enter The Date of Purchase as (YYMMDD) >>> " NO ADVANCING ACCEPT SEARCH-ITEM-VALUE FREE MOVE 5 TO DB-MODE MOVE SEARCH-ITEM-VALUE TO VALUE-FOR-DATA-ITEM CALL "DBLOCK" USING DBNAME, LOCK-DESCRIPTOR-ARRAY, DB-MODE, STATUS1 IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF MOVE "
COBOL II 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 MOVE TAX OF SALES-BUFFER TO TAX-OUT MOVE TOTAL OF SALES-BUFFER TO TOTAL-OUT MOVE PURCH-DATE OF SALES-BUFFER TO PURCH-DATE-OUT MOVE DELIV-DATE OF SALES-BUFFER TO DELIV-DATE-OUT DISPLAY SALES-BUFFER-OUT END-PERFORM END-IF MOVE 1 TO DB-MODE CALL "DBUNLOCK" USING DBNAME, SALES-DETAIL, DB-MODE, STATUS1 IF CO
COBOL II ELSE MOVE RECORD-NUMBER TO SAVED-RECORD-NUMBER IF CONDITION = NO-SUCH-ENTRY THEN DISPLAY CLEAR SCREEN DISPLAY "*****************************************" DISPLAY "* No Such Entry in the Customer Data Set." DISPLAY "* Please Try Again.
COBOL II DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY "* Zip = ", ZIP OF CUSTOMER-BUFFER "* *" "****************************************" SPACE SPACE "Press Enter to Continue ------------------>" NO ADVANCING ACCEPT OPTION FREE END-IF END-IF. Retrieving Master Data Using a Key Value This paragraph implements the GET-PRODUCT-RECORD routine of the sample program. The calculated access is achieved by a call to DBGET in mode 7.
COBOL II DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY "**********************************************" "* *" "* Stock # = ", STOCK-NUMBER OF PRODUCT-BUFFER "* Product = ", DESCRIPTION OF PRODUCT-BUFFER "* *" "**********************************************" SPACE SPACE "Press Enter To Continue ------------->" NO ADVANCING ACCEPT OPTION FREE END-IF. Retrieving Data Serially (with Set Level Locking) This paragraph implements the LIST-ALL-CUSTOMERS routine of the sample program.
COBOL II ELSE ELSE SET DONE TO TRUE DISPLAY SPACE DISPLAY "*End of Data Set" DISPLAY "* Press Enter to Continue ------->" NO ADVANCING ACCEPT OPTION FREE PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF MOVE ACCOUNT-NUMBER OF CUSTOMER-BUFFER TO ACCOUNT-NUMBER-CUST-OUT MOVE FIRST-NAME OF CUSTOMER-BUFFER TO FIRST-NAME-CUST-OUT MOVE INITIAL1 OF CUSTOMER-BUFFER TO INITIAL1-CUST-OUT MOVE LAST-NAME OF CUSTOMER-BUFFER TO LAST-NAME-CUST-OUT DISPLAY CUSTOMER-BUFFER-OUT END-IF END-PERFORM MOVE 1 TO DB-MODE CALL "DBUNLO
COBOL II DISPLAY " Please Provide the Following Values " DISPLAY "****************************************" DISPLAY "* *" DISPLAY "* Stock # = " NO ADVANCING ACCEPT STOCK-NUMBER OF PRODUCT-BUFFER FREE DISPLAY "* Product = " NO ADVANCING ACCEPT DESCRIPTION OF PRODUCT-BUFFER FREE DISPLAY "* *" DISPLAY "****************************************" DISPLAY SPACE DISPLAY SPACE DISPLAY "Enter, <1> to Continue, <2> to Retry >" NO ADVANCING ACCEPT ANSWER FREE END-PERFORM MOVE "PRODUCT;" TO PRODUCT-MASTER MOVE 3 TO DB
COBOL II Updating an Entry This paragraph implements the UPDATE-A-CUSTOMER routine of the sample program. The update process takes place in two phases. In the rst phase, the requested entry is located and retrieved. This is achieved by a call to DBGET in mode 7. Then, the user provides the new values. In the second phase, the recently modi ed values replace the existing entry. This is implemented using a call to DBUPDATE.
COBOL II ELSE 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-BUFFER DISPLAY "* *" DISPLAY "****************************************" DISPLAY SPACE DISPLAY SPACE DISPLAY "Press Enter to Continue ------------------>" NO ADVANCING ACCEPT OPTION F
COBOL II DISPLAY "Enter <1> to Continue, <2> to Retry >" NO ADVANCING ACCEPT ANSWER FREE IF ANSWER = 2 THEN DISPLAY CLEAR SCREEN END-IF END-PERFORM MOVE MOVE MOVE MOVE MOVE MOVE MOVE CALL 1 TO NUM-OF-ELEMENTS 22 TO LENGTH-OF-DESCRIPTOR "CUSTOMER;" TO DATA-SET-OF-DESCRIPTOR "ACCOUNT;" TO DATA-ITEM-OF-DESCRIPTOR " =" TO RELOP-FOR-DATA-ITEM KEY-ITEM-VALUE TO NUM-VALUE-FOR-DATA-ITEM 5 TO DB-MODE "DBLOCK" USING DBNAME, LOCK-DESCRIPTOR-ARRAY, DB-MODE, STATUS1 IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND
COBOL II MOVE "Update Entry On Customer Set End" TO TEXT1 MOVE 16 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, CUSTOMER-MASTER, DB-MODE, STATUS1 IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF END-IF. Deleting an Entry This paragraph implements the DELETE-A-PRODUCT routine of the sample program. The delete operation is achieved by a call to DBDELETE.
COBOL II PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF MOVE 7 TO DB-MODE CALL "DBGET" USING DBNAME, PRODUCT-MASTER, DB-MODE, STATUS1, LIST, PRODUCT-BUFFER, KEY-ITEM-VALUE-PRODUCT IF CONDITION NOT = 0 THEN IF CONDITION = NO-CHAIN-HEAD THEN DISPLAY CLEAR SCREEN DISPLAY "*****************************************" DISPLAY "* No Such Entry in the Product Data Set. *" DISPLAY "* Please Try Again.
COBOL II Rewinding a Data Set This paragraph implements the REWIND-CUSTOMER-SET routine of the sample program. Resetting the data set pointer is achieved by a call to DBCLOSE in mode 2. No special condition is trapped. ****************************************************************** * ACCESS : Mode 1 - Shared Modify Access * * Called By: 30-DO-ACTION * * Calls : DBCLOSE in mode 2 (rewind) * 1100-GET-ERROR-AND-EXPLAIN 900-REWIND-CUSTOMER-SET.
COBOL II Obtaining Error Messages and Explanations The following paragraph implements the GET-ERROR-AND-EXPLAIN routine of the sample program. This paragraph 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 paragraph, users can choose to abort or continue the execution of this program.
COBOL II ****************************************************************** * ACCESS : Mode 1 - Shared Modify Access * * Called By: 30-DO-ACTION * * Calls : DBCLOSE in mode 1 (close) * 1100-GET-ERROR-AND-EXPLAIN 1200-CLOSE-THE-DATABASE. MOVE 1 TO DB-MODE CALL "DBCLOSE" USING DBNAME, PASSWORD, DB-MODE, STATUS1 IF CONDITION NOT = 0 THEN PERFORM 1100-GET-ERROR-AND-EXPLAIN END-IF.
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 speci c tasks to illustrate the use of TurboIMAGE/XL intrinsics. Data items are de ned 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 le.
FORTRAN 77 Integer*2 Condition Integer*2 Length Integer*4 Record_Number Integer*4 Chain_Count Integer*4 Back_Pointer Integer*4 Forward_Pointer Equivalence(Status(1),Condition),(Status(2),Length) Equivalence(Status(3),Record_Number),(Status(5),Chain_Count) Equivalence(Status(7),Back_Pointer),(Status(9),Forward_Pointer) Common /Database_Status_Type/ Status C**** Set up for the Lock_Descriptor_Array of the Sales data set.
FORTRAN 77 Obtaining Error Messages and Explanations The following procedure implements the Get Error And Explain routine of the sample program. In this procedure, DBEXPLAIN and DBERROR are called using FORTRAN 77. DBEXPLAIN interprets the contents of the status parameter and prints a message on $STDLIST. DBERROR returns a message in ERROR Bu er, explaining the condition code returned by TurboIMAGE/XL. At the end of the procedure, users can choose to abort or continue the execution of this program.
FORTRAN 77 If (Answer.NE.1) Then Write(Out,*)' Continuing......' Else Stop Endif Return End Opening the Database This procedure implements the Open The Database procedure of the sample program. All required values, such as, the password, are provided by the routine. Note that the password DO-ALL is followed by a semicolon because it is less that 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.
FORTRAN 77 2. Status 15 from DBGET, indicating the end of the chain. The status interpretation routine permits you to either abort or continue with the execution after viewing all error messages.
FORTRAN 77 Data_Set_Name_Is = 'SALES;' Mode1_Chained_Read = 1 Search_Item_Name_Is = 'PURCH-DATE;' & Call DBFIND (DBname,Sales_Detail,Mode1_Chained_Read,Status, Search_Item_Name,Search_Item_Value) If (Condition.NE.0) Then If (Condition.EQ.No_Chain_Head) Then Print*,'_____________________________________________' Print*,'| |' Print*,'| No Such Entry In the Sales Data Set |' Print*,'| |' Print*,'|___________________________________________|' Print*,'Hit Enter to Continue ....................
Pascal Pascal Portions of the model program presented at the beginning of this chapter are now shown here in Pascal. The examples perform speci c tasks to illustrate the use of TurboIMAGE/XL intrinsics. Data items are de ned 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." Type declarations declare names for data structure forms that will be used in allocating variables.
Pascal Database_Status_Type Data_Set_Name_Type = 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..16] of Char; Data_Item_Name_Type (* for data item names *) = Packed Array [1..16] of Char; Data_Item_List_Type (* for the list parameter *) = Packed Array [1..
Pascal Procedure Procedure Procedure Procedure Procedure Procedure Procedure DBEXPLAIN DBERROR DBDELETE DBUPDATE DBLOCK DBUNLOCK DBINFO ; ; ; ; ; ; ; Intrinsic; Intrinsic; Intrinsic; Intrinsic; Intrinsic; Intrinsic; Intrinsic; Obtaining Error Messages and Explanations The following procedure implements the Get Error And Explain routine of the sample program. In this procedure, DBEXPLAIN and DBERROR are called using Pascal.
Pascal Opening the Database This procedure implements the Open The Database procedure of the sample program. All required values, such as the password, are provided by the routine. Note that 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. Error trapping is done by referring all non-zero conditions to the Get Error And Explain procedure.
Pascal Get_Error_And_Explain Var Lock_Descriptor_Array Sales_Detail Search_Item_Name Search_Item_Value Sales_Buffer Not_Used_Parm Mode1_Chained_Read Mode5_Unconditional Mode5_Forward Mode1_Unlock *) : : : : : : : : : : Lock_Descriptor_Sales_Array_Type; Data_Set_Name_Type; Data_Item_Name_Type; Packed Array [1..6]of Char; Sales_Data_Set_Type; Shortint; Shortint; Shortint; Shortint; Shortint; Begin (* Prepare the lock descriptor buffer for obtaining item level *) (* locks on the Sales data set.
Pascal End Else Begin Write('Acct-Number'); Write('Stock-Number':14); Write('Qty':6); Write('Price':7 ); Write('Tax':5); Write('Total':8); Write('Purch-Date':12); Write('Delive-Date':14); Write('---------------------------------------------------); Write('---------------------------'); Writeln; (* Start retrieving all records in the current chain. *) Mode5_Forward :=5; List :=' @;'; While Status.
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 les at the beginning of program execution, thereby calling DBOPEN for any databases named on File Description speci cations. Likewise, DBCLOSE is automatically called for databases at the end of program execution. Another example is the RPG CHAIN operation which calls DBFIND and/or DBGET, depending on its usage.
RPG **************************************************************** * TABLE/ARRAY DECLARATIONS * **************************************************************** E ESC 1 1 1 Escape = 27 **************************************************************** * INPUT RECORD LAYOUTS * **************************************************************** ISALES NS I B 1 40ACCT# I 5 12 STOCK# I 6 13 140QTY I 7 15 180$PRICE I 5 19 220$TAX I 8 23 260$TOTAL I 27 320PDATE I 33 380DDATE ITERMIN NS I 1 8 OPTION Main Body of Pr
RPG C SETOF 202122 C LOOP1 TAG C DATE CHAINSALES 2122 C*-------------------------------------------------------------C* No chain head found. C* C 21 EXCPT CLEAR C 21 EXCPT NOHEAD C 21 READ TERMIN H0 C 21 GOTO SKIP C*-------------------------------------------------------------C* End-of-chain found. C* C 22 EXCPT EOC C 22 READ TERMIN H0 C 22 GOTO SKIP C*-------------------------------------------------------------C* Any other error.
RPG C C C C C C C C* C OPTION IFEQ "2" EXCPT ELSE EXCPT GOTO GETOPT END END ERRCON BADOPT ENDSR Defining Output **************************************************************** * OUTPUT RECORD LAYOUTS * **************************************************************** O*-------------------------------------------------------------O* Display message for entry of invalid option. O* OTERMOUT E 1 BADOPT O 23 "Invalid option - please" O 33 " re-enter.
RPG O* O E 1 LINHDR O 23 "-----------------------" O *PLACE 46 O *PLACE 69 O 76 "-------" O*-------------------------------------------------------------O* Display message that no IMAGE chain head was found. O* O E 1 NOHEAD O 23 "***********************" O 39 "****************" O E 1 NOHEAD O 23 "* No Such Entry in the " O 39 "Sales Dataset *" O E 1 NOHEAD O 23 "* Please Try Again.
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.
DBRECOV If you use TurboSTORE/iX 7x24 True-Online Backup with ONLINE=START or ONLINE=END option to store your database, you can use the MPE RESTORE command which invokes TurboSTORE/iX 7x24 True-Online Backup to restore the database. Recovers a database from a log le, even when you used TurboSTORE/iX 7x24 True-Online Backup with ONLINE=START or ONLINE=END option to store the database. The DBRECOV utility allows you to set control commands and create individual user recovery les.
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 brie y below.
Dynamic roll-back recovery can be used with roll-forward recovery to handle disk media failures. Intrinsic Level Recovery (ILR). Intrinsic Level Recovery (ILR) is a recovery method provided within TurboIMAGE/XL. ILR ensures that all completed DBPUTs and DBDELETEs are recovered. On TurboIMAGE/XL, ILR is equivalent to calling DBEND mode 2 after every intrinsic. It is recommended that ILR not be used. It is not required for the DBRECOV roll-back recovery.
Logging and Recovery Considerations To ensure database integrity, the following responsibilities need to be assigned to speci c individuals: Enabling and disabling the logging and recovery processes. Creating database backup copies and synchronizing with log les. Performing actual recoveries when required. Note In the event of a system failure and subsequent recovery operation when using private volumes, logging will not resume until these private volumes have been mounted.
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 describes the types of logical transactions: static, multiple database, dynamic, and dynamic multiple database.
Table 7-1. Types of Logical Transactions Transaction De nition Static A logical transaction that begins with a DBBEGIN call and ends with a DBEND call. A static transaction spans only one database and uses DBBEGIN mode 1 and DBEND mode 1 or 2. Multiple database A logical transaction that begins with a DBBEGIN mode 3 or 4 call and ends with a DBEND mode 3 or 4 call. A multiple database transaction (MDBX) spans more than one database and can be recovered with roll-back or roll-forward recovery.
If logging is speci ed and DBBEGIN/DBEND (static transactions) or DBXBEGIN/DBXEND (dynamic transactions) are not used, TurboIMAGE/XL considers each DBPUT, DBDELETE, and DBUPDATE to be a single logical transaction. While a transaction is executing, the database is considered to be in an inconsistent state. Thus, each transaction takes the database from one consistent state to another.
Figure 7-1. Transactions and Transaction Blocks Locking Requirements for Logical Transactions DBRECOV requires that all multiple-intrinsic database transactions execute independently of all other transactions. Transaction independence within the database can be ensured in a user program by locking data before a transaction and then releasing locks after a DBEND or DBXEND is called, thus eliminating the possibility of another user modifying the same data at the same time.
Locking and Transaction Interdependence To maximize the extent of recovery, locking should be used with logging to eliminate interdependence of concurrent static and multiple database transactions. Locking by logical transaction (that is, DBBEGIN and DBEND or DBXBEGIN and DBXEND) guarantees the logical consistency of the database. For roll-back recovery, locking by logical transaction ensures that all incomplete transactions are backed out of the database.
Locking Examples Examples of the two recommended locking schemes follow: Single Lock Strategy DBLOCK for account 2,18,34 Lock should precede DBBEGIN call. 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 DBUNLOCK must be last call.
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.
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.
6. Call DBXEND to declare the end of the modi cations. 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. Dynamic roll-back requires strong locking as discussed previously under \Locking and Dynamic Transactions.
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 ushing of the Transaction Management (XM) log le after every intrinsic. This enforced ushing emulates the immediate posting of intrinsics by TurboIMAGE/V and should only be used if immediate posting is required and DBEND mode 2 cannot be used to provide the immediate posting.
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 identi er (logid ) into the database root le. The log identi er can be associated with an existing log le, in which case you can begin with step 6 below if you know the log identi er and password.
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 (include LG) :ALTUSER username;CAP=capability list (include LG) For example: :NEWACCT CAPE,RICK;CAP=LG,AM,AL,GL,SF,ND,IA,BA :NEWUSER ILSA;CAP=LG,AL,GL,SF,ND,IA,BA Refer to the MPE/iX Commands Reference Manual for information on other MPE/iX user logging commands, including these listed here: R
If you are using roll-back recovery, the log le and the database must be in the same volume set. To accomplish this, use the device parameter of the MPE/iX BUILD command and then create the log le in the appropriate group and account. Note numrec numextents initialloc device is the maximum number of logical records. Maximum value allowed is 2,147,483,647. Default is 1023. is the maximum number of disk extents (from 1 to 32, inclusive). Default is 8.
The logid has a maximum of eight characters. Other users can access the log le and records in the same log le by using the logid you acquire and its password. To access the logging system directly through MPE/iX, you must have logging (LG) or operator (OP) capability and supply the identi er and password on the OPENLOG intrinsic.
password AUTO NOAUTO is the password to be associated with the logging identi er. This parameter protects the log le from unauthorized access. Up to eight characters are allowed. performs an automatic CHANGELOG command when the disk log le becomes full. A new log le is automatically created with the same log le name incremented by one in the digit portion; for example, if the current log le is ORDER001, the next le will be ORDER002.
If you use TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END) to backup your database and DBRECOV to perform roll-forward recovery, you must take precautions to synchronize the proper log les with the stored database. Refer to step 8 for more information.
for logging, DBUTIL checks whether a database backup copy has been stored with DBSTORE or TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END). If not, DBUTIL issues a warning message. Because the database is stored after logging has been rst enabled, the DBUTIL warning message can be interpreted as a prompt to store the database.
Note If you plan on using TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END) when the database is open for access, you will not be able to set the DISABLE FOR ACCESS or ENABLE FOR RECOVERY ags for the backup copy. In the event recovery becomes necessary, set these ags immediately after restoring the database from backup.
The following is an example of how to run DBSTORE: :RUN DBSTORE.PUB.SYS WHICH DATABASE? ORDERS DATABASE STORED END OF PROGRAM 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.
consistent state and there is no active transaction in progress. All ongoing transactions, if any, are allowed to be completed before the sync point . The ONLINE=START option allows the sync point at the beginning of a True-Online 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 @.@.
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 les NLOG001 up to NLOG006. When you continue updating the database, log les up to NLOG999 will be automatically created when needed. After that, the log le NLOG001 is automatically created and used as is done today.
recovery, if enabled for roll-forward, need not commence from the beginning of the rst log le. Note If your database is opened exclusively, such as with mode 3 or 7, True-Online backup does not store your database, and reports an error: DATABASE NOT STORED: UNABLE TO STORE SOME DATABASE FILES BASED ON THE SELECTION CRITERIA, NO FILES WERE STORED. (S/R 1713) Unlike DBSTORE, STORE with ONLINE=START or ONLINE=END option allows your database(s) to be open for access when you perform the backup.
Logging Status The DBUTIL >>SHOW command can be used to display the log identi er and the status of the ags 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 log le used during backup. The following example illustrates roll-forward recovery and the commands used to set the logid and ags into the database, as presented in this chapter.
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. Note The displayed bu er speci cations are the default TurboIMAGE/V values. These speci cations or any new ones that you set are displayed for MPE V compatibility, but they are not used by TurboIMAGE/XL which uses a large default value. See chapter 8 or appendix H for more information.
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 ags are set (see the following discussion). At the end of the day, the log process is stopped from the console and the ags are reset for storage of the database backup copy.
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 le. To determine whether or not a log process is running, use the MPE/iX SHOWLOGSTATUS command to determine the log identi ers of active log processes. SHOWLOGSTATUS displays the percentage of records in the log le if the logid output is to disk.
The user issuing the CHANGELOG command must be the creator of the logid . If the user issuing CHANGELOG is not the creator of the logid , either LG or OP capability is required. If the mirror database method (DBRECOV STOP/RESTART) is being used, CHANGELOG makes logging without interruption on the primary system possible.
The following example shows a LISTLOG display. A CHANGELOG is currently taking place on log le ORDER001; and, because the CHANGELOG to ORDER002 is not yet successfully completed, ORDER001 is displayed: :LISTLOG LOGID CREATOR CHANGE AUTO CURRENT LOG FILE MYLOG TAPELOG ORDERLOG DATA.SYS DATA.SYS TST.MKTG NO YES YES NO MY.PUB.SYS TAPE001 ORDER001.MKTG.
Enable recovery of the database. 3. Store a database backup copy (required for roll-forward recovery) with DBSTORE or TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option). Example Example when using DBSTORE: :LOG ORDERLOG,STOP :RUN DBUTIL.PUB.SYS . . . >>DISABLE ORDERS FOR ACCESS Access is Disabled >>ENABLE ORDERS FOR RECOVERY Recovery is Enabled >>EXIT END OF PROGRAM :RUN DBSTORE.PUB.
Logging Results All database modi cations (DBPUTs, DBUPDATEs, and DBDELETEs) are logged; and in modes 1 through 4 calls to DBOPEN, DBCLOSE, DBBEGIN, DBXBEGIN, DBEND, DBXEND, and DBMEMO are logged to the log le. Each DBBEGIN, DBXBEGIN, DBEND, and DBXEND causes a log record to be written to the log le that includes such information as time, date, and user bu er. These log records are used by DBRECOV to identify logical transactions.
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 le. (Refer to \Logging Preparation" earlier in this chapter for roll-forward logging information.
Enabling the Roll-Forward Feature To enable the roll-forward feature, complete the following sequence: 1. Set the logid and build a log le (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.
>>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. >>EXIT END OF PROGRAM In the above example, recovery is enabled and access is disabled. You do not need to change ags.
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. Restart is disabled. >>exit In the above example, you will need to disable the access ag and enable the recovery ag. Several databases can log to the same log le simultaneously because each call to DBOPEN speci es the fully quali ed name of the database.
the root le before backup. When the database is restored from this backup, the SHOW database ALL command of DBUTIL displays this information. 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. Check your backup listings to see when your database was last stored. If time permits, store your damaged database with DBSTORE.
Note If the operator is unsure of the volume identi er, it is displayed on the console when the tape is mounted. If the database creator and the creator of the log identi er are not the same, and if the disk log le and the database are in two separate accounts, follow the steps listed below for recovery to proceed: 1. Assign a maintenance word to the database. 2. Log on as the creator of the log identi er. 3. Fully qualify the database name when issuing the >RECOVER command. 4.
13. Use DBRECOV for roll-forward recovery. The root le contains information about the starting point for recovery. The recovery will start with the log le LOGF005, following the backup (DBQUIESCE log records). 14. You can back up the recovered database using TurboSTORE/iX 7x24 True-Online Backup (with ONLINE=START or ONLINE=END option) to keep recovery time short. Remember the access ag is disabled and recovery is enabled.
DBRECOV Abort Message If DBRECOV aborts before recovery completes, the following information is printed: Abort occurred on database: dbname dbgroup dbaccount Total database open count: #open Current open count: #open Process user is: dbuser dbgroup dbaccount Running program: progname Log file name: log lename Logging ID: logid Log file record number: nnnnnnnn Transaction type: xx Transaction date/time from log record: day, month, dd, year, time Last successful transaction #: nn First log record # of last s
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 les to restore data integrity. Note that ILR is not needed for 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.
Caution In the event of a system failure, do not restart user logging before running DBRECOV. Log records may have been lost due to the system failure. If user logging is resumed without a recovery, the resulting discontinuous log le would cause invalid results in the event of a subsequent recovery. To prevent access to the database after a system failure without recovery, enable the MUSTRECOVER feature when you enable the roll-back feature.
4. Enter the >CONTROL NOSTORE command of DBRECOV to allow recovery to proceed whether or not the DBSTORE ag is set. 5. Enter the following DBRECOV command (where database name is the name of individual databases to be rolled back): >ROLLBACK database name [,database name2,. . . . ,database nameN] 6. Enter all other desired DBRECOV commands (>FILE, >CONTROL with other options except NOSTORE shown above, and >PRINT).
MPE/iX Cleanup Mode and Roll-Back Recovery In the event of a system failure and subsequent start recovery operation, MPE/iX attempts to clean up any user log les that were open at the time of the failure. The cleanup procedure involves writing any records left in the system log le disk bu er to the user log le. Note that for roll-back recovery without this cleanup, transactions are not lost during a start recovery operation because they are not held in the memory bu er.
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 Speci es the conditions for recovery. FILE Sorts the log le by individual users and/or user identi ers, and designates an MPE/iX le as the destination for each user's log records. PRINT Displays information before you actually initiate recovery with the >RUN command. RECOVER Designates the name of a database to be recovered using roll-forward recovery.
The following provides an example of the override: >CONTROL NOSTAMP,STAMP Because STAMP was entered after NOSTAMP, STAMP negates NOSTAMP, so that recovery proceeds with the time-stamp check intact. For the options and form of the >CONTROL command, refer to the discussion of the >CONTROL command of the DBRECOV utility in chapter 8. Note that the >CONTROL command does not specify a database.
PRINT Command The >PRINT command is an option used to display information before actually initiating recovery with the >RUN command. If DBTABLE is speci ed in the >PRINT command, the names of the databases speci ed for recovery by >RECOVER commands are returned. Note that no statistics are returned with the >PRINT DBTABLE command, because none exist before the log le is read. If you need these statistics without actually performing the recovery, use >CONTROL STATS to display this information.
Conditions necessary for the success of the >ROLLBACK command include the following: The database must be accessible to you when running DBRECOV. If the database resides in a group or account di erent from the your logon, the MPE/iX le security must permit the user read and write access to the database les. The log identi er characteristics (name, password, log le name, and device type) must not have been altered since the log le was generated. The database must be enabled for recovery and roll-back.
Recovery Tables The rst 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 le feature is used.
Note 3 4 If you need this table, along with statistics, without actually performing the recovery, use >CONTROL STATS to display this information. The >PRINT DBTABLE command also displays this table, but does not include the statistics; use this command if you only need to list the names of the databases speci ed with >RECOVER commands. The LOGGING SYSTEM table should have only one entry, the log identi er for the log le that was accessed by the recovery system.
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. Making a new database backup copy and starting a new log le from the console with the CHANGELOG command.
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 di erent 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. This system consists of two identical databases on two separate computer systems.
Figure 7-3.
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.
aborted because the RESTART le is purged. The database ags are returned to the same settings as before the recovery process was started. If ABORT fails to abort recovery because of an inconsistent RESTART le, DBRECOV,PURGE can be used to delete the current RESTART le 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.
This is a list of the databases that are in the RESTART le. These database names are speci ed later when either the RESTART or ABORT options are used. The RESTART le 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.
makes it easier to keep the log les grouped with the databases and RESTART le because all the log les can be stored at the same time when recovery is stopped. Use an MPE/iX STORE command with the \@" option (rather than a DBSTORE) to backup all the les on a minimum number of tapes. If it is necessary to restart from a backup, all the necessary les will be together. Using naming conventions makes storing the les to tape much easier. The logging naming conventions should be used.
If the user logon is not the same as the logon when DBRECOV was suspended, the following message is printed: must be logged on as same user and account where DBRECOV was suspended Log on using the same user and account names that were used when DBRECOV was originally suspended, and run DBRECOV again. When the RESTART le is opened, DBRECOV tries to open all databases identi ed in the RESTART le.
The user is then prompted to con rm the restart: CONTINUE WITH RECOVERY (N/Y)? Respond Y or YES to continue, or type N or NO (or press carriage return) to return to the STOP point. If any of the databases cannot be opened during recovery, an MPE/iX le error is returned and DBRECOV RESTART is terminated. When this happens, go back to the previous STOP point and use the databases, log les, and the RESTART le to RESTART recovery.
If the user logon is not the same as the logon when DBRECOV was suspended, the following message is printed: must be logged on as same user and account where DBRECOV was suspended Log on using the same user and account names that were used when DBRECOV was originally suspended, and run DBRECOV again. When the RESTART le is successfully opened, DBRECOV identi es all the databases in the RESTART le, and veri es that they are in RESTART mode.
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. However, if the ABORT option fails, the DBRECOV,PURGE command can be used as a last resort to delete the useless RESTART le before restarting with a backup of the databases and RESTART le of a previous STOP point. Caution When using PURGE on a RESTART le, RESTART must be done from the previous STOP point. :RUN DBRECOV.PUB.
Occasionally, DBRECOV can terminate abnormally due to a bad log le in the log set or a system failure. If the user cannot RESTART recovery from the previous STOP point because of a damaged or missing log le, PURGE the current RESTART le and begin the mirror recovery process again. Listed below are the four basic steps used to reestablish the mirror database system after an abnormal termination of DBRECOV: 1. Disable user access on the primary system and store the databases from the primary system. 2.
One disadvantage of having several small log les is in the application of STOP-RESTART. DBRECOV prompts to CON[TINUE] or STOP recovery if it is between log les in a log set, and it cannot nd the next log le. Therefore, the prompts to CON[TINUE] or STOP are more frequent when there are several small log les. An alternate logging option would be to set the log le size very large and just manually change to the next log le by issuing the CHANGELOG command.
8 Using the Database Utilities The TurboIMAGE/XL utilities create and initialize the database les 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.
Supported Structural Changes Using DBUNLOAD and DBLOAD Any of the following schema changes, alone or combined, always result in a successfully transformed database: Adding, changing, or deleting passwords and user class numbers. Changing a data item or data set name and all references to it. Changing data item or data set read and write class lists. Adding new data item de nitions. Removing or changing de nitions of unreferenced data items. Increasing data set capacities.
In some circumstances, the load completes, but data is lost. For example, data is lost if the capacity of a data set is reduced in the new database to less than the number of data set entries on the tape. If this is not desired, increase the capacity of the data base and restart the DBLOAD process (refer to \Restructuring the Database with TurboIMAGE/XL Utilities" earlier in this chapter.) Summary of Utility Routines Here is a brief summary of the utilities, their commands, and their functions. Table 8-1.
Table 8-1. TurboIMAGE/XL Utilities (continued) Program DBUTIL (continued) 8-4 Commands ACTIVATE Function Prepares a database-access le which is used to access a remote database. ADDINDEX Adds the associated B-Tree index. CREATE Creates and initializes a database le for each data set. DEACTIVATE Deactivates a database-access le which is used to access a remote database. DETACH Detaches the database from the attached DBEnvironment(s).
Table 8-1. TurboIMAGE/XL Utilities (continued) Program Commands RELEASE Function Suspends MPE/iX security provisions for the root le, data sets, and any third-party indexes. SECURE Restores MPE/iX security provisions suspended by RELEASE. SET Changes or removes the maintenance word or password, stores log identi er and password into root le, speci es the setting for the critical item update (CIUPDATE) option, and changes the native language of the database.
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 le. 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.
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[= lename] [;DEV= device] ] 2 :RUN DBLOAD.PUB.SYS . . . WHICH DATABASE? database name [/maint word] 3 4 5 6 WARNING: The LANGUAGE of the database is DIFFERENT from the language found on the DBLOAD MEDIA. Continue DBLOAD operation? (Y/N): DATA SET m: x ENTRIES . . .
DBLOAD DBLOAD requires exclusive access to the database. If the database is already open to any other process, DBLOAD terminates and prints the message: DATABASE IN USE Parameters lename is the name (up to 8 characters) that replaces DBLOAD in the mount request at the operator's console. device is the device class name of the device from which the data entries are to be loaded. Tape is the only supported device class.
DBLOAD 4 5 After each data set is copied, DBLOAD prints a message on the list le device which includes the data set number and the number of entries copied. When the end of a volume is encountered, DBLOAD prints a message (where z is the logical device number of the unit, XXXX is the database name, and n is the volume number).
DBLOAD Note For optimum performance, DBLOAD uses deferred output when it adds entries to a database. With deferred output, data and structural information cannot be written back to disk each time DBPUT returns to the DBLOAD program. As a result, the database is not considered to be logically or structurally complete on disk until the DBLOAD is complete.
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 le containing records of all database modi cations 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.
DBRECOV Example 2 Roll-forward recovery of multiple databases ORDERS and RETAIL. PART and SALES are lenames , 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.
DBRECOV Text Reference Chapter 7 Using the Database Utilities 8-13
DBRECOV >CONTROL Used to control various options that a ect 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.
>CONTROL DBRECOV If additional databases are speci ed for simultaneous recovery, they are all governed by the same >CONTROL options. In the speci cations below, default options are shown in brackets [ ]. The default conditions for STOPTIME, ERRORS, and EOF are included with their descriptions. Parameters is the time stamp in the database root le. It is compared with the time stamp in each DBOPEN log record in the log le.
>CONTROL ERRORS=nnnn DBRECOV controls the maximum number of non-fatal errors allowed during a job (batch) execution. Should nnnn be exceeded, DBRECOV terminates and sets the job control word to 01 to indicate an error. However, this check does not take e ect until all commands have been parsed and processed. Default condition: ERRORS=0 for batch jobs and ERRORS=30,000 for interactive sessions. The number of errors allowed can be altered by entering a revised ERRORS parameter.
DBRECOV >CONTROL Record Numbers DBRECOV identi es detail records by their record number. Suppressing aborted or unended transactions during recovery with the NOUNEND or NOABORTS options can cause subsequent detail calls to DBPUT to use di erent record numbers. In order to change old record numbers into new ones, DBRECOV uses an internal record table. The record table provides a \before" and \after" location of the record numbers for DBPUT calls.
DBRECOV >EXIT Used to terminate DBRECOV without recovering any databases.
>FILE DBRECOV >FILE Routes log records to individual user les, providing the application program with information about the outcome of recovery; provides a useful tool for auditing previous entries. One le 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 le. Syntax >FILE leref,userref [,rmode,fmode] Parameters leref userref rmode fmode Caution is an MPE/iX le reference: lename [/lockword ] [.group [.account ]].
>FILE DBRECOV 1 2 3 Log records corresponding to the rst unsuccessfully recovered call to DBBEGIN of each transaction block are copied. The sequence of log records associated with the rst unsuccessfully recovered transaction of each transaction block are copied. All log records that could not be recovered are copied. Discussion The >FILE command copies quali ed DBOPEN and DBCLOSE log records to each user's recovery le.
>PRINT DBRECOV >PRINT Prints the names of databases speci ed for recovery (DBTABLE option) or recovery les speci ed (FILETABLE option). Can be used as a check before actually initiating recovery with the >RUN command. 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.
DBRECOV >RECOVER Used to designate the name of a database to be roll-forward recovered; opens database root le, validates logid and password with MPE/iX, and checks the DBSTORE ag. Multiple databases can be roll-forward recovered concurrently if they have all logged to the same log le by entering the >RECOVER command once for each database or as follows: >RECOVER database name, database name Syntax >RECOVER database name[/maint word][.group[.
DBRECOV >RECOVER The >RECOVER command itself does not initiate recovery, but makes several preparatory checks. The recovery system is actually initiated by the >RUN command. Example >RECOVER ORDERS, RETAIL DATABASE ORDERS LAST DBSTORED THURS, SEP 7, 1989, 6:30 PM DATABASE RETAIL LAST DBSTORED MON, SEP 11, 1989, 10:00 PM ORDERS and RETAIL are database names .
DBRECOV >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 de ned by the database creator. This word must be supplied by anyone other than the database creator.
>ROLLBACK DBRECOV The following commands are used with >ROLLBACK: >FILE >PRINT >CONTROL The >FILE command optional parameter rmode is not used with >ROLLBACK. The following >CONTROL options are not applicable with >ROLLBACK: STAMP, NOSTAMP, STORE, NOSTORE, STOPTIME Example >CONTROL NOSTATS >ROLLBACK ORDERS DATABASE ORDERS LAST USED THURS, SEP 7, 1989, 6:00 PM >RUN ORDERS is the database name .
DBRECOV >RUN Initiates recovery-process. The recovery system opens the log le and validates the log identi er before roll-forward recovery or roll-back recovery begins. Syntax >RUN Discussion For recovery to succeed, the log le must be accessible to the database administrator. This means that the database administrator must either be the creator of the log identi er used to create the log le, or know the maintenance word and have system manager (SM) or operator (OP) capability.
>RUN DBRECOV Example 2 Roll-back recovery of database ORDERS. :RUN DBRECOV.PUB.
>RUN 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 2 32 = lename ;DEV=device :FILE DBRESTOR 32 8 93 2 ;REC=recsize ; BUFNOBUF 3 :RUN DBRESTOR.PUB.SYS . . . WHICH DATABASE? database name [/maint word] DATABASE RESTORED END OF PROGRAM 3 4 Parameters lename is a name (up to 8 characters) that replaces DBRESTOR in the mount prompt at the operator's console.
DBRESTOR Console Messages After you supply the database name and DBRESTOR opens the le speci ed by lename , a message is displayed on the system console. A tape must be mounted on the appropriate unit and identi ed 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. The operator must mount the next volume in the sequence.
DBSTORE Stores the database root le and all data sets to a tape in a format compatible with backup les created by the MPE STORE and SYSGEN commands. DBSTORE di ers from these commands in that it handles only TurboIMAGE/XL databases. Operation 1 2 2 :FILE DBSTORE = lename 32 ;DEV=device 32 ;REC=recsize 3 BUF ; NOBUF :RUN DBSTORE.PUB.SYS [;INFO=" MPE STORE options"] . . .
DBSTORE Operation Discussion 1 2 3 4 The optional le equation that speci es 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 bu ered. The default device class is TAPE. Initiates execution of the DBSTORE program in the PUB group of the SYS account. The MPE STORE options are parameters that can be passed to the STORE/RESTORE process.
DBSTORE le, and the log les that were processed since the last successful RESTART can be done with an MPE STORE command. DBRECOV STOP-RESTART places a time stamp in the RESTART le and in the database to identify which RESTART le to apply to which database. If naming conventions have been followed, an MPE STORE @ command can be used to store all the necessary les and database(s). If DBSTORE is used, the user must remember to use an MPE STORE command to store the RESTART le and the log les.
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 les including TC le, third-party indexing les, jumbo data set les, and B-Tree index les are also stored along with it. The DBSTORE ag and time stamp are also set before storing the database. You can restore it using the MPE RESTORE command.
DBUNLOAD Copies the data entries from each data set to specially formatted tape volumes. Operation 1 2 [:FILE DBUNLOAD[= lename] [;DEV=device] ] :RUN DBUNLOAD.PUB.SYS . . . 3 ,CHAINED ,SERIAL WHICH.DATA BASE? database name [/maint word] . . DATA SET m: x ENTRIES EXPECTED, x ENTRIES PROCESSED 4 5 END OF VOLUME n, y WRITE ERRORS RECOVERED SAVE VOLUME ON LOGICAL DEVICE z AS n DATABASE UNLOADED 6 END OF PROGRAM (Refer to \Operation Discussion" later in this section.
DBUNLOAD 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 le. 4. Execute the DBUTIL >>CREATE command. 5. Reload the data entries from the volumes created by DBUNLOAD. The data sets are unloaded in the order that they were de ned in the original schema.
DBUNLOAD Operation Discussion 1 2 3 4 An optional le equation that speci es the device class name for the device on which the data entries are to be copied. The default is device class TAPE. Initiates execution of the DBUNLOAD program in the PUB group of the SYS account. In session mode, DBUNLOAD 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.
DBUNLOAD 6 After the data sets have been successfully copied, DBUNLOAD issues a completion message. DATABASE UNLOADED END OF PROGRAM Console Messages After you supply the database name and DBUNLOAD opens the output le, a message is displayed on the system console. A tape must be mounted on the appropriate unit and identi ed through an operator reply. Refer to the Volume Management Reference Manual for instructions about console interaction.
DBUNLOAD Example (Job Mode) :JOB MGR.ACCOUNTA :RUN DBUNLOAD.PUB.SYS ORDERS :EOJ Initiate job. Initiate execution of DBUNLOAD. Specify database name. Initiate end of job. Because the user in this example is the database creator, a maintenance word is not provided. The DBUNLOAD program is executed in chained mode by default because no entry is speci ed.
DBUNLOAD Figure 8-1.
DBUTIL The DBUTIL program performs several di erent functions according to the command you enter. Each DBUTIL command is described separately on the following pages. Operation 1 2 :RUN DBUTIL.PUB.SYS >>command Operation Discussion 1 2 Initiates execution of the DBUTIL program in the PUB group of the SYS account. Prompts for a DBUTIL >>command .
>>ACTIVATE DBUTIL >>ACTIVATE Activates the database-access le 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 le before accessing a remote database residing on another HP 3000.
>>ACTIVATE DBUTIL Example :RUN DBUTIL.PUB.SYS . . . >>ACT ORDDBA Verification follows FILE command: Looks DSLINE command: Looks HELLO command: Looks HELLO command: Looks ACTIVATED >> Initiate DBUTIL execution. Enter abbreviated form of ACTIVATE command and database-access le name. good good good good DBUTIL checks the structure of the le named ORDDBA for correct format and activates the le. You will not be able to edit the le unless you deactivate it using the DBUTIL >>DEACTIVATE command.
>>ADDINDEX DBUTIL >>ADDINDEX The ADDINDEX command updates the root le, and adds the associated B-Tree index le. When using the ALL option and there is no master dataset, a warning is generated, but the command is considered to be successful. Syntax 2 3 2 3 >>ADDI NDEX database name /maintword FOR 8 < ALL : 9 = setnamelist ; setnumlist For example: >>ADDINDEX ORDERS FOR ALL where ORDERS is the database name .
DBUTIL >>CREATE Creates and initializes a le for each data set in the database. Once the Schema Processor has created the root le, the database creator must build a le 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 le in the same logon group as the root le, on the device classes speci ed in the schema. The data set names are created by appending two digits to the root le name.
>>CREATE DBUTIL Example (Job Mode) :JOB MGR.ACCOUNTA :RUN DBUTIL.PUB.SYS CREATE ORDERS EXIT :EOJ Initiate job. Initiate DBUTIL execution. Enter >>CREATE command and database name. Terminate DBUTIL. Terminate job. After the data les are created and initialized, DBUTIL prints the following message on the list le device: DATABASE ORDERS HAS BEEN CREATED Note >>CREATE will fail if the native language de ned for the database is not supported at the system level.
DBUTIL >>DEACTIVATE Deactivates the database-access le to allow modi cations to the le or to disallow remote database access. This command is used before you change the contents of the database-access le. (Refer to chapter 9 for more information about accessing remote databases.) If DBUTIL successfully deactivates the le, it prints a con rmation message on the list le device. Syntax >>DE[ACTIVATE] database-access le name For example: DEACTIVATE ORDDBA where ORDDBA is the database-access le name .
>>DETACH DBUTIL >>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 di erent account or di erent group, then issue a DETACH command for the copied database, you will get an error stating that the detach failed from dbename.group.account (ATCERR 32052).
DBUTIL >>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 . Parameters database name is the name of a TurboIMAGE/XL database root le created in the current session or job's account and logon group.
>>DISABLE DBUTIL MUSTRECOVER PREFETCH RECOVERY ROLLBACK disables the MUSTRECOVER option for the database. Logging is not a ected by disabling MUSTRECOVER. If the database needs recovery when you disable MUSTRECOVER, you are prompted to con rm the DISABLE command. If you respond to continue, the consistency of the database cannot be guaranteed. To ensure database consistency, respond with N, recover the database, and then disable MUSTRECOVER after recovering the database.
DBUTIL >>DROPINDEX The DROPINDEX command drops the associated B-Tree index le and updates the root le. When using the ALL option and there is no master dataset, a warning is generated, but the command is considered to be successful. Syntax 2 3 2 3 >>DROPI NDEX database name /maintword FOR 8 < ALL : 9 = setnamelist ; setnumlist For example: >>DROPINDEX ORDERS FOR 2 where ORDERS is the database name and 2 is set# 2.
>>ENABLE DBUTIL >>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.
>>ENABLE HWMPUT ILR INDEXING LOGGING MUSTRECOVER PREFETCH RECOVERY ROLLBACK DBUTIL enables DBPUT action of placing entries at the high-water mark rst, instead of at the delete chain head. enables the Intrinsic Level Recovery facility. TurboIMAGE/XL maintains structural integrity without ILR enabled. enables third-party indexing (TPI) for the database if not already done by the third-party software when con guring the database for TPI.
>>ERASE DBUTIL >>ERASE Reinitializes all data sets in the database to their empty condition and resets all ags except the access, PREFETCH, and recovery ags (refer to the discussion of the DBUTIL >>ENABLE command earlier in this chapter). The data sets remain as catalogued MPE/iX les. To execute DBUTIL to reinitialize the data sets, you must be the database creator or supply the correct maintenance word.
DBUTIL >>EXIT Terminates DBUTIL execution. Syntax >>E[XIT] Example >>CREATE ORDERS Database ORDERS has been CREATED Create a database. >>EXIT If no other DBUTIL functions are to be performed, terminate DBUTIL with >>EXIT command.
>>HELP DBUTIL >>HELP Displays each of the DBUTIL commands. >>H[ELP] [commandname] Parameter commandname is the name of a speci c 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.
DBUTIL >>MOVE Moves TurboIMAGE/XL les across devices within the same volume set. Syntax >>M[OVE] TurboIMAGE/XL le name TO device For example: MOVE ORDERS05 to DISC2 where ORDERS05 is the le name and DISC2 is a device . Parameters le name device is a TurboIMAGE/XL root le, data set, or ILR le. Enter the le name only; no group/account speci cation is allowed. The user must be the creator of the le.
>>MOVE DBUTIL The MOVE command does not allow a B-Tree index (\.idx") le to be moved. Example >>MOVE ORDERS05 to 3 Database last stored on FRI, SEP 22, 1989, 8:32 PM Database has been modified since last store date. The database should be backed up before doing a MOVE operation. Do you still want to continue the MOVE operation (Y/N)? Y Starting file copy ... ... file copy completed.
DBUTIL >>PURGE Purges the root le 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 les regardless of third-party indexing being enabled or disabled. Purging removes the les 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.
>>PURGE DBUTIL Message Meaning No root file, >>PURGE operation proceeding DBUTIL was unable to locate the root le, but will attempt to purge data set, if any. Data set XXXXk has been purged DBUTIL successfully purged the root le 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 de ned for the database (n) .
DBUTIL >>REBUILDINDEX REBUILDINDEX rebuilds the B-Tree index le for a speci ed dataset that should have an index le. 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 le built by REBUILDINDEX has the Native Language Support language speci ed to match the language of the database, if the key is a text (X or U) data type.
>>REDO DBUTIL >>REDO Redo the previous command or the previous n th 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 is the backwards count of the command being repeated.
DBUTIL >>RELEASE Suspends le system security provisions for the database root le and data sets, allowing access to the database from other groups and accounts. If you use third-party indexing, the >>RELEASE command suspends the le system security provisions for any existing index les. 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.
>>SECURE DBUTIL >>SECURE Restores security provisions that were released by a >>RELEASE command for the database root le and data sets. If you use third-party indexing, the >>SECURE command restores the security provisions for any existing index les. 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.
DBUTIL >>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 identi er into the root le, modi es access class passwords, sets a subsystem ag, and sets the critical item update (CIUPDATE) option.
DBUTIL MAINT SUBSYSTEMS PASSWORD LANGUAGE Note CIUPDATE >>SET password speci ed in the GETLOG command before it checks the validity of the log identi er. Entry of the correct logid password causes the valid log identi er to be stored in the root le and used whenever the logging capability is enabled. However, if the log identi er is left blank, it is removed from the database. sets the maintenance word for the database. The maintenance word is the new maintenance word for the database.
>>SET DBUTIL ALLOWED ALLOWED is now the default setting. It was DISALLOWED in releases prior to C.07.00. Note ON BTREEMODE1 WILDCARD Note indicates that programmatic enabling of the option is possible through a call to DBCONTROL mode 5, but programs that do not make this call are prevented from using critical item update on this database. Programs that enable the option do so temporarily for the duration of the process but can subsequently disable it through a call to DBCONTROL mode 6.
>>SET DBUTIL Example 1 :RUN DBUTIL.PUB.SYS . . . >>SET ORDERS MAINT Maintenance word changed >> Initiate DBUTIL execution. Remove current maintenance word. Example 2 :RUN DBUTIL.PUB.SYS . . . >>SET ORDERS CIUPDATE=ON CIUPDATE is ON. Initiate DBUTIL execution. Indicates that processes can update the values of detail data set search or sort items in the ORDERS database without a need to do DBCONTROL mode 5. DBUTIL con rms the setting. Example 3 :RUN DBUTIL.PUB.SYS . . .
DBUTIL >>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 identi er and ags, the current bu er speci cations, and the setting for the critical item update option. Displays the capacity expansion information for the database and the data sets.
DBUTIL >>SHOW 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.
>>SHOW SUBSYSTEMS USERS OFFLINE DBUTIL 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. displays a list of the processes that have the database open with the program le name and other information. (Refer to examples below.) requests that the information be listed on the line printer. The formal designator for the list le is DBUTLIST.
>>SHOW DBUTIL Example (Show All) . . . >>SHOW ORDERS ALL For database ORDERS MAINTENANCE WORD: Display all information for ORDERS database. 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. Restart is disabled. Database last stored using True-Online Backup and logfile NLOG001 on WED, MAR 26, 1997, 8:07 AM.
>>SHOW DBUTIL Example Discussion The listing above indicates that the current bu er speci cations provide for 50 bu ers to be allocated when there are between 1 and 120 concurrent users of the database. On TurboIMAGE/XL the bu er speci cations remain xed, so the information shown in the above listing is useful only for databases that will be migrated to an MPE V system. The list above also shows that the database is enabled for roll-forward recovery, logging, MUSTRECOVER, and user access.
>>SHOW DBUTIL Example (Show Capacity) . . . >>SHOW ORDERS CAPACITY Data Set Name Type No.
>>SHOW DBUTIL Format of Show Indices The following example lists the data set names, type, and whether they are indexed. Example (Show Indices) >>SHOW ORDERS INDICES For database ORDERS Data Set Name Type Indexed? DATE-MASTER CUSTOMER PRODUCT SUP-MASTER A M M M YES YES YES YES 4 indexed datasets >> Format of Show Locks List DBUTIL lists the locking information sequentially by locking level: database locks followed by data set locks, followed by data entry locks.
>>SHOW DBUTIL 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.
>>SHOW DBUTIL Example 2 Discussion 1 2 3 4 Indicates process 22 (program BROWSE, session 118) has requested a lock on the database and yet it cannot continue until existing locks held in the database are released. In this example, the reason for the pending lock is listed on the line below. Indicates process 29 (program INVENTRY, session 115, access path 1) has the INVENTORY data set locked.
>>VERIFY DBUTIL >>VERIFY Reports whether a remote database-access (RDBA) le is activated or deactivated and checks the validity of the RDBA le. Syntax >>V[ERIFY] database-access le name For example: VERIFY ORDDBA where ORDDBA is the database-access le name . Parameter database-access le name is the name of a remote database-access le. Example :RUN DBUTIL.PUB.SYS . . . >>VERIFY ORDDBA Database-access file ORDDBA is ACTIVATED >> Initiate DBUTIL execution.
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 con gured 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.
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 le. In all three cases, a local program accesses a remote database and the data is passed across the communication line.
remote les is given in the NS3000/XL User/Programmer Reference Manual. Figure 9-3 contains a diagram of method 2. Figure 9-3. Using Method 2 If you want to access more than one remotely located database with an application program, you must enter one FILE equation for each remote database. To terminate execution perform the following steps: 1. Close the database. 2. Log o (REMOTE BYE). 3. Close the communication line.
Figure 9-4. Using Method 3 Using the database-access le, only one database can be accessed using each database-access le 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 le name, the remote session is established and the remote database is opened. Then other TurboIMAGE/XL intrinsics can perform desired operations on the database.
Creating a Database-Access File The content of the database-access le should be created in the format shown below. Syntax Record 1 Record 2 FILE dbname1 =dbname2 :nodename Record 3 lusername.lacctname [,lgroupname ]=HELLO rusername [/rup asw ] .racctname [/rapasw ][,rgroupname [/rgpasw ]] . . . (See MPE/iX commands document for additional parameters.) Same format as record 3. Speci es other \user.account,group" identi cation. Record .. 4 . Record n DSLINE nodename [; . . .
racctname rapasw rgroupname rgpasw 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.) is the password assigned to racctname . (Optional parameter.) is the name of the logon group on the remote HP 3000. It follows the same rules as lgroupname . An at-sign (@) can be used to indicate rgroupname is the same as lgroupname . (Optional parameter.
Example Record 1 Record 2 Record 3 Record 4 Record 5 End of le FILE ORDERS=ORDERS:NODEX DSLINE NODEX USERA.ACCTA,GROUPA=HELLO USERB.ACCTA,GROUPB @ .ACCTA,GROUPA=HELLO USERA.ACCTA,GROUPA USERB.ACCTB,@ =HELLO USERB.ACCTX,@ If a user logs on with the logon identi cation indicated in the rst column below, TurboIMAGE/XL uses the corresponding USER.ACCT,GROUP identi cation in the second column to establish communication with the remote system. Logon Identi cation Remote Identi cation User1 USERA.
Activating a Database-Access File After you have constructed a database-access le, you must use the DBUTIL utility program to activate the le. 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 . . .
Deactivating a Database-Access File In order to deactivate the database-access le, you use the DEACTIVATE command of the DBUTIL utility program. Complete syntax for this program is given in chapter 8. Here is a summary of the operating instructions: :RUN DBUTIL.PUB.SYS . . . >>DEACTIVATE database-access le name DEACTIVATED >>EXIT You can do this if you want to edit the content of the database-access le or to prevent access through this le to the remote database.
1 :HELLO MEMBER1.PAYACCT . . . 2 :EDITOR HP32201A.00.00 EDIT/3000 FRI, SEP 6, 1991, 3:30 PM (C) HEWLETT-PACKARD CO. 1985 3 /ADD 4 /KEEP ORDDBA,UNN /END 5 :RUN DBUTIL.PUB.SYS >>ACTIVATE ORDDBA Verification follows: FILE command: Looks DSLINE command: Looks HELLO command: Looks HELLO command: Looks ACTIVATED >>EXIT 1 2 3 4 5 FILE ORDERS=ORDERS:NODEX DSLINE NODEX MEMBER1.PAYACCT=HELLO MEMBER1.PAYACCT MEMBER2.PAYACCT=HELLO @.PAYACCT // good good good good END OF PROGRAM Figure 9-5.
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. 1 :HELLO. MEMBER2.PAYACCT . . 2 :RUN APPLICAN 3 HP3000 / MPE/iX G.00.00 FRI SEP 6, 1991, 3:55 PM ENVIRONMENT 1: ELECTRA.DOC.ITG 4 WELCOME TO SYSTEM B. . . . CPU=2. CONNECT=1. FRI, SEP 6, 1991, 3:59 PM ENVIRONMENT 1: ELECTRA.DOC.ITG CLOSED 5 :BYE Figure 9-6.
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 le name.
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 e cient access to the database content. This chapter describes these structures and techniques to give you an overview of the way TurboIMAGE/XL works. 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.
Media Records TurboIMAGE/XL transfers information to and from a storage location on disk in 4096-byte pages using the system storage manager. Access to the data in memory is synchronized through blocks of media records. A media record consists of both a data entry and its pointers or a null record if no data entry is present. Media Records of Detail Data Sets For each detail entry, the media record consists of the data entry itself preceded by all of its related data chain pointer pairs.
Figure 10-3 illustrates a media record for a secondary entry of a master data set with two paths de ned. 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 speci ed 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 rst 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 bidirectionally linking the secondary entries of the synonym chain to each other. As with detail chains, the rst member of this chain of secondary entries contains a zero backward pointer, and the last member of the chain contains a zero forward pointer. Blocks and Bit Maps Each group of media records involved in a single MPE le record is a block.
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. The capacity parameters are: maximum capacity is a required parameter and is a maximum number of entries the data set can contain.
For new databases, the expansion parameters for data sets can be speci ed using the CAPACITY statement of DBSCHEMA as follows: 3 ,initial capacity 2 CAPACITY: 3 ; maximum capacity (blocking factor) 2 ,increment C: To specify the expansion parameters for data sets of existing databases, use DBChange Plus, or other third-party tools which support this feature.
1. If the primary address in the original area is not occupied, the new entry resides there. The new entry also becomes a synonym chain head with a count of one. 2. If the primary address is occupied by another primary entry, TurboIMAGE/XL scans a few blocks (quick search) in the close proximity of the primary address to nd an unoccupied address (empty record). If found, the new entry resides at this secondary address in the original area.
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. This is acceptable for the low-end machines but not for the high-end and multi-processor machines.
1. 2. 3. 4. 5. 6. 7. M1 D1 D2 and M2 D3 and M3 D4 and M3 D5, M4 and M5 D6, M5 and M6 There are several di erent scenarios when concurrent modi cations 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 modi ed. Other details D2, D3 or D4, and D5 or D6. This is if the dependent master(s) are not being modi ed.
Run-Time TurboIMAGE/XL Control Blocks As mentioned in chapter 4, TurboIMAGE/XL uses control blocks resident in privileged mapped les 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. Although it is not necessary to know the details in order to use the TurboIMAGE/XL procedures, the following descriptions are provided for those who prefer to understand the control blocks and their functions.
Note If you have an existing le with the same name that TurboIMAGE/XL would assign to the permanent mapped le (that is, dbname GB), you will get the following message for status code 09: CANNOT CREATE DBG : MPE ERROR The DBG is derived mostly from the root le and contains global information required by TurboIMAGE/XL intrinsics during run-time. In addition, the DBG contains the lock table which holds user-level locking information.
TURBOGTX le, and it remains on the system even after the system is rebooted. It is used for tracking DMDBX. The QOPEN table is an unnamed global object and is rst created by DBOPEN when the rst writer of any database enabled for user logging opens a database. It is subsequently accessed only by writers of databases enabled for user logging. Each system has only one QOPEN table, and it is purged when all processes accessing it are terminated.
Internal Techniques Although it is not necessary to know the following techniques to use TurboIMAGE/XL, an understanding of them can help you design a more e cient database. Primary Address Calculation TurboIMAGE/XL employs two distinct methods of calculating primary addresses in master data sets. The intent of the rst method is to spread master entries as uniformly as possible throughout the record space of the data le.
Migrating Secondaries In some cases, secondary entries of master data sets are automatically moved to storage locations other than the one originally assigned. This most often occurs when a new master data entry is assigned a primary address occupied by a secondary entry. By de nition, the secondary entry is a synonym to some other primary entry resident at their common primary address. Thus, the new entry represents the beginning of a new synonym chain.
Space Allocation for Detail Data Sets Space allocation for each detail data set is controlled by a free space counter, an end-of- le pointer and a pointer to a delete chain. The end-of- le pointer contains the record address of the highest-numbered entry which has existed so far in the data set. The delete chain pointer contains the record address of the entry which was most recently deleted. When each detail data set is rst created, the end-of- le pointer and delete chain pointer are both zero.
Locking Internals Within the DBG is a large lock area that provides space for the entries described below. Accessor Entries One of these is created for each successful call to DBOPEN (each access path). Although located in the lock area, each accessor entry is the link with which TurboIMAGE/XL controls access to the database. An accessor entry is deleted when DBCLOSE is called for the access path, and the space is reused.
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. XM logs these transactions in its own XM log le.
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.
in a detail data set using DBGET, TurboIMAGE \walks" (traverses) this super-chain. B-Tree Search is the same as B-Tree DBFIND. Super-chain is the sum of all detail data set chains involved in the B-Tree DBFIND. Trailing-@ Search is a B-Tree search where only the characters left of the @ (wildcard character) of the argument are compared to qualify an entry. (For example, \cat@" is a trailing-@ search, but \cat@dog" is not and the result will be the same for both arguments. That is, \dog" will be ignored.
DBUTIL has new commands and options. a. New ADDINDEX, DROPINDEX, and REBUILDINDEX commands (to be used for one, more than one, or all masters) b. The SET command has a new BTREEMODE1 option to set DBFIND mode 1 access ON or OFF for a B-Tree wildcard search for X and U types. The default is OFF. The ON setting allows you to use B-Tree indices for generic search without making application changes. c. The SET command allows you to de ne your own database-wide wildcard character. d.
21 is the same as B-Tree index search using DBFIND mode 1, except it is a faster version and does not return accurate chain counts. Requires a simple argument. 24 is the same as B-Tree index search using DBFIND mode 4, except it is a faster version and does not return accurate chain counts. Requires a structured argument. c. Allows wildcard search, as well as range search (t, >=,\PK", or [ ] for between). d.
External Commands and Utilities Affected The root le, utilities, and intrinsics a ected by the implementation of B-Tree index les include the following: Root le DBSCHEMA DBUTIL DBCONTROL DBFIND DBGET DBINFO DBPUT DBDELETE DBUPDATE Root File The root le version level will be \C4" if at least one master data set has a B-Tree index. If there are no B-Tree indices, the root le version will be \C3" if any jumbo data sets exist, and \C2" otherwise.
Syntax for DROPINDEX 2 3 3 2 DROPI NDEX database name /maintword FOR 8 < ALL : 9 = setnamelist ; setnumlist Syntax for REBUILDINDEX 2 3 2 3 REBUILDI NDEX database name /maintword FOR 8 < ALL : 9 = setnamelist ; setnumlist Parameters setnamelist setnumlist ALL is the list setname [, . . . ] is the list setnum [, . . . ] means all master data sets for the database.
New Syntax for SET ON SET database name /maintword BTREEMODE1= OFF 2 3 2 2 3 3 , WILDCARD= c where c is any printable ASCII character, and the default character is @. The BTREEMODE1 option sets DBFIND mode 1 access ON or OFF for a B-Tree index search for X and U types. The default is OFF, in which case DBFIND mode 1 with the argument containing a wildcard character will continue to work the way it did in releases prior to a release with the B-Tree index feature (C.07.00).
New Syntax for SHOW SHOW has a new option INDEX, alternatively INDEXES or INDICES. 3 2 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. Adding index to set# 1 (#entries Adding index to set# 2 (#entries Adding index to set# 3 (#entries Adding index to set# 4 (#entries Done.
Mode 13 Mode 13 is used to perform functions related to B-Tree index les. 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. Quali er has a structured record containing data set information and directives.
Mode 14 Mode 14 is used to set BTREEMODE1 option ON or OFF for the database and set the wildcard character for the database. The changes will be made in the root le, unlike mode 15 and 16 of DBCONTROL. The caller must be privileged. The result is same as using the SET command with BTREEMODE1 option of DBUTIL. This is the quali er layout (16 halfwords): Element Contents 1 Function code: 0 mode support inquiry (returns \OK" in status, and ignores the rest of the record).
DBFIND Prior to a release with the B-Tree index feature, DBFIND required the caller to specify detail data set on the quali er and a search item in the item parameter. It used that pair of data to determine the master set to search for the exact value in the item parameter. The B-Tree index feature extends DBFIND to allow a master data set as well as the key item in that data set. Also, it allows for searches other than just equality.
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. 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.
#3 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 rst entry, record number of the rst entry in the rst chain is obtained. For masters, the chain count re ects the total number of master entries quali ed, and last entry and rst entry values are zeroes.
DBFIND Structured Argument The structure of the structured argument for DBFIND modes 4 and 24: Bytes Meaning 1-2 Type of generic search.
Pascal/iX Example A Pascal/iX view of the above is: type dbfind_structured_arg_type dbf_type dbf_version dbf_arg1_bytes dbf_arg2_bytes {NOTE: { { { = : : : : $alignment 2$ record pac2; {e.g., "<="} shortint; {must be 0} shortint; shortint; {0 {2 {4 {6 @ @ @ @ 2} 2} 2} 2} arg1 data is variable sized...2 to 256 bytes} and, arg2 data might not even be present. } Still, the following serve to define a record} that can hold the worst case arg1 & arg2... } dbf_arg1_data : packed array [1..
mode4 := 4; item := 'FIRSTNAME;'; dbfind (base, set, mode4, status, item, arg); Example 3 X20 eld, looking for keys that start with \SMITH", using C: char arg arg arg arg arg arg arg arg arg [29]; [0] [1] [2] [3] [4] [5] [6] [7] = = = = = = = = '@'; '@'; (char) (char) (char) (char) (char) (char) 0; 0; 0; 20; 0; 0; /* 2 + 2 + 2 + 2 + 20 + 1 trailing null */ /* /* /* /* /* /* /* /* want a wildcard search */ use an @ as a wildcard character */ upper half of version */ bottom half of version */ upper ha
DBGET DBGET has no changes to the calling sequence. It has the semantic change that chained access modes can be used for both masters and details. For master data sets, DBGET mode 5 or 6 following a B-Tree DBFIND implies the next or previous quali ed record of the master data set. Also, DBGET mode 5 (forward chained read) and mode 6 (backward chained read) may now traverse super-chains for a B-Tree index DBFIND on a detail data set.
Element Contents 1 0 if no B-Tree index exists 2 3-32 1 if B-Tree index exists 1 if attached B-Tree is not damaged or index does not exist For internal use DBPUT, DBDELETE, and DBUPDATE DBPUT and DBDELETE trigger similar operation to the associated B-Tree index le 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 le is done with an FWRITE call.
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.
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 bene t 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.
A Error Messages TurboIMAGE/XL issues three di erent 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.
Schema Processor File Errors Various le 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 le information display on the $STDLIST le. MESSAGE FILE ALREADY EXISTS; UNABLE TO CLOSE le name MEANING ACTION FCLOSE error occurred on speci ed le. Can be caused by duplicate le in group with same name as root le. Change database name or purge le of same name.
MESSAGE UNEXPECTED END-OF-FILE ON le name MEANING ACTION Call to FREAD or FWRITE on speci ed le has yielded unexpected end of le condition. Change database name, or purge le of same name. Or, be sure correct le and le name used. Check MPE FILE commands used. If other cause, consult MPE/iX Intrinsics Reference Manual for similar message. MESSAGE WRITE ERROR ON le name MEANING FWRITE error occurred on the speci ed le. Change database name or purge le of same name.
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 ($). Examine the schema text le to nd any incorrect commands.
MESSAGE SPECIFIED TITLE TOO LONG MEANING Character string in $TITLE or $PAGE command exceeds 104 characters. Examine the schema text le to nd any incorrect commands. Edit the text le, and run the Schema Processor again.
Schema Syntax Errors Database de nition syntax errors can be detected by the Schema Processor. Their existence does not cause termination but does prohibit root le creation. Discovery of one can trigger others which disappear after the rst is corrected. Also, detection of one can preclude detection of others which appear after the rst is corrected. Syntax errors are also added to an error count which, if excessive, will cause Schema Processor termination.
MESSAGE BAD DATABASE NAME OR TERMINATOR MEANING Database name in BEGIN DATABASE statement is not a valid database name beginning with an alphabetic character and having up to 6 alphanumeric characters. Or, the name is not followed by a semicolon (;). Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. ACTION MESSAGE BAD DATA SET TYPE MEANING The data set type designator is not AUTOMATIC (or A), MANUAL (or M), or DETAIL (or D).
MESSAGE BAD PATH COUNT OR TERMINATOR MEANING The path count in the master data set de nition is not an integer from 1 to 16 (for an automatic master), or 0 to 16 (for a manual master). This message can also mean the path count is not followed by a quotation mark ("). Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again.
MESSAGE BAD SUBITEM LENGTH OR TERMINATOR MEANING Subitem length for data item de ned in schema item is not an integer from 1 to 255. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. ACTION MESSAGE BAD TERMINATOR-';' EXPECTED MEANING ACTION Password or capacity was not followed by a semicolon. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again.
MESSAGE BLANKS WILL BE REMOVED MEANING ACTION A blank ' ' character in a password has been suppressed before writing the password to the root le. Edit and remove. MESSAGE 'CAPACITY:' EXPECTED MEANING CAPACITY statement must follow entry de nition in the de nition of data sets in the set part of schema. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again.
MESSAGE DUPLICATE ITEM SPECIFIED MEANING The same data item name was used more than once in the entry de nition of data sets. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. ACTION MESSAGE DUPLICATE SET NAME MEANING The same data set name was used to de ne more than one data set in the set part of schema. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again.
MESSAGE ILLEGAL CHARACTER IN PASSWORD MEANING ACTION The password cannot contain a period, semicolon, slash, or carriage return. Edit and remove. MESSAGE ILLEGAL ITEM NAME OR TERMINATOR MEANING The data item name does not conform to naming rules. (Names must start with a letter and can have up to 16 alphanumeric characters including + 0 ? / # $ & * @ ). Or if in the item part, it is not followed by a comma. Examine the schema text le to nd the error.
MESSAGE INITIAL CAPACITY = MAXIMUM CAPACITY, NO EXPANSION MEANING ACTION The initial capacity is equal to the maximum capacity, no dynamic expansion for the data set. Warning only. MESSAGE INITIAL CAPACITY EXCEEDS MAXIMUM CAPACITY MEANING ACTION The initial capacity de ned is greater than maximum capacity. Either change the maximum capacity or the initial capacity. Initial capacity must be less than or equal to the maximum capacity.
MESSAGE MASTER DATA SET LACKS EXPECTED DETAIL(S) MEANING Master data set was de ned with a non-zero data count, but the number of detail search items which back-referenced the master is less than the value of the path count. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. ACTION MESSAGE MASTER DATA SET LACKS KEY ITEM MEANING A master data set was de ned without de ning one of the data items in the set as a key item.
MESSAGE 'PASSWORDS:' NOT FOUND MEANING PASSWORDS statement must immediately follow the BEGIN DATABASE statement in schema. If it does not, DBSCHEMA terminates execution. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. ACTION MESSAGE PASSWORD TOO LONG MEANING ACTION A password de ned in data schema cannot exceed eight characters. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again.
MESSAGE SEARCH AND KEY ITEMS NOT OF SAME LENGTH MEANING Master key item must be the same length as any related detail data set search item. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. ACTION MESSAGE SEARCH AND KEY ITEMS NOT OF SAME TYPE MEANING Master key item must be of the same type as any related detail data set search item. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again.
MESSAGE TOO MANY DATA ITEMS MEANING ACTION The item part of schema cannot have more than 1023 data item names. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. MESSAGE TOO MANY DATA SETS MEANING ACTION The database cannot have more than 199 data sets. Examine the schema text le to nd the error. Edit the text le, and run the Schema Processor again. MESSAGE TOO MANY ERRORS MEANING ACTION The speci ed or default number of errors has been exceeded.
Library Procedure Error Messages The success of each call to a TurboIMAGE/XL library procedure is re ected upon return to the user by the condition code and the value of the return status in the rst 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.
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 le 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.
Library Procedure File System and Memory Management For return status values 01 through 06, the second element of the calling program's status area is the data set number for which le error occurred (zero indicates root le). The third element is the MPE failure code returned by the FCHECK intrinsic. Refer to MPE documentation for meaning of this code. -1 MESSAGE MPE file error nn returned by FOPEN on root file or data set nn MEANING For DBOPEN, error can indicate that database could not be opened.
-3 MESSAGE MEANING ACTION -4 MESSAGE MEANING ACTION -5 -7 -8 This is an exceptional error (as 02 above) and is returned by DBOPEN, DBFIND, DBGET, DBUPDATE, DBPUT, DBDELETE. Notify system manager of error. MPE file error nn returned by FREADLABEL on root file or data set nn This is an exceptional error (as 02 above) and is returned by DBOPEN, DBINFO, DBFIND, DBGET, DBUPDATE, DBPUT, DBDELETE, and DBUNLOCK. Notify system manager of error.
-9 MESSAGE Cannot create control block name : MPE error %nn MEANING This is an exceptional error returned when DBOPEN fails to call HPFOPEN to create a control block. Notify system manager or HP support personnel. ACTION -10 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 le. Notify system manager or HP support personnel.
Library Procedure Calling Errors -11 MESSAGE Bad base reference MEANING For DBOPEN, the rst two characters in base are not blank, or database name contains special characters other than period. For all other procedures, either rst 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. Check application program's procedure call. Correct error in call.
-14 MESSAGE Illegal intrinsic in current access mode MEANING DBPUT and DBDELETE cannot be used with DBOPEN mode 2, 5, 6, 7, or 8. DBUPDATE cannot be used with DBOPEN mode 5, 6, 7, or 8. Modify program or notify current user that operation cannot be performed. ACTION -15 MESSAGE Setup for RDBA failed MEANING DBOPEN will issue a DSLINE command and a REMOTE HELLO on behalf of the user if a DBA le is being used for RDBA. One of these commands failed.
-21 MESSAGE MEANING -22 -23 -30 (See above for additional status code 021 messages.) 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. ACTION An erroneous data item name can arise when a terminating semicolon or blank is omitted. Check application program's procedure call. Correct error in call.
-31 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. Correct mode in procedure call. ACTION -32 MESSAGE Unobtainable access mode; AOPTIONS requested: n , granted: m MEANING For DBOPEN, root le cannot be opened with FOPEN using the access options (AOPTIONS) requested for the speci ed access mode.
-51 -52 -53 -60 -61 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. ACTION It will never occur for numeric lists. Shorten list array contents. If necessary, change to numeric list. MESSAGE Bad list or bad item MEANING For DBGET, DBUPDATE, or DBPUT, the list parameter is invalid.
-80 -81 MESSAGE Output Deferred not allowed with ILR enabled MEANING ACTION DBCONTROL (mode 1) was used to request deferred output, but deferred output cannot be used when ILR is enabled. Deferred output is not initiated. Do not use deferred output; or run DBUTIL and disable ILR. MESSAGE Output Deferred not allowed with ROLLBACK enabled MEANING DBCONTROL (mode 1) was used to request deferred output, but deferred output cannot be used when ROLLBACK is enabled. Deferred output is not initiated.
-91 MESSAGE Bad root modification level MEANING For DBOPEN, the software version of the DBOPEN procedure is incompatible with version of Schema Processor which created root le. Check with system manager that you have correct TurboIMAGE/XL software. If necessary ask HP support personnel about conversion. ACTION -92 -93 -94 MESSAGE Database not created MEANING ACTION For DBOPEN, the referenced database has not yet been created and initialized by the DBUTIL CREATE command.
-97 -98 -99 MESSAGE Database bad - ILR enable in process (enable again) MEANING ACTION DBOPEN attempted to open a database but prior disable of ILR was not complete. Run DBUTIL with ENABLE command to enable ILR. MESSAGE Database bad - ILR disable in process (disable again) MEANING ACTION DBOPEN attempted to open a database, but prior disable of ILR was not complete. Run DBUTIL with DISABLE command to disable ILR. MESSAGE UNSUPPORTED FEATURE.
-103 MESSAGE Remote 3000 stack too small MEANING Command Interpreter on remote HP 3000 cannot obtain stack space necessary to execute a DBOPEN or DBLOCK. Ask system manager of remote system to increase available stack size. ACTION -104 -105 -106 MESSAGE Remote 3000 does not support TurboIMAGE/XL MEANING ACTION This is an exceptional error and is returned by DBOPEN on the remote system. Notify system manager of problem. MESSAGE Remote 3000 cannot create TurboIMAGE control block.
-110 -111 -112 MESSAGE MPE OPENLOG intrinsic failure MEANING ACTION 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. Notify system manager or HP support personnel.
-121 -123 -124 -125 MESSAGE Descriptor count error MEANING ACTION DBLOCK detected an error in the descriptor count ( rst element of quali er array) in locking mode 5 or 6. Count must be a positive integer. MESSAGE Illegal relop in a descriptor MEANING ACTION DBLOCK encountered a relop eld containing characters other than >=, <=, =t or t=. Check contents of quali er array. MESSAGE Descriptor too short.
-129 -130 -131 -132 -133 -134 -135 MESSAGE P-type item longer than P28 specified MEANING ACTION DBLOCK does not allow P-type data items longer than 28 in lock descriptors (27 digits plus sign). Modify locking strategy to lock on a di erent item. MESSAGE Illegal digit in a P-type value MEANING ACTION DBLOCK has encountered a P-type value in a lock descriptor with an invalid packed decimal digit. Check quali er array contents to determine why data is invalid.
-136 -137 -139 MESSAGE Descriptor list exceeds 4094 bytes MEANING ACTION DBLOCK allows a maximum length of 4094 bytes for lock descriptor lists (quali er array). Change quali er array contents so lock descriptor list is shorter. MESSAGE USER ABOUT TO WAIT FOR SELF. MEANING ACTION There is a potential for an imminent deadlock situation. Examine the locking scheme in your application; may need to call DBUNLOCK and then DBLOCK. MESSAGE Invalid number of base IDs.
-143 MESSAGE Logging must be enabled or disabled for all MDBX databases. MEANING All databases involved in a multiple database transaction (MDBX) must have synchronized logging facilities. Ask your database administrator or application programmer to synchronize the logging facilities. ACTION -144 MESSAGE ACTION -145 -147 -148 Roll-back recovery must be enabled or disabled for all MDBX databases.
-151 MESSAGE Text length greater than 512 bytes MEANING Text provided to DBBEGIN, DBEND, DBMEMO, DBXBEGIN, DBXEND, DBXUNDO is too long. Modify program. ACTION -152 -153 -160 MESSAGE DBCLOSE called while a transaction is in process; DBBEGIN called while a transaction is in process; DBXBEGIN called while a transaction is in progress MEANING ACTION A transaction is in process. Call DBEND before DBCLOSE. Call DBEND before the next DBBEGIN. Call DBXEND before the next DBXBEGIN.
-168 -169 -170 -172 -173 -174 -175 MESSAGE Cannot attach n to MPE XL XM: file system error nn MEANING ACTION Data set n could not be attached to the MPE transaction recovery mechanism. MPE intrinsic FILEINFO or FLABELINFO failed. Notify HP support personnel. MESSAGE Invalid mode for XM attach options MEANING ACTION An internal error has occurred. Notify HP support personnel.
-176 -177 MESSAGE Cannot detach n from MPE XL XM: XM error nn . MEANING ACTION The data set n could not be detached from the transaction recovery mechanism. nn is the MPE error number returned. Notify HP support personnel. MESSAGE MPE log file is not in the same volume set as the database. MEANING MPE transaction recovery requires that the user log le must reside in the same volume set as the database. Build the MPE user log le in same volume set as database.
-181 MESSAGE ILR log file invalid - internal group name does not match root file MEANING DBUTIL DISABLE command or call to DBOPEN attempted to open ILR log le, but group names do not match. (See error 0180 for possible cause.) With ILR on, use the MPE RESTORE command with the GROUP= option to restore the database. ACTION To avoid this error, disable ILR when moving a database from one group and account to another group and account.
-184 MESSAGE ILR log invalid - internal last access data access data does not match root file MEANING DBUTIL DISABLE command or call to DBOPEN was unable to open ILR log le because its last access date does not match the date in the root le. Possibly caused by a store and then a partial restore (using the MPE RESTORE command) of the database . Always store database with DBSTORE and restore with DBRESTOR to assure consistent dates in root le and log le.
-192 -193 -194 -195 -196 -197 -198 MESSAGE Invalid DBU MEANING ACTION The database user local control block has been corrupted. Notify HP support personnel. MESSAGE DBU control block is full MEANING ACTION The database user local control block is full. Notify HP support personnel. MESSAGE Invalid DBB MEANING ACTION The database bu er control block has been corrupted. Notify HP support personnel. MESSAGE Invalid DBG MEANING ACTION The database global control block has been corrupted.
-199 -200 -201 -202 -204 -205 MESSAGE Cannot end MPE XL XM transaction: XM error nn MEANING The logical ending of an MPE transaction failed. nn is the error number returned. Any writes done on behalf of the intrinsic will be rolled out. ACTION NOTE: This error is only possible from DBOPEN, DBPUT, DBDELETE, DBUNLOCK, or DBUPDATE. Notify system manager.
-206 MESSAGE Database exceeds limits MEANING DBOPEN has detected that the remote TurboIMAGE/XL database exceeds the local IMAGE limitations. Remote database access cannot be completed. A TurboIMAGE/XL database can only be accessed from a local node (which has IMAGE) if and only if the remote database has not exceeded the IMAGE/3000 data set and data item limitations. Access the remote TurboIMAGE/XL database from another local node which also supports TurboIMAGE/XL.
-214 MESSAGE CANNOT CALL DBXUNDO WHEN A TRANSACTION IS STARTED BY DBBEGIN. MEANING DBXUNDO can be called only when DBXBEGIN is called and not DBBEGIN. DBXBEGIN, DBXUNDO, and DBXEND are compatible intrinsics. DBBEGIN can only be matched with DBEND. Correct the application. ACTION -215 -216 -217 -218 MESSAGE XM error nn encountered when rolling out a dynamic transaction. MEANING ACTION This is an internal error. Notify your system manager and HP support personnel.
-220 MESSAGE Database and user log not attached to the same XM log set MEANING When a database is enabled for DBRECOV roll-back recovery, the database and user log must be attached to the same XM log set. Move the database and user log to the same XM log set. ACTION -221 MESSAGE Cannot begin a transaction when a dynamic transaction is active MEANING Each DBOPEN can have only one dynamic transaction active at one time.
-226 -227 MESSAGE Error occurred in when the 00 file was created MEANING ACTION The transaction de ned in the user application exceeds the maximum transaction size for dynamic transactions. Notify your database administrator and HP support personnel. MESSAGE Error occurred in 00 file recovery MEANING An internal error has occurred. Notify your database administrator and HP support personnel.
-233 -234 MESSAGE Key data found in database does not match that in the memo record MEANING ACTION An internal error has occurred. Notify your database administrator and Hewlett-Packard support personnel. MESSAGE Cannot purge the 00 file MEANING The 00 le cannot be purged due to MPE le system error. Find out the le system error number in element 2 of the status array, and notify your database administrator and HP support personnel.
-240 -241 -242 -243 -244 -245 -246 MESSAGE ERROR IN DYNAMIC ROLLBACK. MEANING ACTION The dynamic transaction could not be rolled back successfully. Notify HP support personnel. MESSAGE BAD TAG FOR TURBOLKT TABLE. MEANING ACTION The tag in the header record of the lock table, TURBOLKT.PUB.SYS, appears to be corrupted. Notify HP support personnel. MESSAGE Dynamic Rollback MDBX error.
-250 -251 MESSAGE CBINIT FAILED ON nn MEANING ACTION The initialization of a semaphore failed. Notify HP support personnel. MESSAGE DBS WAS OBTAINED BUT NOT RELEASED. MEANING There is an active lock granted on the le, TURBODBS.PUB.SYS, and not released. Notify HP support personnel. ACTION -253 MESSAGE Database enabled for indexing, but third-party indexing is not configured MEANING This message is returned if you are using third-party indexing (TPI).
-257 -258 -259 -260 -261 -262 MESSAGE Third-party index for path nn is damaged MEANING ACTION This message is returned if you are using third-party indexing (TPI). The index le for the indicated path is damaged; nn represents the path number. Consult your third-party vendor documentation. MESSAGE Invalid argument for index MEANING ACTION This message is returned if you are using third-party indexing (TPI). The argument parameter contained an inappropriate value for the speci ed index.
-263 MESSAGE INVALID PCODE RETURNED BY TPI. MEANING The third-party indexing product returned an unsupported or invalid pcode to IMAGE/SQL. Notify your system administrator or third-party vendor. ACTION -264 -265 -266 -267 -268 -269 TPIXMWRITERR MESSAGE WRITE ERROR FOR TPI FILES. MEANING ACTION Third-party indexing product encountered error from storage management procedures. The transaction may be too big, causing the transaction to stall. Notify HP support personnel.
-3nn -305 -306 -307 -308 -309 -310 MESSAGE Internal error returned MEANING ACTION Internal error nn occurred while in an intrinsic. Notify HP support personnel. MESSAGE INVALID DATA SET NUMBER. MEANING ACTION Invalid set number for the master set. The internal error is returned when trying to nd the primary address in the set using the key value. Notify your HP personnel. MESSAGE INVALID DATA SET TYPE. MEANING ACTION Invalid set type, must be master.
-312 -314 -322 -323 -331 -332 -333 MESSAGE INTERNAL ERROR ENCOUNTERED WHILE READING DATABASE BLOCK. MEANING ACTION An internal error encountered while reading the data set le. Notify your HP personnel. MESSAGE ERROR WHILE OBTAINING PATH INFORMATION FOR SET. MEANING ACTION An internal error encountered while obtaining the path information for the set. Notify your HP personnel.
-420 -421 -422 -423 MESSAGE FEATURE NOT IMPLEMENTED. MEANING ACTION Use of a feature not supported for B-Tree indices is detected. Correct your application. MESSAGE BTE: unknown qualifier value for DBCONTROL mode 13. MEANING ACTION The function code in the quali er that passed to DBCONTROL is invalid. Modify the program. MESSAGE BTE: data set# not in valid range. MEANING ACTION The data set number in the quali er that passed to DBCONTROL is invalid. Modify the program.
-427 -428 MESSAGE BTE: FCLOSE, purge failed. MEANING ACTION While trying to purge the B-Tree le, FCLOSE failed. Check the status of the B-Tree le. This may indicate a problem with the le security of the B-Tree le. MESSAGE BTE: Rebuildindex failed. MEANING The process of rebuilding the B-Tree failed. Check the third and fourth halfword of the quali er parameter you passed to DBCONTROL for the status. This value should provide extra error information in HPERRMSG format. Notify HP support personnel.
-433 -434 -436 MESSAGE BTE: DBFIND (mode 4/24) argument #2 length is bad. MEANING ACTION The size (in bytes) for argument 2 in the argument parameter passed to DBFIND is less than 0 or greater than the key length, or not valid for the search type. Modify the program. MESSAGE BTE: Data set is a detail and not a master. MEANING ACTION The data set being accessed is a detail data set and not a master data set. Correct application. MESSAGE BTE: Failed to extract data from root file.
-440 MESSAGE BTE: XM Attach of index file failed. MEANING Attaching a B-Tree to the Transaction Manager (XM) has failed. Check the third and fourth halfword of the quali er parameter you passed to DBCONTROL for the status. This value should provide extra error information in HPERRMSG format. Notify HP support personnel. ACTION -441 -442 -443 -444 MESSAGE BTE: XM Detach of index file failed. MEANING ACTION Detaching a B-Tree from the Transaction Manager (XM) has failed.
-446 MESSAGE ACTION A relational operator (<, <=, >, >=, =) was found in the DBFIND argument, which implies that only one data argument eld is expected. However, the argument 2 length eld is non-zero, implying that a second argument data eld was unnecessarily passed into DBFIND. For relational operators, DBFIND's argument 2 size must be zero. Modify the program. MESSAGE BTE: Failed to build record holding root data information. MEANING A procedure that extracts information from a root le has failed.
-452 -458 MESSAGE BTE: Key length greater than 252 bytes (maximum index key size). MEANING ACTION The key length of the data item you want to create a B-Tree index on is too long. The length can not exceed 252 bytes. Consider reducing the size of the item used as the data set key. The 252 byte limitation is a result of a KSAM/iX limitation. B-Trees are currently implemented using KSAM/iX les. MESSAGE DBOPEN failed, out of disk space.
-1004 MESSAGE HPLOADNMPROC FAILED ON CM intrinsic name MEANING An internal error has occurred. Notify HP support personnel.
Library Procedure Exceptional Conditions 10 11 12 13 14 MESSAGE Beginning of file MEANING ACTION DBGET has encountered beginning of le during a backward serial read. (No entries exist before the one previously accessed.) Appropriate action depends on program design. MESSAGE End of file MEANING ACTION DBGET has encountered the end of le during a forward serial read. (No entries exist beyond the most recently accessed one.) Appropriate action depends on program design.
15 16 MESSAGE End of chain MEANING ACTION DBGET has encountered end of chain during a forward chained read. Appropriate action depends on program design. 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.) 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.
17 MESSAGE ACTION (See below for additional status code 17 message.) DBFIND is unable to locate master data set entry (chain head) for speci ed detail data set's search item value. Appropriate action depends on program design. MESSAGE No entry MEANING 17 No master entry MEANING (See above for additional status code 17 message.) DBGET mode 1 has been called to reread an entry, but no \current record" has been established or a call to DBFIND has set the current record to 0.
20 22 23 24 25 MESSAGE Database locked or contains locks MEANING ACTION 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. Appropriate action depends on program design.
26 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 di erent open count. ACTION If it is locked by another process, it is because of the DBLOCK call from another user that the real deadlock is encountered. To avoid the self-deadlock, modify the program. If it is a real deadlock caused by another process, call DBUNLOCK.
41 MESSAGE MEANING ACTION 41 MESSAGE MEANING ACTION DBUPDATE: Full chain for path decimal integer: nn (contains 2,147,483,647 entries (See above and below for additional status code 41 messages.) User has called DBUPDATE to update a detail data set entry associated with an automatic master data set chain that already contains 2,147,483,647 values, the maximum allowable entries.
41 MESSAGE MEANING ACTION 42 44 49 Read only item MEANING DBUPDATE has been asked to change the value of a data item for which the user does not have write access. Notify user, cannot update item. Or change password in program. MESSAGE Duplicate key item value MEANING ACTION 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. Appropriate action depends on program design.
50 51 52 53 60 61 MESSAGE Buffer too small MEANING ACTION Calling program's bu er (identi ed by bu er parameter) is too small to accommodate the amount of information that DBGET or DBINFO wishes to return without extending into the parameters area. This message is returned only if the bu er is the last item in the user's stack, and will over ow the stack boundaries. Correct procedure call, or change bu er name or size. MESSAGE STACK OVERFLOW FOR BASIC - IMAGE INTERFACE.
63 64 65 66 67 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. ACTION If the database has been enabled for dumping, an I and a J le should exist. These les can help determine the cause of the error.
68 69 71 72 73 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. ACTION If the database has been enabled for dumping, an I and a J le should exist. These les can help determine the cause of the error. The database should be recovered.
1nn 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 o ending path number established by the order in which the search items occur in the set part of the schema. Notify user cannot add entry or add manual master entry and try again.
944 Others MESSAGE Warning: Assuming no message catalog MEANING ACTION No message catalog is available. Notify your system administrator. MESSAGE Unrecognized return status: nn MEANING Return status could not be recognized. Notify HP support personnel.
Library Procedure Abort Condition Messages in I File MESSAGE BUFFER SUPPLY CRISIS MEANING ACTION Internal software inconsistency caused TurboIMAGE/XL to mismanage its bu er space. 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 CRITICAL LABEL READ ERROR ON data set MEANING ACTION Unable to read label of database le.
MESSAGE HPUNLOADCMPROCEDURE FAILED ON intrinsic name INFO info SUBSYS subsystem MEANING ACTION A problem was encountered when switching to Compatibility Mode (CM). INFO is the error returned by the subsystem. SUBSYS is the subsystem which failed. Notify HP support personnel. MESSAGE LABEL WRITE ERROR ON data set MEANING ACTION Unable to complete the writing of a user label on database le. Notify the database administrator and HP support personnel if necessary.
MESSAGE UNABLE TO OPEN A data set MEANING ACTION Unable to open database le. Modify your application so that the parm parameter is 16-bit (halfword) aligned. MESSAGE WRITE ERROR ON data set MEANING ACTION While writing into database le, MPE le write error was found. Modify your application so that the parm parameter is 16-bit (halfword) aligned.
Utility Error Messages Two types of error messages are generated by the utility programs. The rst 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. Conditional errors are associated with accessing the speci ed database.
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. Use DBUTIL to disable AUTODEFER and enable ILR or ROLLBACK for the database. ACTION MESSAGE AUTODEFER MUST BE DISABLED BEFORE ROLLBACK CAN BE ENABLED MEANING ACTION The rollback recovery option cannot be used when the database has been enabled for AUTODEFER.
MESSAGE CANNOT PARSE LOG FILE NAME MEANING ACTION Internal error. Contact your database administrator. MESSAGE Cannot process data set file filename MEANING ACTION Cannot read/write to the le due to a le system error. Another process may have exclusive access to the data set. Check if the data set le exists or is locked. Retry. MESSAGE CAN'T RECOVER DATA BASES IN STATISTICAL MODE MEANING The CONTROL STATS command was entered subsequent to a RECOVER command.
MESSAGE CURRENT TRANSACTION DOESN'T MATCH LOG FILE TRANSACTION MEANING ACTION Internal error. Contact your database administrator. MESSAGE DATABASE-ACCESS FILE DOES NOT EXIST MEANING ACTION No such le exists in the logon user or account. Check the les in group to determine the correct le name. MESSAGE DATABASE-ACCESS FILE NAME MAY NOT BE QUALIFIED MEANING ACTION The DBA le name cannot be quali ed with group and account. Log on in the same group and account as the database- access le.
MESSAGE DATABASE ALREADY ENABLED FOR option MEANING ACTION The option has already been enabled for this database. Press return to terminate the program. MESSAGE DATABASE CANNOT BE ERASED UNTIL RECOVERY HAS COMPLETED MEANING Erasing database is attempted when recovery was started but not completed, or while recovery is in RESTART mode. Press return to terminate program. After the recovery process has completed, the user can run DBUTIL again.
MESSAGE DATABASE n HASN'T BEEN CREATED YET MEANING ACTION The database creator must run DBUTIL and CREATE the database. In session mode, correct the error or press return to terminate the program. MESSAGE DATABASE IN USE MEANING ACTION Utility program cannot get exclusive access to the referenced database due to other current users. In session mode, press return to terminate the program.
MESSAGE DATABASE NAME TOO LONG MEANING ACTION The database name you speci ed has more than six characters. Try the command again with the correct name. MESSAGE DATABASE NOT ENABLED FOR RECOVERY MEANING ACTION The recovery ag in the database root le is disabled. Be sure you are running recovery against the appropriately restored database. You can override the disable ag with DBUTIL if necessary.
MESSAGE DBLOAD TO DIFFERENT DATABASE NAME MAINTENANCE WORD IS NOT ALLOWED MEANING The DBLOAD database name and maintenance word must be the same as those used for DBUNLOAD. Use a database name and maintenance word which were used for the DBUNLOAD. ACTION MESSAGE DBLOAD TO DIFFERENT GROUP OR ACCOUNT IS NOT ALLOWED. MEANING DBLOAD must be done from the same group and account as the DBUNLOAD le. Log on to the same group and account from which the DBUNLOAD was done. Then use DBLOAD again.
MESSAGE DEVICE NOT 'DISC' MEANING ACTION The string following the \#" sign was not \DISC." Use EDITOR to change the FILE command. MESSAGE DSDEVICE DOESN'T MATCH FILE COMMAND MEANING ACTION The dsdevice name in the DSLINE command was not the same as the dsdevice name in the FILE command. Use EDITOR to change the command which is in error. MESSAGE DSDEVICE NAME MORE THAN 8 CHARACTERS MEANING ACTION The dsdevice name is too long. Use EDITOR to change the command which is in error.
MESSAGE ERROR WRITING ROOT FILE LABEL MEANING ACTION DBUTIL found an error while writing the root le label. Contact your HP systems engineer. MESSAGE ERROR WRITING ROOT FILE RECORD MEANING ACTION DBUTIL found an error while writing to a root le record. Contact your HP systems engineer. MESSAGE EXCEEDS ACCOUNT DISC SPACE MEANING ACTION Amount of space required by the database plus the space already assigned to other les exceeds the disk space available to the account.
MESSAGE FGETINFO CANNOT VERIFY THAT FILE IS TYPE "LOG" MEANING ACTION Internal error. Contact your database administrator. MESSAGE FGETINFO INTRINSIC FAILED MEANING ACTION Internal error. Contact your database administrator. MESSAGE FILE CODE IS NOT 0. MEANING ACTION The database-access le to be activated has a le code of other than 0. Be sure you have the correct EDITOR le.
MESSAGE FREAD ERROR ON ASCII ACCESS FILE MEANING ACTION Exceptional errors indicate a hardware or software failure. Notify the database administrator of the error. MESSAGE FWRITE ERROR ON filename:ferrmsg MEANING ACTION FWRITE failure on user recovery le. Check ferrmsg to determine the cause. MESSAGE GROUP NAME MORE THAN 8 CHARACTERS MEANING ACTION The group name part of dbname 2 is too long. Use EDITOR to change the FILE command.
MESSAGE INCOMPLETE REMOTE PART MEANING ACTION The period following the rusername was missing, or the raccountname was missing, or the raccountname was followed by a comma and the rgroupname was missing. Use EDITOR to change the HELLO command in the RDBA access le. MESSAGE INSUFFICIENT DISC SPACE MEANING ACTION The amount of disk space required for the database is not available on the system. Consult with the database administrator about disk space requirements.
MESSAGE INVALID CONTENTS OF ASCII ACCESS FILE ACTIVATION / DEACTIVATION FAILED MEANING The le speci ed is either 1. Not a database-access le, or 2. It does not contain the valid format and parameters. Either 1. Verify the correct database-access le, or 2. Use EDITOR to make the required changes and try accessing again. ACTION MESSAGE INVALID DATABASE CONTROL BLOCK MEANING ACTION TurboIMAGE/XL encountered an inconsistency in the control blocks. Contact your system engineer.
MESSAGE INVALID FIRST LOG FILE NAME MEANING ACTION Internal error. Contact your database administrator. MESSAGE INVALID FIRST LOG FILE SEQUENCE NUMBER MEANING ACTION Internal error. Contact your database administrator. MESSAGE INVALID FIRST LOG FILE TIMESTAMP MEANING ACTION Internal error. Contact your database administrator. MESSAGE INVALID IMAGE LOG RECORD DETECTED MEANING ACTION DBRECOV encountered an unde ned log record code. Notify the database administrator and HP support personnel.
MESSAGE INVALID MAINTENANCE WORD MEANING ACTION An incorrect maintenance word was used. Check the maintenance word speci ed and reenter the command. MESSAGE INVALID NUMBER OF BUFFERS SPECIFIED MEANING ACTION The number of bu ers must be between 4 and 255. Reenter the DBUTIL SET command with a valid number. MESSAGE INVALID NUMBER OF USERS SPECIFIED MEANING ACTION The minimum number of users allowed is 1 and the maximum is 120. The ranges of users speci ed must be in ascending order.
MESSAGE LANGUAGE NOT SUPPORTED MEANING The language is not supported on your system or is not a valid language name. Check with your database administrator for the con guration of the language, or enter a valid language name or number. ACTION MESSAGE LESS THAN 3 RECORDS IN FILE! MEANING ACTION The database-access le does not contain a FILE, DSLINE, or HELLO command. Use EDITOR to create the missing records.
MESSAGE LOGFILE AND DATABASE LOGID'S DO NOT MATCH MEANING ACTION The restored database does not match the log le. Be sure the log le and the backup database are properly attached. MESSAGE LOG FILE HEADER RECORD IS NOT FIRST RECORD MEANING ACTION Internal error. Contact your database administrator. MESSAGE LOGFILE IS EMPTY MEANING ACTION The log le has no records. Be sure you have correctly identi ed the log le. MESSAGE LOG FILE OPEN FAILED MEANING ACTION Internal error.
MESSAGE LOGGING IS ENABLED, CAN NOT CLEAR LOGID MEANING ACTION The logid cannot be changed while logging is in process in order to ensure validity of recovery and logging. Change the logid after the recovery process has completed. MESSAGE LOG PERIOD DOES NOT EQUAL ONE (1) MEANING ACTION Internal error. Contact your database administrator. MESSAGE MAINTENANCE WORD CANNOT BE CHANGED UNTIL RECOVERY HAS COMPLETED MEANING ACTION Changing maintenance word was attempted when recovery was enabled.
MESSAGE MISSING!! MEANING The keyword FILE is not found in the rst record; or the keyword DSLINE is not found in the second record; or the keyword HELLO is not found in any of the remaining records. Use EDITOR to modify the record in the database-access le that returned the error message. ACTION MESSAGE MISSING DBNAME1 MEANING ACTION An equal sign (=), semicolon (;), or end of line followed the keyword FILE. Use EDITOR to change the FILE command.
MESSAGE MISSING # SIGN MEANING ACTION dsdevice was not followed by a #. Use EDITOR to change the FILE command. MESSAGE MORE THAN ONE (1) LOG FILE HEADER RECORD IS FOUND MEANING ACTION Internal error. Contact your database administrator. MESSAGE MULTIPLE LOG IDENTIFIERS NOT ALLOWED MEANING ACTION You tried to simultaneously recover databases that logged to di erent log les. Run DBRECOV once for each log le.
MESSAGE NLINFO FAILURE MEANING ACTION An error was returned by NLS/3000. Notify database administrator. MESSAGE NO DATABASE HAS BEEN SPECIFIED FOR RECOVERY MEANING ACTION RUN command has been entered and no databases have been speci ed for recovery. Use the RECOVER command to specify database(s) or EXIT to terminate. MESSAGE NO INDEXING PRODUCT CONFIGURED MEANING This message is returned if you are not using third-party indexing (TPI) and you attempted to disable the database for indexing.
MESSAGE NO SUCH DATABASE MEANING ACTION Speci ed database does not exist in users logon group. Check base name and logon account and group. Press return to terminate the program. MESSAGE NOT A DATABASE ACCESS FILE MEANING ACTION The speci ed le is not a database-access le. Check the le name and try the command again. MESSAGE NOT A DATABASE OR DATABASE ACCESS FILE MEANING ACTION The speci ed database is invalid, or the speci ed le is not a database-access le.
MESSAGE OUTMODED ROOT MEANING The root le of the speci ed database corresponds to a di erent version of IMAGE software and is not compatible with the utility program currently executing. Consult with your database administrator to verify the correct version of the software. Ask HP support personnel about conversion process. ACTION MESSAGE PARAMETER EXPECTED MEANING ACTION The command you speci ed calls for another parameter. Use HELP to nd the correct command syntax.
MESSAGE PREMATURE EOF ON ASCII ACCESS FILE MEANING ACTION DBUTIL encountered an end of le mark before at least one =HELLO record in the database-access le. Use EDITOR to change the ASCII le. MESSAGE RECORD SIZE EXCEEDS 128 CHARACTERS! MEANING ACTION The longest record in the database-access le exceeds the allowable length. Use EDITOR to modify the database-access le. MESSAGE RECORDS ARE NUMBERED! MEANING ACTION The database-access le is numbered. Use EDITOR to keep the le unnumbered.
MESSAGE REMOTE GROUP rgroupname TOO LONG MEANING ACTION rgroupname is more than eight characters. Use EDITOR to change the HELLO command. MESSAGE REMOTE GROUP PASSWORD TOO LONG MEANING ACTION rgpasw is more than eight characters. Use EDITOR to change the HELLO command. MESSAGE REMOTE USER rusername TOO LONG MEANING ACTION rusername is more than eight characters. Use EDITOR to change the HELLO command. MESSAGE REMOTE USER PASSWORD TOO LONG MEANING ACTION rupasw is more than eight characters.
MESSAGE SEQUENCE ERROR ON LOG RECORD #n - EOF ASSUMED MEANING ACTION Log record numbers are out of sequence. Notify the database administrator and HP support personnel. One likely cause is that a log le has been altered, or that a start recovery operation was not performed after a system failure. MESSAGE TIMESTAMP OUT OF SEQUENCE ON LOG RECORD #n - EOF ASSUMED. MEANING ACTION Log record timestamps are out of sequence. Notify the database administrator and HP support personnel.
MESSAGE USER IS NOT CREATOR OF LOGGING IDENTIFIER MEANING A function or activity was attempted by someone other than the creator of the log identi er. Log on to the system as the user who created the log identi er or as a user with database administrator (SM) or operator (OP) capability. ACTION MESSAGE WARNING: DATABASE MODIFIED AND NOT DBSTORED MEANING The database has been enabled for logging but a backup copy has not been made by executing DBSTORE.
MESSAGE WARNING: ROOT FILE ATC FLAG IS ON, BUT dbname TC FILE IS MISSING, CANNOT DETACH 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 ATC ag in the root le indicates that the database is attached to at least one ALLBASE/SQL database environment (DBEnvironment), but its corresponding ATC le does not exist. Therefore, DBUTIL cannot detach the speci ed database.
MESSAGE WARNING: THE NUMBER OF DATA SETS DEFINED IN THE SCHEMA IS LESS THAN (OR GREATER THAN) THE NUMBER OF DATA SETS FOUND ON THE DBLOAD MEDIA. MEANING You have added or deleted data sets from the database between a DBUNLOAD and a DBLOAD. DBLOAD will continue with the load, but data can be lost or put into the wrong sets due to an invalid set change. Stop the DBLOAD, correct the schema, and perform DBLOAD again. Or, if you are sure the database is not corrupt, allow DBLOAD to continue.
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. Re-create the root le with a larger capacity for automatic master. Rerun the necessary utilities. ACTION MESSAGE ***BAD DATABASE*** MEANING This message is issued by DBSTORE, DBRESTOR, and DBUNLOAD.
MESSAGE CAN'T CREATE NEW COPY OF FILE x (FS ERROR #) MEANING ACTION MPE intrinsic FOPEN failed while creating a temporary le. Check the le system error. Possible reasons: The speci ed device does not exist or has insu cient space. MESSAGE CAN'T GET SPECIFICATIONS VIA FGETINFO FOR THIS FILE x (FS error #) MEANING ACTION MPE intrinsic FGETINFO failed. DBUTIL cannot get information for the speci ed le. Check the le system error to determine cause.
MESSAGE ***COPY FAILED*** MEANING An error occurred while copying the le. DBUTIL has encountered a problem reading or writing the les. (It is possible the disk pack is bad.) Restore the database and try the move again. Contact your database administrator if the copy fails again. ACTION MESSAGE COULD NOT ATTACH DATA SET n TO XM LOG FILE: FILE SYSTEM ERROR nn MEANING ACTION The data set could not be attached to the MPE transaction recovery mechanism. nn is the le system error number returned.
MESSAGE DATA SET FULL MEANING ACTION Data set currently being loaded is full. Re-create root le, increase the data set's capacity and run the utilities again. MESSAGE DATABASE TABLE OVERFLOWED MEANING ACTION Internal error. Contact your database administrator. MESSAGE DATABASE TABLE TRANSACTION COUNT IS NEGATIVE MEANING ACTION Internal error. Contact your database administrator. MESSAGE DBBEGIN FOUND AN ALREADY ACTIVE TRANSACTION MEANING ACTION Internal error.
MESSAGE Dynamic capacity expansion in progress flag is on MEANING The data set is being expanded by DBPUT in another process. The number of entries and the current capacity may not be accurate since the data set is being expanded at this time. If asterisks (***) are in the \no. of entries" and \%max cap" elds, then a previous DBPUT may have aborted while DBPUT was expanding this data set. If there are positive numbers in the \no. of entries" and \% max cap" elds, nothing needs to be done.
MESSAGE FILE x ALREADY RESIDES ON DEVICE x MEANING ACTION The le speci ed already resides on the device. Continue with the next desired command, or exit from DBUTIL. MESSAGE FREADDIR FAILURE MEANING ACTION This is an MPE exceptional failure and is returned when DBUTIL calls FREADDIR. Contact your database administrator. MESSAGE HARD TERMINAL READ ERROR, TERMINATING MEANING ACTION DBUTIL cannot read input from terminal. Notify HP systems engineer.
MESSAGE INTERNAL ERROR--FOPEN FAILS IN F'HEADLOG MEANING ACTION Internal error. Contact your database administrator. MESSAGE INTERNAL ERROR--FOPEN INTRINSIC FAILED MEANING ACTION Internal error. Contact your database administrator. MESSAGE INTERNAL ERROR--FREADLABEL FAILS IN F'HEADLOG MEANING ACTION Internal error. Contact your database administrator. MESSAGE INTERNAL ERROR--FREADLABEL INTRINSIC FAILED MEANING ACTION Internal error. Contact your database administrator.
MESSAGE INTERNAL ERROR--INVALID PASSWORD FOR DATABASE LOGGING IDENTIFIER MEANING ACTION Log password does not correspond with the log identi er in the log le. Contact your database administrator. MESSAGE INTERNAL ERROR--INVALID PROCTABLE INDEX FOUND IN PROC'ACTIVELINK MEANING ACTION Internal error. Contact your database administrator. MESSAGE INTERNAL ERROR--INVALID RECOVERY TABLE ADDRESS MEANING ACTION Internal error. Contact your database administrator.
MESSAGE INTERNAL ERROR--RECORD TABLE IS FULL MEANING ACTION Internal error. Contact your database administrator. MESSAGE INTERNAL ERROR--UNABLE TO ALLOCATE THE HEAP MEANING ACTION Internal error. Contact your database administrator. MESSAGE ***INVALID SET COUNT*** MEANING ACTION TurboIMAGE/XL found an inconsistency in the data set count. Notify HP systems engineer. MESSAGE INVALID TRANSACTION SEQUENCE DETECTED MEANING ACTION Internal error. The transaction numbers are not consecutive.
MESSAGE RECOVERY TABLE OVERFLOW MEANING ACTION You tried to specify more than 100 user recovery les. Reduce the number of recovery les needed. MESSAGE RECSIZE MUST BE <=xxxx AND EVENLY DIVISIBLE BY 256. MEANING Issued if the REC=recsize parameter for DBSTORE speci ed a record size not modulo 256 halfwords, or greater than the con gured record size of the device. Check the REC=recsize parameter and correct it before running DBSTORE again.
MESSAGE UNABLE TO CONTINUE MEANING DBUTIL program (operating in PURGE mode) cannot continue execution due to exceptional error in le system. This information is followed by MPE le information display. Save the le information. Consult with database administrator and HP support personnel. ACTION MESSAGE UNABLE TO OBTAIN FILE LABEL INFORMATION FOR FILE x MEANING ACTION MPE internal procedure failed. DBUTIL cannot obtain information for the speci ed le. Contact your database administrator.
Extended Utility Program Unconditional Messages A set of messages can be returned when an unusual condition causes TurboIMAGE/XL to fail while a TurboIMAGE/XL utility is executing. In each of the following messages, the value xxxxx is the location where TurboIMAGE/XL failed. Error messages 401 through 414 are all TurboIMAGE/XL utility failures caused by failure of the TurboIMAGE/XL intrinsic speci ed in the message.
-70 MESSAGE ENTRY NUMBERS ARE OUT OF SEQUENCE. TURBOIMAGE FAILED AT xxxxx MEANING The next block on the backup volume was not what DBLOAD expected. Status elements 0,1 have the expected block number; elements 2,3 have the actual next block number; element 4 has the set number. An error for a known value that was written to tape with FWRITE was found. The tape or tape drive could be defective.
401 MESSAGE DBOPEN FAILURE AT xxxxx MEANING A detailed error message can be retrieved by calling DBEXPLAIN. For more information, see \Library Procedure Error Messages" earlier in this appendix. ACTION 402 MESSAGE DBINFO FAILURE AT xxxxx MEANING A detailed error message can be retrieved by calling DBEXPLAIN. For more information, see \Library Procedure Error Messages" earlier in this appendix.
407 MEANING DBPUT FAILURE AT xxxxx MEANING A detailed error message can be retrieved by calling DBEXPLAIN. For more information, see \Library Procedure Error Messages" earlier in this appendix. ACTION 408 MESSAGE DBDELETE FAILURE AT xxxxx MEANING A detailed error message can be retrieved by calling DBEXPLAIN. For more information, see \Library Procedure Error Messages" earlier in this appendix.
413 MESSAGE DBEND FAILURE AT xxxxx MEANING A detailed error message can be retrieved by calling DBEXPLAIN. For more information, see \Library Procedure Error Messages" earlier in this appendix. ACTION 414 MESSAGE DBMEMO FAILURE AT xxxxx MEANING A detail error message can be retrieved by calling DBEXPLAIN. For more information, see \Library Procedure Error Messages" earlier in this appendix.
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 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 identi ed at the far left of the row in which the box appears.
Figure B-1.
C Database Design Considerations Keep one-of-a-kind information, such as unique identi ers, in master data sets. Keep duplicate information, such as records of events (sales, purchases, shipments), in detail data sets. De ne 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.
If your application uses sorted paths, plan to add or delete entries (DBPUT, DBDELETE) to sorted chains when the system is not very busy. If it is very busy, limit the database 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.
101 503 1,009 5,003 10,007 15,013 20,011 25,013 30,011 35,023 40,009 45,007 50,021 55,001 60,013 65,003 70,001 75,011 80,021 85,009 90,001 95,003 100,003 110,017 121,001 130,003 140,009 150,001 160,001 170,003 180,001 190,027 200,003 210,011 220,009 230,003 240,007 250,007 260,003 270,001 280,001 290,011 300,007 310,019 320,009 330,017 340,007 350,003 360,007 370,003 380,041 390,001 400,009 410,009 420,001 430,007 440,009 450,001 460,013 470,021 480,013 490,001 500,009 510,007 520,019 530,017 540,041 550,0
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 speci ed multiple lock descriptors. Any program which does not have the Multiple RIN (Resource Identi cation 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.
If it is absolutely necessary to make multiple DBLOCK calls, the following information about how TurboIMAGE/XL performs locking may be useful.
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 e ect using MR capability has on the local system is that the rule prohibiting multiple DBLOCK calls is not enforced.
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 ag will always be zero in the log le records. This ag is used during recovery if user recovery les are created. Note All TurboIMAGE/XL records are contained within MPE/iX \WRITELOG" records.
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(15) HALFWORD(16) HALFWORD(17) HALFW
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 USER BUFFER (pointer to beginning o
DBOPEN (continued) HALFWORD(40) HALFWORD(41) HALFWORD(45) HALFWORD(48) HALFWORD(52) HALFWORD(56) HALFWORD(60) HALFWORD(61) HALFWORD(63) HALFWORD(65) HALFWORD(66) HALFWORD(69) HALFWORD(72) HALFWORD(73) - DBOPEN MODE PARAMETER LOGGING IDENTIFIER DBSTORE TIME STAMP (3 HALFWORDS) USER PROGRAM NAME USER PROGRAM GROUP 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
DBQUIESCE HALFWORD(0-8) HALFWORD(9) HALFWORD(10) - HALFWORD(11) HALFWORD(12) HALFWORD(13) HALFWORD(17) HALFWORD(21) HALFWORD(25) HALFWORD(29) HALFWORD(33) HALFWORD(37) HALFWORD(41) HALFWORD(45) HALFWORD(49) HALFWORD(51) - MPE WRITELOG RECORD TURBOIMAGE/XL LOG RECORD LENGTH QUIESCE CODE QB - QUIESCE BEGIN QE - QUIESCE END UQ - UNQUIESCE FOR INTERNAL USE QUIESCE FLAG FROM QLOCK TABLE USER NAME USER GROUP USER ACCOUNT DATABASE NAME DATABASE GROUP DATABASE ACCOUNT USER PROGRAM NAME USER PROGRAM GROUP USER PR
DBXBEGIN 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 DBXBEGIN LOG RECORD CODE ("XB") 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 DBXEND HALFWORD(0-8) HALFWORD(9) HALFWORD(10) HALFWORD(11) HALFWORD(12) HALFWORD(13) HALFWORD(15) HALF
F MPE/iX Log Record Formats This appendix lists the MPE/iX Log Record Formats for log les and user recovery les.
WRITELOG CONTINUATION HALFWORD(0) HALFWORD(2) HALFWORD(3) HALFWORD(3) HALFWORD(4) HALFWORD(6) HALFWORD(7) HALFWORD(8) HALFWORD(9) - RECORD NUMBER (1 WORD) CHECKSUM SUBSYSTEM IDENTIFIER (lST BYTE) LOG RECORD CODE (2ND BYTE - 7) TIME DATE LOG NUMBER USER BUFFER LENGTH USER BUFFER AREA - 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 T
RESTART HALFWORD(0) HALFWORD(2) HALFWORD(3) HALFWORD(3) HALFWORD(4) HALFWORD(6) HALFWORD(7) - RECORD NUMBER (1 WORD) CHECKSUM SUBSYSTEM IDENTIFIER (1ST BYTE) LOG RECORD CODE (2ND BYTE - 6) TIME DATE LOGGING IDENTIFIER - RECORD NUMBER (1 WORD) CHECKSUM SUBSYSTEM IDENTIFIER (1ST BYTE) LOG RECORD CODE (2ND BYTE - 9) TIME DATE - 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 IDEN
G Recovery and Logging Quick Reference Recovery Quick Reference The following pages o er 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.
Intrinsic Level Recovery (ILR) Should only be used to force ushing 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. Guarantees that at most one DBPUT and DBDELETE call per process will be lost.
May not recover all transactions. If using DBEND mode 2, transactions will be ushed to the log le at DBEND time; therefore, transactions will not be lost. You should consider how often to store the database. The more frequent the backup, the smaller the log les will be, thus cutting the time required for recovery. Roll-Forward Flag Settings The recommended settings for TurboIMAGE/XL ags used for roll-forward recovery are shown in the following table.
Transactions are not lost during a start recovery operation because they are not held in the memory bu er. (A start recovery operation must be performed after a system failure.) When the roll-back process nishes, the RESTART option in user logging can be used or a new logging cycle can be started. Remember to purge the log le before starting the new logging cycle. Roll-Back Flag Settings The recommended settings for TurboIMAGE/XL ags used for roll-back recovery are shown in the following table.
Logging Device Quick Reference The lists below outline both the bene ts 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 sta , number of users and size of the database, and other considerations listed here. Logging to Tape For roll-back recovery, requires the database be on the system volume set. Does not take up disk space.
Has overhead comparable to logging to tape. 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 le to resume logging.
Sample Job Streams This section shows a sample job stream which can be used to initiate a logging cycle. Prior to using this job stream, you should check the MPE/iX logging con guration for adequate capacity. Also shown in this section are sample job streams which can be used to recover a database using either roll-forward recovery or roll-back recovery. You must decide which recovery method to use and how often the database should be stored.
At the end of the logging cycle, stop logging, store the current log le on tape for back-up, purge the current log le, build a new log le, and store a database backup copy. To start a logging cycle, the steps (except GETLOG command) shown in the previous job stream in Figure G-1 are completed after you do the following: Stop logging. Use STORE command to store the log le to tape. :PURGE ORDER001 Purge the current log le. The next example in Figure G-2 uses roll-forward recovery and DBSTORE/DBRESTORE.
The next example in Figure G-3 uses roll-back recovery. If all recommended procedures have been followed, the database will have ags set for enabling recovery and disabling access, so the step to set these ags would be unnecessary. 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.
:JOB MGR.DATAMGT :GETLOG ORDERLOG;LOG=ORDER001,DISC;AUTO Acquire log identi er. AUTO is optional. :BUILD ORDER001;DISC=200000,20,7;CODE=LOG Build new log le. :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 :FILE ORDERBK1;DEV=TAPE :STORE ORDERS;*ORDERBK1;ONLINE=START :LOG ORDERLOG,START :RUN DBUTIL.PUB.
process is being done interactively, the following command in DBUTIL will show if the ags for recovery and access are correctly set: >>SHOW database name FLAGS :JOB MGR.DATAMGT :FILE ORDERBAD;DEV=TAPE :STORE ORDERS;*ORDERBAD;ONLINE=START :RUN DBUTIL.PUB.SYS PURGE ORDERS EXIT :FILE ORDERBK2;DEV=TAPE :RESTORE *ORDERBK2;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.
:JOB MGR.DATAMGT :RUN DBUTIL.PUB.SYS DISABLE ORDERS FOR ACCESS ENABLE ORDERS FOR RECOVERY EXIT Set the ags in the database root le. A backup of the database at this time is recommended. :RUN DBRECOV.PUB.SYS CONTROL NOSTORE ROLLBACK ORDERS RUN EXIT :LOG ORDERLOG,RESTART :RUN DBUTIL.PUB.SYS ENABLE ORDERS FOR ACCESS DISABLE ORDERS FOR RECOVERY EXIT :EOJ Allows recovery to proceed whether or not the DBSTORE ag is set. Use roll-back recovery on database ORDERS.
H TurboIMAGE/XL versus TurboIMAGE/V Overview TurboIMAGE/XL is available on the HP 3000 Series 900. This database management system is very similar to TurboIMAGE/V. However, some di erences exist due to the architecture of the 900 series and the MPE/iX features of which TurboIMAGE/XL takes advantage.
Databases can be stored, even when they are open for read/write access, using TurboSTORE/iX 7x24 True Online Backup (with ONLINE=START or ONLINE=END option). Their related les, such as TC le and third-party index les, are stored along with the databases. DBRECOV can perform a roll-forward recovery for a database stored using TurboSTORE/iX 7x24 True Online Backup (with ONLINE=START or ONLINE=END option). Data sets, master as well as detail, can be dynamically expanded during DBPUT.
Table H-1. TurboIMAGE/XL Differences Area A ected Data Set Size { DBEXPLAIN { { DBOPEN { DBSTORE Command { { Dynamic Roll-Back Recovery { { { Intrinsic Level Recovery { { { { { { { { Changes/Additions The maximum data set size is 4 gigabytes unless it is a jumbo data set. 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.
Table H-1. TurboIMAGE/XL Differences (continued) Area A ected Remote Database Access Roll-Back Recovery Run-Time Control Blocks { { { { { { Status Area { { TURBO Trace and Pro ler Third-Party Indexing { { B-Tree Indices { Master and Detail Data Set Expansion { Jumbo Data Sets { Dynamic Multiple Database Transaction (DMDBX) { Deadlock Detection { H-4 Changes/Additions Only NS/3000 is supported on MPE/iX. ILR is not required.
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 le system service, called Transaction Management (XM), to provide intrinsic level backup and recovery. Unless AUTODEFER is enabled, all intrinsics that modify the database (DBPUTs, DBDELETEs, and DBUPDATEs) are written to XM log le pages by MPE/iX.
is enabled for ILR, the last DBPUT or DBDELETE, which was interrupted by a system failure or other abnormal termination, will be completed. When recovery is necessary, it must be performed at system startup time before anyone modi es the database. This can cause a slightly longer startup time. (If a program accessing a TurboIMAGE/XL database aborts during the execution of an intrinsic, the incomplete intrinsic will be undone.
Control Blocks Run-time control blocks are created di erently 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. See the descriptions below for these four tables that were added: TURBOLKT TURBOGTX QOPEN QLOCK Major Differences Run-time control blocks are no longer created as privileged extra data segments.
TOTAL DBOPEN COUNT PER USER EXCEEDS LIMIT OF 127 The Database Lock Table (TURBOLKT) contains information pertaining to locks on the database and is used to avoid deadlocks. The Multi-Database Transactions (TURBOGTX) contains information pertaining to dynamic transaction constituting multiple databases. The QOPEN Table (QOPEN) contains information about user logging process for active DBOPENS of modes 1-4. The QLOCK Table (QLOCK) contains information about all writers to databases and a pointer to QOPEN.
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 les, DBOPEN calls HPFOPEN to open these mapped les. If an error occurs during this process, the condition code 09, formerly used to indicate an MPE/iX GETDSEG failure, is now used to indicate an MPE/iX HPFOPEN failure.
library procedure that encountered the error. This could a ect applications that use two or more di erent status arrays. Table H-4 compares elements 5 through 10 of the TurboIMAGE/V status area with elements 5 through 10 of the TurboIMAGE/XL status area. If an error occurs, this information is returned for all library procedures. If the procedure executes successfully, this information is returned for DBBEGIN, DBCLOSE, DBCONTROL, DBEND, DBINFO, DBLOCK, DBMEMO, and DBOPEN. Table H-4.
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 dbname 00 le. If the dbname 00 le exists, the database needs to be recovered. Open the database and close it again. The recovery occurs automatically with the call to DBOPEN. 2. Disable ILR, roll-back recovery, and, if applicable, third-party indexing.
For a complete syntax listing of the DBUTIL >>SET command, refer to Chapter 8. Parameters BUFFSPECS is for MPE V compatibility only, because the TurboIMAGE/XL bu er speci cations are xed at a large default value. For databases that will be moved to MPE V, it sets the number of bu ers to be allocated by TurboIMAGE/V in the Database Bu er Area Control Block (DBB).
For example, the largest path count for a detail data set in the ORDERS database is 4. (This is the path count for the CUST data set.) Therefore, the value of b for the ORDERS database is shown here: b = max (4+3,8) = 8 The default bu er speci cations in this case are: 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) Example 1 :RUN DBUTIL.PUB.SYS . . . >>SET ORDERS BUFFSPECS=5(1/120) For database ORDERS BUFFER SPECIFICATIONS: 5(1/120) >> Initiate DBUTIL execution.
Index A abnormal termination of a procedure, 4-39 abort and recovery, 7-5 conditions, A-19, A-74 ABORTS parameter, of DBRECOV, 8-14, 8-15 absent list, 2-18, 2-19 versus null list, 2-18 access calculated, 4-15 chained, 4-15 class password, modifying, 8-64 concurrent modes, 4-4 creator-only, 2-16 directed, 4-13 disable, 8-48 enable, 8-51 exclusive, 2-24 granting, B-1 modes, 2-18, 4-3 modes and user class number, 4-10 none, 2-16 option, 8-48, 8-51 path, 4-12 read, 2-16 rules, 2-19 semi-exclusive, 2-24 serial,
B-Tree index attachment, 5-60 DBINFO, 5-54, 5-60 mode setting, 5-54 B-Tree indices, 11-1{20 external commands a ected, 11-5 getting started, 11-20 key points, 11-2 limits, 11-19 overview, 11-1 terminology, 11-1 utilities a ected, 11-5 BTREEMODE1, 11-2 bu er length, 3-26 management, 10-15 speci cations, H-11{13 BUFFSPECS option, of DBUTIL, 8-64, 8-68, H-11 BUILD command, of MPE/iX, 7-17 byte, 3-5 C C, 6-1 sample program, 6-20{25 calculated access, 4-15 reading data, 4-15 calling errors, A-19 call statements
size of, 10-12 System (DBS), 4-2, 10-10 User Local (DBU), 4-2, 10-10 User Local Index (DBUX), 4-2, 10-10 CONTROL command of DBRECOV, 8-14{17 of Schema Processor, 3-23 control, exclusive, 8-68 conventions database description language, 3-2 model program, 6-5 copying data entries to formatted tape, 8-34 copying entire database from backup volumes, 8-28 to disk, 8-28 to tape, 8-30 correspondence of backup copy and log le, 7-39 CREATE command, of DBUTIL, 8-44{45 creating a database, 7-1 the text le, 3-18 creato
Database Bu er Area Control Block (DBB), 4-2, 10-10 allocating bu ers, 8-64 Database Globals Control Block (DBG), 4-2, 10-10 Database System Control Block (DBS), 4-2, 10-10 Database User Local Control Block (DBU), 4-2, 10-10 Database User Local Index Control Block (DBUX), 4-2, 10-10 data entry, 2-1 and access mode, 4-12 and user class number, 4-10 deleting, 4-22 length, 2-1 locking, 4-24, 4-29 numbers, 4-12 sequence for adding, 4-9 data item, 2-1 compound, 2-1 de nition of, 2-1 identi ers, 3-9 length, 3-5 m
DBERROR calling sequence, 5-23 description, 4-39, 5-23 messages, 5-24{35 DBEXPLAIN calling sequence, 5-36 description, 4-39, 5-36 messages, 5-37{38 DBFIND calling sequence, 5-39 current path number, 5-43 current record number, 5-43 description, 4-12, 4-15, 5-39 errors, 5-44 for B-Tree index, 11-1 with B-Tree index, 11-11 DBGET calling sequence, 5-46 current path, 5-48 description, 4-12, 4-15, 5-46 errors, 5-49 primary path, 2-8 with B-Tree index, 11-17 DBG, use of, 10-10 DBINFO and CIUPDATE option, 4-37 and
PREFETCH option, 8-48, 8-51 RECOVERY option, 8-48, 8-51 ROLLBACK option, 8-48, 8-51 DBUTIL utility commands ACTIVATE, 8-41{42 ADDINDEX, 8-43 CREATE, 8-44{45 DEACTIVATE, 8-46 DETACH, 8-47 DISABLE, 8-48{49 DROPINDEX, 8-50 ENABLE, 8-51{52 ERASE, 8-53 EXIT, 8-54 HELP, 8-55 MOVE, 8-56{57 PURGE, 8-58{59 REBUILDINDEX, 8-60 REDO, 8-61 RELEASE, 8-62 SECURE, 8-63 SET, 8-64{67 SHOW, 8-68{76 VERIFY, 8-77 DBU, use of, 10-10 DBUX, use of, 10-10 DBXBEGIN calling sequence, 5-95 description, 5-95 errors, 5-97 DBXEND calling
DSLINE command in database-access le, 9-5 DS user identi cation, 9-4 dummy parameters, 5-4 dumping disable, 8-48 enable, 8-51 DUMPING option, of DBUTIL, 8-48, 8-51 show, 8-68 dynamic capacity.
and data types, 3-5, 3-7 owchart, security, 2-19 formal le designators, 3-17 FORTRAN 77, 1-5, 2-1, 6-1 and complex numbers, 3-8 sample routines, 6-47{52 full data access, 2-16 G GETLOG command, of MPE/iX, 7-18 getting started with B-Tree indices, 11-20 granting a user class access, 2-19 group protection, 2-15 user, 2-15 H halfword, 3-5 HELP command, of DBUTIL, 8-55 high-water mark, 5-13, 5-14 host language access, 6-1 HP Sort, 2-9 HWMPUT, 5-13, 5-14 I I and J les, A-19 identi ers, data item, 3-9 identify
library procedures, 1-5 abort condition messages, A-74{76 calling error messages, A-23{61 error messages, A-18 exceptional condition messages, A-62{73 le system and memory management error messages, A-20{22 summary of, 5-3 LINES option, of $CONTROL, 3-23 list absent, 2-18 null, 2-18 list le, 3-21 Schema Processor, 3-17 LISTLOG command, of MPE/iX, 7-18 LIST option, 3-25 and $PAGE command, 3-21 of $CONTROL, 3-23 lock area, 10-16 lock descriptors, 4-24 array, format of, 5-72 sort sequence, D-2 locking, 4-14 ac
to tape, quick reference, G-5 Transaction Management, 4-33 transaction numbers, 4-35 user, 4-33 what it does, 4-33 LOGGING option, of DBUTIL, 8-48, 8-51 logical transaction and locking, 7-9 de nition of, 4-34, 7-6 log identi er creating, 7-18 setting in root le, 7-21, 8-64 LOGID option, of DBUTIL, 8-64, 8-68 LOGINFO option, of DBUTIL, 8-68 logon group, database creator, 2-13 log records, 7-35 le reference, 8-19 fmode, 8-19{20 formats, MPE/iX, F-1 formats, TurboIMAGE/XL, E-1 rmode, 8-19{20 user reference, 8-
N names data, 3-10, 3-13 database, syntax, 3-2 data set, 2-2, 3-10, 3-13, 8-44 Native Language Support (NLS), 1-3 Network Services (NS/3000), 9-1 nibble, 3-5 NOABORTS parameter, of DBRECOV, 8-15 no access, 2-17 data item, 2-17 data set, 2-17 NOLIST option, of $CONTROL, 3-23 NOMDBX parameter, of DBRECOV, 8-15 NOROOT option, of $CONTROL, 3-23 NOSTAMP parameter, of DBRECOV, 8-15 NOSTATS parameter, of DBRECOV, 8-14, 8-17 NOSTORE parameter, of DBRECOV, 8-15 NOTABLE option, of $CONTROL, 3-23 NOUNEND parameter, o
database, 5-3 group, 2-15 library procedure, 2-24 privileged le, 2-15 utilities, 2-24 PURGE command, of DBUTIL, 8-58{59 purging the database, 8-58 Q QLOCK, 10-10, 10-12 QOPEN, 10-10, 10-12 QUERY/3000 data types, 3-8 de nition of, 1-2 remote database access, 9-12 quick reference, logging and recovery, G-1 logging device, G-5{6 recovery options, G-1{4 sample job streams, G-7{12 R read access, 2-17 default, 2-18 read and write class lists, 2-15, 2-16, 2-17 excluding user classes, 2-17 schema, 2-18 reading da
rereading data, 4-17 resetting data sets, 5-8 Resource Identi cation Number (RIN), D-1 RESTART option, of DBRECOV, 8-11 RESTORE command, of MPE/iX, 2-15 restoring from database backup copy, 7-37 return status, 4-38 rewinding data sets, 5-8 RIN, D-1 ROLLBACK command, of DBRECOV, 8-24{25 ROLLBACK option, of DBUTIL, 8-48, 8-51 disable, 8-48 enable, 8-51 roll-back recovery, 7-4, 8-24 disabling, 7-46 dynamic, 7-4, 7-13 performing, 7-46 quick reference, G-3 roll-forward recovery, 7-4, 8-22 quick reference, G-2 ro
serial access and locking, 4-15 reading data, 4-14 SET command, of DBUTIL, 8-64{67 set part details, 3-13 masters, 3-10 schema, 3-10, 3-13 sharing database, B-1 show capacity, 8-73 locks, 8-74 SHOW command, of DBUTIL, 8-68{76 SHOWLOGSTATUS command, of MPE/iX, 7-18 simple argument, 11-2 sorted chains, C-1 entries, maintenance of, 2-9 sort items, 2-8, 3-16 de ned as critical items, 2-1 design considerations, C-1 updating values, 4-18, 4-19, 8-66 sort sequence for lock descriptors, D-2 space allocation for det
static, de ned, 7-6 Transaction Management, of MPE/iX, 4-33, 10-17 transactions de nition, 5-4 dynamic, 7-8 multiple database, 7-8 static, 7-8 TRANSACT/V, 1-5 TRANSPORT option, of DBSTORE, H-11 True-Online Backup, 7-24, 8-33 TURBOGTX, 10-10, 10-11 TurboIMAGE/V versus TurboIMAGE/XL, H-1 TurboIMAGE/XL e ect on programs, 1-5 overview, 1-1, H-1 TURBOLKT, 10-10, 10-11 TurboSTORE/iX 7x24, 8-33 TurboSTORE/iX 7x24 True-Online Backup, 7-24 bene ts, 7-26 type designators, 3-5 and programming languages, 3-6 table of,
