Adding or modifying a sparse exit routine

If the routine specifies that a particular record should be suppressed, a pointer record is not placed in the PFX index.

This feature is useful because you might not always want to include a pointer from the PFX index to every record in the primary DEDB. For example, you might want to index fields that sometimes contain blanks or zeros. Because these values have no significant meaning, you can code a sparse exit routine to exclude them.

BMC does not recommend coding an exit routine that multiple primary DEDBs share. Sharing an exit routine requires cycling IMS to load a new (changed) copy of a shared exit routine. Therefore, using IMS Online Change to reload an ACB for any primary DEDB that shares the exit will reload the original, unchanged exit routine. In contrast, if the exit routine is not shared, IMS Online Change will load the new (changed) exit when the primary ACB is reloaded.

Fast Path Indexer/EP uses the sparse exit routine in the same way that IMS uses a PFX index database maintenance exit routine. If you need to add an exit routine to Fast Path Indexer/EP, follow the same coding requirements described in the IBM IMS EXIT Routine Reference Manual.

Fast Path Indexer/EP provides the following methods for coding a sparse exit routine:

• using a single-character value comparison between the NULLVAL character and the pointer segment value
• calling a user-written exit to determine whether the pointer segment should be suppressed

Single-character method

The first type of PFX index sparse maintenance exit routine uses the NULLVAL keyword during the registration process.

The value associated to NULLVAL is a single character; for example: NULLVAL=C' '. Fast Path Indexer/EP compares this single-character value to the portion of the source segment that will be used as the index key value. When the product performs a comparison between the single-character value and the single-source or multiple-source segment value, it looks for a match between the two values. If a match exists, Fast Path Indexer/EP excludes the pointer segment from the PFX index.

User-written method

A single-character comparison might not be sufficient to exclude all unwanted pointer segments from the PFX index.

The second type of sparse exit routine lets you write your own user exit. This exit examines all pointer segments in the primary DEDB and dynamically excludes specific pointer segments from the PFX index.

You specify this user-written exit during the index registration process by coding the EXTRTN keyword on the PFXXDFLD macro. For more information about the EXTRTN keyword, see PFXXDFLD keywords.

Maintenance functions

The sparse exit routine is called during the index maintenance for the functions listed in the following table.

Coding requirements

When you code a sparse exit routine for Fast Path Indexer/EP, you must follow the same coding conventions that IBM requires. These conventions are detailed in the IBM IMS/ESA Customization Guide: Database.

For information about a secondary index database maintenance exit routine, see the IBM IMS/ESA Database Administration Guide.

You must comply with the following requirements to code a sparse exit routine:

• Ignore the first parameter of the sparse index in batch. If you run a sparse exit routine with any of the Fast Path Indexer/EP index commands (BUILD, VERIFY or RESYNC), the first keyword (PST) of the sparse index is not available; therefore, PST should not be used.
• You must use AMODE=31 and RMODE=ANY when you add an index sparse maintenance exit routine.
• Use reentrant and reusable link attributes. Because you load the sparse exit routine into IMS common service area (CSA) or extended CSA (ECSA), you must link-edit the routine with reentrant (RENT) and reusable (REUS) attributes.

• Use register settings at entry to exit. Fast Path Indexer/EP uses standard linkage conventions with pre-chained save areas. At entry to the exit, the registers are set as shown in the following table.

  Register	Setting
  1	IMS PST address The PST address is not available in batch build.
  2	Index segment address
  3	Index maintenance exit parameter list address
  4	Index source segment address
  13	Pre-chained save area address
  14	Return address
  15	Entry address See Parameter list for user-written exit for the parameters passed to this register.

• The parameters listed in the following table are passed in register 3 to the sparse exit routine.

  Offset	Length	Field Name
  +0	8	Target segment name
  +8	8	PFXXDFLD name
  +16	8	Exit routine name
  +24	4	Exit entry point address
  +28	2	Exit parameter length

• Use register settings at time of return. All registers should be returned as they were at entry (except register 15). Register 15 should contain the values listed in the following table.

  Register 15	Setting
  Equal to 0	Continue to index this segment.
  Not equal to 0	Do not index this segment.

• Use the index segment format. The index segment entry is built in PFX internal format for SHISAM or HISAM indexes, and has the format shown the following figures.
  

  Structure for a compact PFX index format for user-written exit
  

  
  

  Warning

  Do not modify data under any circumstances. Modification of data might result in unpredictable results or abnormal termination.

Applying maintenance

If you add or modify a sparse exit routine, perform the following steps before using Fast Path Indexer/EP again:

1. Code the sparse exit routine.
2. Modify the primary DBD.To add the sparse exit routine, include the EXTRTN keyword on the PFXXDFLD macro statement. This macro statement resides on the primary DBD. For more information about the EXTRTN keyword, see PFXXDFLD keywords.
3. Run IMS DBDGEN to update the primary DBD to the DBDLIB.
4. Run PFXAGEN to update the ACBLIB and the PFXLIB.
5. Complete this step if the primary DEDB is offline (but skip to step 6 if the DEDB is online):
   1. Execute the BUILD command provided by the Fast Path Indexer/EP product to extract data from the primary DEDB and build the PFX index.Input to the BUILD command can be either the area data sets or XSCAN-created data sets. You can use the BUILD command to customize the index build process, including specific areas within the primary DEDB as well as the PFX index itself.
   2. Refresh the control blocks in the control region.
6. Complete this step if the primary DEDB is online:
   1. Refresh the control blocks in the control region.
   2. Execute the RESYNC command provided by the Fast Path Indexer/EP product to resynchronize the PFX index with its associated primary DEDB. For more information, see Index-validation-utilities.
7. Refresh the control blocks in the control region.Use your standard migration procedures to stage your new ACBLIB and PFXLIB to the active/inactive ACBLIBx/PFXLIBx libraries:
   • If you are staging ACBs to ACBLIBA, stage PFXLIB to PFXLIBA.
   • If you are staging ACBs to ACBLIBB, stage PFXLIB to PFXLIBB.
8. When you complete your migration procedures, determine whether IMS is active:
   • If IMS is active, you can perform an ACB online change to refresh the active ACBLIB. PFX automatically uses the active PFXLIB x that matches ACBLIB x.
   • If IMS is not active, issue a START command and bring in the new control blocks.