Chapter 6: For the Database Administrator (DBA)

This chapter describes the IMS Option support for advanced database features. Many of the terms and phrases used in this chapter will be understood only by those with specific training in, or an unusually good understanding of, IMS/ESA database design concepts and implementation.

The database features described in this chapter are:

6.1 Overview

It is very easy to create and generate DBDs in IMS Option. However, IMS Option cannot determine whether a DBD will be acceptable to an IMS/ESA support group. IMS Option identifies a number of syntax errors during DBDGEN processing. The DBDGEN messages explain syntax errors with lines of descriptive text instead of short Assembler-like MNOTEs. DBDs likely to produce undesired results on the mainframe cannot be determined. Errors in DBDs which produce unacceptable performance on the mainframe cannot be detected and might not appear within IMS Option. It is important to involve your database experts when designing a new database or making changes to an existing database.

6.2 Secondary Index Definitions

It is not necessary to run a DBDGEN for an index DBD unless you want to process it as a stand-alone database or it defines an index with non-unique keys. If an index DBD describes non-unique keys, it must be generated prior to zeroloading the database.

A maximum of 32 secondary indices can be defined for one database. These can all be defined for the same source and target segment. The primary index in a HIDAM database is not a secondary index.

The source segment can be different to the target segment. As with IMS/ESA, if the source segment is different than the target, it must be an eventual child of the target segment.

The XDFLD operands of NAME, SEGMENT, CONST, SRCH, SUBSEQ, DDATA and NULLVAL are supported. Hex and binary value NULLVAL definitions, for example, X'40' or B'00000001', are compared exactly as stated.

User data is supported; however, a new operand is required on the XDFLD statement. XDFLD operands of UBYTES and, optionally, USTART, are used to indicate the length and starting position of user data in the index record. The section Processing a Stand-alone Index contains further details on user data.

The source segment can be a fixed or variable length segment.

The START and BYTES options for a /CK field are supported.

Shared secondary indices are supported (the CONST operand), although they must be defined as separate members and are physically stored in separate files. No checking is performed to ensure the shared indices would meet the restrictions for sharing.

The combined lengths of CONST, SRCH and SUBSEQ fields are supported up to their maximum 240 bytes.

The combined lengths of CONST, SRCH, SUBSEQ, DDATA and user data cannot exceed 1,536 bytes. This maximum is reduced to1,532 bytes if the index has non-unique keys.

An index DBD describes an index with non-unique keys if there is an OVFLW keyword on the DATASET macro in the index DBD or the sequence FIELD specifies multiple keys (SEQ,M).

The XDFLD SRCH fields are only available in an SSA for a target segment when the corresponding alternate processing sequence is used or the source segment is the same as the target segment.

6.3 External Secondary Sparse Routines

External sparse routines are supported and can be re-written in COBOL or are supported in Assembler using the Assembler Option. The DB Configuration setting Enable Secondary Index Sparse and Data Capture exit - Language indicates the language type of the external routines.

If this option indicates COBOL routines, IMS Option calls the program named in the EXTRTN parameter using COBOL style linkage conventions. There is a sample program named sparsrtn.cbl which shows the COBOL interface. Please refer to the comments in this program for a further description of the COBOL interface.

If you want to use Assembler routines, you must:

  1. Set the appropriate configuration value on the DB page of the IMS System Properties dialog box.

  2. Preprocess, assemble and link the supplied routine named ims2asm.mlc using the Assembler Option. This program is a glue module which changes the parameters passed from IMS Option in COBOL standard linkage format to the non-standard linkage convention defined by IMS/ESA for these exits. Refer to the comments in the ims2asm.mlc program for details.

The sparse routine can be debugged in the same way as any other application program. When maintenance occurs to the source segment of the index, the exit is invoked and is debugged if it has been prepared for debugging. For COBOL programs, this means the Create debug/browse information check box is checked on the Build Settings for program dialog box. If the program is not displayed in the debugger, verify that the compiled program is in a loadlib folder and that the IMS System property Secondary Index Sparse and Data Capture exits - Language is set appropriately. This setting is shared with Data capture exits. See the section Data Capture Exits. For information about setting IMS system properties, see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, Working with IMS Projects, How to, Configure an IMS Project.

Any errors, such as "exit not found" or "invalid return code", encountered while calling the exit are logged in the IMS System Log. Processing continues as if the exit were not defined. See the section IMS System Log in the chapter IMS Option Administration Information in your Administrator's Guide for more information.

In IMSVS86 versions 2.4 and prior, only COBOL routines were supported and you had to add a parameter named EXTRNCBL to your DBD. This parameter is still supported, and, if specified for an index, takes precedence over the language type specified on the IMS System Properties dialog box.

The CSECT parameter (Reg 3) is supported in the call list except for the user data component. The sparse routine is responsible for providing all data required to process each index it is responsible for. The PST (Reg 1) parameter is an address pointing to a dummy 1 byte area.

6.4 Secondary Index Maintenance

IMS Option uses the same maintenance rules as IMS/ESA to provide good performance and to maintain consistency of user data.

When a variable length source segment's length is not long enough to provide a SRCH field, the index entry is not created.

When a variable length source segment's length is not long enough to provide a SUBSEQ or DDATA field, the filling of missing fields is as if the missing field were of type "X".

An attempt to insert a duplicate key into an index which does not provide for non-unique keys is rejected with a status code of NI.

The status code NE is issued for index maintenance errors caused by deleting an index segment while processing an index as a stand-alone, and then updating the source segment in such a way as to cause index maintenance. The index is not corrupted, however, as IMS Option assumes the index entry was removed by a user application and was not caused by index maintenance errors or mismanagement of an index database.

Index errors of NE and NI are logged in the IMS System Log.

The "SX" field, when used, is a four byte unique value. This value is unique for each source segment. However, the value might not correspond to its hierarchical position in the database. The order of index entries, which differ only by the SX value, is random as it is the relative byte address of the source segment. Combinations of CK and SX can be used to present a more application-oriented order.However this might change the way the index record is perceived when using it as a stand-alone database.

Non-unique index entries stored in a VSAM ESDS are stored in LIFO order. Non-unique index entries are chained together similar to IMS/ESA. Poor performance can result if many index records with the same search values are chained together.

NULLVAL comparisons differ from IMS/ESA in that all field types are assumed to be "X". Thus, packed fields are compared logically instead of algebraically. A work-around for this limitation would be to write a Sparse routine. See the section External Secondary Sparse Routines earlier in this chapter.

6.5 Processing a Stand-alone Index

Retrieval, replace and delete calls with or without SSAs are supported. Insert calls are not allowed by IMS/ESA.

The NOPROT option is assumed although IMS Option does not allow access to the target segment concatenated key, if present, when symbolic pointing is used. DDATA and user data are changed if the replace call's data is different than that retrieved. If the target segment's concatenated key is needed, it must be derived from the source segment CK field in the DDATA or SUBSEQ.

IMS Option requires a UBYTES keyword to be added to the XDFLD statement in the indexed database to indicate the length of optional user data. A USTART operand to indicate the starting position of user data within the index segment is required when:

The primary index of a HIDAM database cannot be directly processed as a stand-alone database in IMS Option. If you require access to a HIDAM index as a stand-alone database, you must add a "dummy" XDFLD statement following the LCHILD for use in IMS Option. The XDFLD contains just a SRCH field naming the key of the root segment.

6.6 Managing Index Databases

Secondary index databases are zeroloaded automatically when the indexed database is zeroloaded. Trying to access a newly created database results in a GE status code, as expected.

When a database which contains source segments for an index is reorganized, the secondary index is automatically rebuilt. There is no provision to reorganize just an indexed database or just an index database. To preserve changes made to the user data component in an index database, you must make a backup of the index database files and restore them after the reorg. If you do this, the index might be corrupt in the following cases:

6.7 Using a PCB PROCSEQ

Secondary data structures are supported. This includes accessing the physical parents of the target segment (inverted structure), physical children of the target and physical children of the physical parents. These can be accessed using a single PCB or multiple PCBs in any combination. Physical parents and their children can appear to the "left" or the "right" of the physical children of the target in an inverted structure.

All updates are allowed for physical children of the target segment and for physical children of the physical parents. Replacing the target segment or physical parents of the target segment is supported.

SSAs for the target segment can specify the XDFLD name or any search fields on the target segment.

Path calls can be issued for physical parents of the target, physical children of the target and physical children of physical parents, including path update calls, where appropriate.

The boolean SSA "Independent And" is not supported - this operator is unique to secondary indices.

The INDICES operand of the SENSEG statement is not supported and is ignored. If the INDICES operand specifies the same processing sequence as the PROCSEQ operand, then ignoring the INDICES operand should not cause a problem.

6.8 Data Capture Exits

Data Capture exits allow updates to segments in a DL/I database to be passed to a Data Capture exit program. IMS/ESA's main purpose for providing these exits is to propagate data to DB2. On IMS/ESA, this can be done with an IBM product called Data Propagator/ESA. The Data Propagator product uses the Data Capture exits and propagates data to DB2. You can also write your own Data Capture exits to perform propagation or other functions.

IMS Option provides support for the Data Capture exits. The functions of the IBM Data Propagator product are not provided.

IMS Option supports these exits according to the IMS/ESA version 5 documentation, except as noted within this topic. Please see the following IMS/ESA V5 manuals for a complete description of these exits:

The following sections highlight the main Data Capture exit support in IMS Option. It also describes any restrictions and the differences in this support from that described in the IBM documentation. If you have any questions on this support, please contact your sales or technical representative. For IMS Option migration information, see the chapter Migrating from IMS Option in your Migration Cookbook.

6.8.1 Defining Data Capture Exits

The EXIT operand is supported for both the DBD and SEGM statements along with all of the EXIT options, except the LOG option. That is, the KEY, DATA, PATH and CASCADE options are supported. The suboptions for CASCADE: KEY, DATA and PATH are also supported. Data Capture log records (the LOG option) are not written to disk and thus are not available for asynchronous processing.

A maximum of nine different exit routines can be specified for any one segment. An error message is issued when compiling the DBD if more than nine are defined. There is no restriction on the total number of Data Capture exits defined for all segments in a DBD.

A maximum of 256 exit routines can be active within one IMS Option Application Region. An exit becomes active when it is called when its corresponding database segment is updated. This means that you can define any number of exits in the DBDs referenced by PSBs, however, updates to segments cannot cause more than 256 exits to be called.

The DBD statement's VERSION operand is supported and its value is pointed to by the XPCB parameter block. The &SYSDATE and &SYSTIME substitutable variables are also supported. The maximum length of the VERSION value is 128 bytes (after any substitution). If no VERSION operand is specified, a default 13-byte date-time stamp is generated.

6.8.2 Using Data Capture Exits

All fields in the XPCB and XSDB parameter blocks are supported. The appropriate actions for all XPCB return codes are supported. In addition, XPCB return codes of 8 or greater, have a descriptive message written to the IMS System Log.

Exits written in COBOL and Assembler are supported. If the exit program is compiled for debugging, it is shown by the respective debugger when the exit is called by IMS Option.

Data Capture exits are called from all IMS Option Application Region types. This includes BMP and DLI regions as well as CICS and the IMS Option Dynamic Database Attach (DDBA) region type.

The rules for the calling sequence of exits are followed. This includes calling the exit multiple times, if necessary for path calls, in a top-down order. Exits are called in a bottom-up sequence, for cascaded deletes.

Databases involved in logical relationships are supported. Segment deletes can cascade across a maximum of 32 nested hierarchical relationships and up to a maximum of 99 segment levels.

Data Capture exit programs can make DL/I calls to any PCB defined in the currently active PSB. If you make calls to PCBs other than the IO PCB or the current DB PCB, you need to change your exit program or the IMS2ASM 'glue module' to get addressability to the desired PCB.

Unlike IMS/ESA, IMS Option does not perform before- and after-image segment compare during replace operations. Replace calls always cause the segment to be updated, even if the data was not changed. Thus, Data Capture exits are always called for a replace call, whether or not the data was modified.

6.8.3 Enabling the Exits in IMS Option

You do not have to compile or assemble all of the exits defined in your DBDs. You only need to download the exits that you need for your application. If a specific exit program is not found, it is ignored and a message is written to the IMS System Log. IMS Option continues as if the exit were not defined in the DBD.

To enable the use of Data Capture exits, you must set the IMS System Properties dialog box setting to indicate the language in which your exits are written. This setting is shared with Secondary Index Sparse exits and it is called Enable Secondary Index Sparse and Data Capture exits - Language. For information about setting IMS system properties, see the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click IMS Option, Working with IMS Projects, How to, Configure an IMS Project.

Data Capture exits written in Assembler require the following additional steps:

  1. You must prepare the ims2asm.mlc Assembler glue module. See the ims2asm.mlc sample program for details

  2. You must ensure that the CALLCAP equate statement is set in ims2asm.mlc to enable it to call your Data Capture exits. See the ims2asm.mlc sample program for instructions.

6.9 Logical Databases

Logical database support is implemented by the use of pointers in the physical databases which define the relationships and with program logic within IMS Option. In other words, logical databases map to their respective physical databases in a similar manner to IMS/ESA. There are no additional disk storage requirements for logical databases other than the additional pointers and counters.

All types of logical databases and logical relationships are supported. These are:

Logical parents:

Logical children:

Concatenated segments:

6.10 Bidirectional Logical Databases

Fixed Intersection Data (FID) for physically paired segments must be equal lengths. Different length FIDs would work in most cases although it would not be an ordinary definition as some of the FID would be "lost" when updates occur from both sides.

Variable Intersection Data (VID) can be accessed from either side of a paired relationship.

The RULES specification for non-uniquely keyed paired logical children cannot be overridden by use of the F or L command code in an SSA.

Virtual logical children can contain multiple (scattered) sequence fields.

Bidirectional pairings must be explicitly defined using two logical child segment definitions. The use of PAIR=DBLE on a logical parent's LCHILD statement does not establish a pointer from the logical parent to the logical child. You need explicitly to define a virtual, logical child segment under the logical parent if you need access to the real logical child from its logical parent.

6.11 Logical RULES Support

Logical Insert and Replace RULES are fully supported.

The logical parent Logical delete rule is supported but the logical parent is not available from the logical path once deleted. Both the Virtual and Physical logical parent delete RULES are processed as if Logical delete is specified. For the Physical delete rule, no DX status code is issued for violations of the rule.

The logical child delete RULES are supported except that no DX status code is issued for violating the RULES and a logical child is not available from the logical path after it is deleted. In general, the delete processing issues a physical delete for a logical child and is allowed from any path. When deleted, it is physically removed, all logical relationships are broken and any paired segment is deleted.

6.12 Logical Structures

A concatenated segment can be used to cross a hierarchical boundary. Crossing a boundary is accessing a physical parent or child of the logical parent segment in the concatenated segment. If the logical parent is defined in the same physical database as the logical child, it is a recursive crossing. It is considered recursive even if the logical parent is not a physical parent of the logical child. Once a hierarchy is crossed, you can cross into other hierarchies recursively or non-recursively.

The logical databases resulting from logical child and parent definitions can become very complicated. You can define and access any combination of these three "child groups" under a concatenated segment:

These child groups can be listed in any order under a concatenated segment. For example, the logical parent's physical children can be defined "on the left" with VID "on the right" or they can be in the reverse order.

Some of the logical parent's physical parents can be logical children. This occurs when a VID segment is also a logical parent. Accessing a logical child using the physical parent path is known as the Third Access Path. If this logical child is defined as a concatenated segment, it can have its own child groups, including its physical parents.

All of these child groups and paths can be accessed in one logical DBD and one PCB or can be defined in multiple DBDs and/or PCBs. A PCB does not have to reference all of the SEGMs.

6.13 PROCSEQ with Logical Databases

The PCB PROCSEQ operand can be used with logical databases.

The logical DBD can be any type of supported logical relationship, for example, concatenated segments or crossing of boundaries. All of the functionality and restrictions which apply individually to secondary indexes and logical databases also apply when combining them.

The target segment for the index can be at the physical root level in the database or any level below the root. The logical DBD SEGM order can reflect the physical database or the secondary processing sequence. A logical DBD describes the secondary processing sequence when the root in the logical DBD is the target segment for the index. If it describes the physical database, the PCB SENSEG definitions define the secondary processing sequence. If the logical DBD describes the secondary data structure, the PCB must use the same sequence but can omit segments.

6.14 Loading Logical Databases

Either of the IMSDBU or DBUTIL utilities can be used to load databases containing logical children:

Loading logical databases using DL/I calls is more complicated than using IMSDBU. You might need to do this in special circumstancesif, for example, your IMS/ESA data management tools require the use of a logical DBD for extracting data.

6.15 Fast Path DEDBs

DEDBs are supported similar to a Full Function database with the DEDB features included.

Sequential dependent segments (SDEPs) are supported. These can be accessed in LIFO order chained from their parents. They can be unloaded using the IMSDBU utility with a date/time stamp from when it was inserted. This unloaded file can then be sorted to provide SDEPs in chronological order to supply functional equivalency to the sequential dependent scan utility of IMS/ESA. There is no limit to the number of SDEPs which can be inserted.

The processing option of "P" is not required to perform path calls for DEDBs. The processing option of "P" does not cause a GC status code to be issued when crossing a Unit of Work boundary.

Multiple AREAs are not supported. All segments randomize to a single area. This also means that the DL/I status codes related to AREA availability are not supported. You can test these status codes using Examine on the Debug menu.

There is no support for subset pointers. A warning message is issued during DBDGEN upon encountering subset pointer definitions.

6.16 DEDB POS Calls

All three of the POS calls are supported. That is, locate a specific sequential dependent, locate the last inserted sequential dependent and identify free space. The I/O area returned for a successful POS call is always the same and contains the following values:

These values can be easily changed to any desired value by using the Debug menu's Examine command.

6.17 Fast Path MSDBs

The four MSDB types of terminal-related fixed, terminal-related dynamic, nonterminal-related with terminal keys and nonterminal-related without terminal keys are supported.

The maximum length of the segment is 32,000 bytes. The maximum length of a key field is 240 bytes.

The name of the owning terminal is specified in the Current LTERM field on the TM/MFS morepage of the IMS System Properties dialog box. Updates can be issued to terminal-related MSDBs only by the owning terminal. Retrieval calls can be issued by any LTERM. Use of an SSA which specifies "*MYLTERM" retrieves the owned segment.

Calls issued which violate the rules for MSDBs result in the appropriate status code. For example, an insert or delete call issued for a nonterminal-related MSDB results in an FC status code.

SSAs which name a field defined as HEX (TYPE=H in the DBD) are supported and processed as a hex value.

For inserts and deletes to terminal-related dynamic MSDBs, inserts actually insert a segment and deletes actually delete them. There is no free segment pool: in other words, the free segment pool is pre-defined and is theoretically infinite, limited only by the amount of available disk space.

The sequence of the segments for GN calls is always in a key sequence. For terminal-relateds and nonterminal-related with LTERM keys, the "key" for this purpose is the LTERM name.

The sequence of the segments for GN calls is always in a key sequence. For terminal related MSDBs and non-terminal related MSDBs with LTERM keys, the key for this purpose is the LTERM name.

The commit strategy for MSDB is not implemented. All update calls are immediately applied to the database. Thus, for example, a call sequence of GHU, REPL and GHU causes the second GHU to retrieve the updated segment and not the same segment as the first GHU retrieved.

MSDB segments are actually stored on the disk drive just as if it were a Full Function or DEDB database. They must be zeroloaded before being used. The database data files are named the same as other database types.

6.18 MSDB FLD Calls

The FLD/VERIFY and FLD/CHANGE calls are supported as described in this section.

The FLD call appears in the DLI call trace facility and FSA syntax errors produce Trace Help messages, when Trace is active.

FLD calls are only supported for non-terminal related MSDBs - with or without LTERM keys.

Changes made by a FLD CHANGE are applied to the database segment immediately and are not reprocessed when a syncpoint is reached.

FLD calls are supported by DBUTIL. The FSA is entered in the I/O area of the interactive screen or as an "IO" control card when using a control card data set.

A maximum of 63 FSAs can be specified in one I/O area in a FLD call. The maximum length of an FSA is 8,192 bytes.

The maximum length of a character field is 256 bytes. The maximum number of hex characters is 512 which results in a field of 256 bytes. The maximum length of a packed field is nine bytes. Exceeding packed field length does not produce an error status and unpredictable results occur if used in a FLD/VERIFY or FLD/CHANGE.

The FLD/VERIFY has complete support for all field types (C, X, P, H and F) with complete editing support. The FLD/CHANGE call has complete support for field types C and X.

The FLD/CHANGE call supports the "=" operation for field types P, H and F. For this operation, the data is applied to the database exactly as it appears in the FSA field value. For packed fields, the data is moved only if the field value contains valid packed data and the sign must be either "C", "D" or "F".

The FLD/CHANGE call support for the "+" and "-" operations for packed fields is handled by moving the database field value and the FSA field value to internal packed fields of length 9. Their signs are changed specifically to "C" or "D" for positive and negative respectively. The math operation is then carried out which always results in a sign of "C" for positive and "D" for negative. If the result is positive and the FSA field value had originally specified a sign of "F" (COBOL's sign when the PIC clause is unsigned), then the resulting sign is changed to "F" from "C". No other changes to the sign are made. This result is then applied to the database. The numeric overflow status is returned when either:

The FLD/CHANGE call support for the "+" and "-" operations for binary fields is algebraic. That is, the most significant bit of the half- or full-word is a sign bit to indicate a positive or negative number. For example, adding +10 to a binary field which contained -2 results in the field containing +8 and a field with the high order bit on tests lower than a field with the high order bit off (negative less than positive).

The FSA status codes which are supported are:

FSA Status Code
A Operator invalid
Arithmetic operation requires numeric field
B Connector invalid (data wrong size)
C Cannot change key field
D Verify unsuccessful
E Hex field contains invalid character
Packed field contains invalid data or is too long
G Database contains invalid packed data or sign
Addition or subtraction caused numeric overflow

6.19 Field Level Sensitivity

Supported features:

Unsupported features:

6.20 HDAM Considerations

The randomizer for HDAM DBDs is not selectable. IMS Option always uses its own sequential randomizer. That is, root segments are returned in key sequence when doing unqualified sequential retrieval.

When an SSA qualification for a root segment in an HDAM database specifies boolean operators or uses a relational operator other than 'equal', a warning message is issued that this call has unpredictable results when the HDAM randomizer puts segments in a sequence other than key sequence (that is, it is not a purely sequential randomizer). Since IMS Option always puts HDAM root segments in key sequence, these calls have predictable results. You need to review whether the mainframe randomizer you use is sequential or not. If it is not, then review the DL/I call. If it is, then you can ignore this message. The message is displayed on the screen or in the DL/I call trace data set depending on the options currently in effect for the DL/I call trace output selection. You must enable the Configuration setting Help message for PCB status codes for this message to be displayed.

6.21 GSAM Considerations

You can use GSAM databases with the IMS Option of Mainframe Express in just the same way as you do with your IMS/ESA system. Access to your GSAM database data is controlled by JCL DD statements.

The name specified in the JCL DD statement DSN parameter is used to look up the actual filename in the system catalog. The GSAM data file properties, such as sequential or VSAM, are also defined in the system catalog.

The DD1 and DD2 parameters of the DATASET statement on the GSAM DBD specify the dd-names used.

GSAM data can reside on a:

Concatenated DD statements are supported for input to GSAM databases. If specified, the concatenated files can be from any of the locations in the above list.

You can find GSAM limitations in the section Unsupported DB Features of the chapter Product Summary.

Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.