Utility Statements › MAINTAIN INDEX › Usage

Usage

How to submit the MAINTAIN INDEX utility

You submit the MAINTAIN INDEX utility only through the batch command facility. You must run the batch command facility in local mode.

All areas affected by the index must be varied offline.

When to use MAINTAIN INDEX

Use the MAINTAIN INDEX utility to process indexes in a non-SQL-defined database. This includes indexes associated with individual ASF tables and ASF indexes that reside in the IDMSR-AREA; specify the IDMSRSSA subschema.

When not to use MAINTAIN INDEX

To process indexes in an SQL-defined database, use the LOAD or BUILD utility.

Multiple operations in one execution

You can perform maintenance on multiple indexes in one execution of the MAINTAIN INDEX utility. However, you should perform only one operation on an index within the same execution. For example, do not DELETE and BUILD the same index at the same time.

Subschema reentrancy

If the subschemas specified in the MAINTAIN INDEX utility reside in a load library, they must not be linked with the reentrant attribute, nor can they reside in the LPA (OS) or SVA (DOS). If the subschemas are loaded from a dictionary load area, these issues are not relevant.

BUILD-option with non-MA indexes

Specifying the BUILD-option will connect every potential member record to the system-owned index. Therefore, if the index is not MANDATORY AUTOMATIC and there are occurrences of the member record that should not participate in the index, do not use the BUILD-option. Instead, use the REBUILD FROM MEMBERS-option.

Rebuilding indexes

When rebuilding an index, MAINTAIN INDEX might need a subschema that describes the old index, the new index, or both depending on the changes (if any) being made to the index structure. The following table specifies the REBUILD option and subschema to use based on the function that the rebuild operation is performing:

Where there is a choice between using FROM INDEX or FROM MEMBERS, consider the following:

• FROM INDEX is generally more efficient because only the index structure is read, rather than every member record occurrence
• FROM INDEX preserves the order of entries with duplicate key values; FROM MEMBERS or FROM ALLROWS rebuilds the index with duplicate entries in db-key sequence
• FROM INDEX requires that the index exist and be readable

Changing symbolic index values

The following values can be supplied as a symbolic index parameter in the physical area definition:

• The number of entries in an SR8 (INDEX BLOCK CONTAINS)
• The number of pages bottom-level SR8s are displaced from top-level SR8s (DISPLACEMENT)

If these values are changed in the physical definition, you can (if desired) reorganize the index to reflect the new values by rebuilding it using a DMCL containing the updated segment definition.

Changing subarea page range

The page range in which a system-owned index resides can be specified by using a symbolic subarea parameter in the physical area definition. If this value is changed, execute MAINTAIN INDEX twice:

• The first execution must use a DMCL with the old values for the symbolic parameters and specify STEP IDMSTABX to indicate that only the first step of index maintenance is to be performed.
• The second execution must use a new DMCL (with the same name as the old DMCL) and specify FROM SORT3 to indicate that all remaining steps of index maintenance are to be performed.

To ensure that the correct DMCL is used in each case, you can either change load libraries or rename the new DMCL to have the same name as the old DMCL.

Adding or removing indexes

If adding or removing a linked system-owned index or a user-owned index set, you must use RESTRUCTURE to add or remove index and optional owner pointers in the member record.

Sorted indexes

Adding, removing, or changing the sort key of a sorted index (system- or user-owned) may change the control length of the record. If it does, and the record is compressed or variable in length, you must also use RESTRUCTURE to adjust the control length of the record in the database.

Duplicate index entries

When building an index (or rebuilding an index with the FROM ALLROWS or MEMBERS option), MAINTAIN INDEX stores duplicate index entries in the order in which the corresponding member record occurrences exist in the database (that is, in db-key sequence). When rebuilding an index with the FROM INDEX option, the order of duplicate index entries is maintained in the rebuilt index.

SORTEXIT and FROM/STEP

When using the FROM and STEP options with the SORTEXIT option, each pair of SORTn and DBLx steps are considered to be one step. If either half of the SORTn/DBLx is specified on a FROM or STEP option, processing will start with the SORTn step and the DBLx step will also be executed. For example:

• FROM IDMSDBL3 will start with step SORT3 and will continue to the end.
• STEP SORT3 will run steps SORT3 and IDMSDBL3.

SORTEXIT/REUSE WORKFILE restart considerations

Since SORTEXIT combines each SORTn step with the DBLx step that follows it, if a failure occurs in the DBLx step, a restart (if a restart is possible) must begin with the sort step and the input to the step will be resorted. Non-SORTEXIT mode will take longer to run but can be restarted after the sort in this case. Therefore, if restart time is more critical than normal runtime do not run the utility as a sortexit.

If the REUSE WORKFILE option is used with SORTEXIT, some input workfiles will be used as output files in the same step. Therefore if these two options are used together and a failure occurs, the utility must be restarted from the beginning.

Workfile Considerations for restarting a failed MAINTAIN INDEX

If the MAINTAIN INDEX command fails, depending on the reason for failure, restart the command at the failing step using the "FROM step-name" syntax. You can only restart a step if the input files to that step are intact and valid.

To prepare for a possible restart when running a one-step MAINTAIN INDEX, the Intermediate work files should have a disposition that preserves the data set in the event of an abend, for example, "DISP=(NEW,CATLG,CATLG)."

To restart MAINTAIN INDEX at a particular step, the input files to that step must have a disposition to specify that the files already exist, for example, "DISP=OLD".

To determine which files were input to a given step, see the "Intermediate Work File" tables under "JCL Considerations". Partially created output files should be deleted before restarting the job, and the original disposition should be used in the restart job, for example, "DISP=(NEW,CATLG,CATLG)".

The SYSPCH file contains sort parm information for sort steps. It is an output file to IDMSDBLn steps but is not read unless restarting or running in step mode. So during a normal run the SYSPCH file should be treated as a normal output file, for example, "DISP=(NEW,CATLG,CATLG)." However, restarting is not as straightforward. If the previous job failed in an IDMSDBLx step, the SYSPCH file was an output file and should be deleted before restarting. But if the failure occurred in a SORTx step, the contents of the SYSPCH file should contain the same values that were input to the SORTx step. In this case the SYSPCH file should be preserved and defined as a SYS001 input file to the restart step.

When the SORTEXIT option is used, the SORTx and IDMSDBLx steps are combined. If a failure occurs in this mode, the SYSPCH file should normally be preserved and used as a SYS001 input file to the restart. However, there is a small window at the end of a IDMSDBLx step where the SYSPCH file is opened for output and new SORT parameters are written. If the job fails at this point, the entire SORTx/IDMSDBLx step must be restarted, but the SYSPCH file will not be valid as a SYS001 input file. In this case, the sort parameters must be recreated by hand or the job must be restarted at an earlier IDMSDBLx step if possible. One way to avoid this situation is to run in step mode when running SORTEXIT mode.

The RELDCTL data set is always an input file to the first step of a MAINTAIN INDEX whether being restarted or not.

The steps of MAINTAIN INDEX

The MAINTAIN INDEX utility consists of the following steps, which you can run separately or as a single operation:

Each step has input and output

Note: This table describes the input and output files when you execute MAINTAIN INDEX without the SORTEXIT and REUSE options. For the impact of running MAINTAIN INDEX with these options, see "JCL Considerations" later in this section.

Sort output after each step

If you execute the MAINTAIN INDEX utility a step at a time, you must use the sort parameters to sort the contents of the intermediate work files. You can use your own sort program or IDMSSORT.

Sort the intermediate work files as follows:

Note: If running in step mode, the sort parameters generated by IDMSTABX and IDMSDBL3 are not sufficient for stand-alone sort programs running under z/VSE. If you want to use your own sort program, you must add "WORK=" parameters to specify more than one sort work file.

Maintaining indexes

General procedure

In general, the procedure for changing indexes is as follows:

Step 1: Create a new schema and global subschema, if necessary

Note: These steps are not necessary if the only change being made is to the value of symbolic parameters associated with the index.

1. Create a new schema that is identical to the original schema.
2. Create a global subschema for the new schema with a name that is different from that of any other subschema in the dictionary. Include in the subschema all areas, records, and sets associated with the schema.
3. Make the necessary changes to the new schema definition.
4. Validate the schema.
5. Regenerate the global subschema.

Step 2: Modify the segment and DMCL if necessary

Note: Segment and DMCL modification is necessary only if adding or changing the values of symbolic index or subarea parameters associated with the index or adding a new area in which to store the index.

1. Make the appropriate changes in the segment definition. Make sure that subareas and other symbolics are defined appropriately.
2. Generate, punch, and link all DMCLs containing the altered segment.

Step 3: Make changes to the index

1. Backup the area(s).
2. Use the MAINTAIN INDEX utility to change a system-owned index.
3. Use a user-written program in conjunction with IDMSTBLU and the MAINTAIN INDEX utility to change a user-owned index.
4. Verify the change with IDMSDBAN or a retrieval program, CA OLQ or CA Culprit.
5. Back up the altered area(s).

Step 4: Complete the change

If schema changes were necessary:

1. Update the original schema in the same way that the copy was changed.
2. Regenerate all subschemas associated with the original schema that are affected by the change.
3. Recompile all access modules affected by the change, using the ALTER ACCESS MODULE statement with the REPLACE ALL option.

As appropriate, make the new subschemas, DMCL(s), and area(s) available to your runtime environment.

Maintaining user-owned indexes

To build, rebuild, or delete user-owned indexes, you must write a program which calls IDMSTBLU and passes information about the indexes to be operated on and the owner and member record occurrences participating in the indexes.

Once the program executes, complete the operation by executing the MAINTAIN INDEX utility, specifying FROM SORT3. Use the SYSPCH, SYS002, and RELDCTL work files generated by IDMSTBLU as input to the MAINTAIN INDEX utility as SYS001, SYS003, and RELDCTL respectively.

Creating the user-written program

The following considerations apply when writing your program:

1. Include in your program the following descriptors:
   • The global subschema describing the index
   • The owner and member record descriptions
   • Descriptions of the IDMSTBLU parameters outlined next
2. The general logic of the program should:
   • As the first call to IDMSTBLU, pass the subschema descriptor:

     CALL IDMSTBLU USING SUBSCTYP.
     

   • For each occurrence of a user-owned indexed set, identify the owner by passing an owner descriptor:

     CALL IDMSTBLU USING OWNERTYP.
     

     Note: If more than one set per owner is to be processed during a single execution of the user-written program, multiple owner descriptors must be passed to IDMSTBLU. For example, to rebuild two indexed sets in which REC-A is owner and REC-B is member, as the second and third calls to IDMSTBLU:

     CALL IDMSTBLU USING OWNERTYP.
                           :..........+2 REBUILD IXSET-1 REC-A's dbkey
     CALL IDMSTBLU USING OWNERTYP.
                           :..........+2 REBUILD IXSET-2 REC-A's dbkey
     

     In this example, subsequent REC-B member descriptors passed to IDMSTBLU should contain two occurrences of set name and owner dbkey information (one occurrence for IXSET-1 and one occurrence for IXSET-2).

   • For each record that participates as a member of an indexed set to be processed, pass a member descriptor and the member record occurrence:

     CALL IDMSTBLU USING MEMBERTYP member-record.
     

   • As the last call to IDMSTBLU, pass the end-of-file descriptor:

     CALL IDMSTBLU USING EOFTYP.
     

   The owner and member information can be obtained either from the database or a user input file.

   As information is passed to IDMSTBLU, it creates work files needed to build, rebuild, or drop the specified indexed sets.

3. Link edit your program with IDMSTBLU. Also, link it with IDMS if your program binds a rununit.

IDMSTBLU parameters

Subschema descriptor

The subschema descriptor identifies the subschema and segment that contain the indexed sets. If you are rebuilding an index and changing its characteristics, the identified subschema and segment must describe the new index definition.

The subschema descriptor also identifies the name of the DMCL to be used during MAINTAIN INDEX execution. It must be the same as the name of the DMCL specified in the SYSIDMS parameter file used to execute the MAINTAIN INDEX utility.

For example:

01 SUBSCTYP.
   02  FILLER PIC S9(8) COMP VALUE +1.
   02  ssnm   PIC X(8) VALUE 'EMPSS01'.
   02  segnm  PIC X(8) VALUE 'EMPSEG'.
   02  dmclnm PIC X(8) VALUE 'NEWDMCL'.

Owner descriptor

The owner descriptor describes each record that participates as an owner in an indexed set to be processed:

For example:

01   OWNERTYP.
     02  FILLER PIC S9(8) COMP VALUE +2.
     02  OFUNC  PIC X(8) VALUE SPACES.
     02  OSET   PIC X(16) VALUE SPACES.
     02  ODBKEY PIC S9(8) COMP SYNC VALUE +0.

Member descriptor

The member descriptor describes each record that participates as a member in one or more indexed sets to be processed:

Repeat the following two fields once for every indexed set in which the record participates as a member:

For example, the following illustrates a member that participates in user-owned indexed sets:

01   MEMBRTYP.
     02  FILLER PIC S9(8) COMP VALUE +3.
     02  MREC   PIC X(16) VALUE SPACES.
     02  MDBKEY PIC S9(8) COMP SYNC VALUE +0.
     02  MSETS  PIC S9(8) COMP VALUE +2.
     02  MSET-INFO OCCURS n TIMES.
         04  MSET    PIC X(16).
         04  MODBKEY PIC S9(8) COMP SYNC.

Note: n represents the number of indexed sets that are actually being processed (for example, those for which an owner descriptor was previously passed to IDMSTBLU and in which MREC participates as a member).

Database record descriptor

The database record descriptor describes each member record type in an indexed set to be processed:

For example:

01   COPY IDMS RECORD EMPLOYEE.
01   COPY IDMS RECORD SKILL.
01   COPY IDMS RECORD EXPERTISE.
01   COPY IDMS RECORD JOB.

End-of-file descriptor

The end-of-file descriptor serves as an end-of-file indicator:

For example:

01   EOFTYP.
     02  FILLER PIC S9(8) COMP VALUE -1.