Data Entry Database Resource Name hash routine (DBFLHSH0)

The IMS DEDB Resource Name hash routine is used with the Internal Resource Lock Manager (IRLM) and enables IMS and DBCTL to maintain and retrieve information about the control intervals (CIs) used by sharing subsystems.

Subsections:

About this routine

The routine performs a hashing function on the high-order three bytes of the relative byte address (RBA) representing a CI and uses the hashing result as a displacement into the hash table. If you are using IRLM in your system, the routine IMS supplies (DBFLHSH0) or the replacement routine that you write yourself is called automatically.

You can write the routine and bind it as reentrant (RENT) like the one supplied by IMS. It receives control and must return control in 31-bit addressing mode. It must be able to execute in cross-memory and TASK modes.

Important: All IMS systems sharing data must use the same hashing routine or the contents of DEDBs might be lost. IMS does not check to ensure that the routines are the same.

Attributes of the routine

The following table shows the attributes of the Data Entry Database Resource Name Hash routine.

Table 1. Data Entry Database resource name hash routine attributes
Attribute Description
IMS environments DB/DC, DBCTL
Naming convention You must name this exit routine DBFLHSH0.
Binding

After you compile and test the routine, bind it into IMS.SDFSRESL or to the library specified in the USERLIB= parameter of the IMSGEN macro statement.
Including the routine At system definition time, you must specify the name of your routine in the UHASH parameter of the DBC, FDR, or IMS procedure.

Related Reading: For details, see the topic on the UHASH and the above procedures in IMS Version 15.2 System Definition.
IMS callable services This exit is not eligible to use IMS callable services.
Sample routine location IMS.SDFSSMPL (member name DBFLHSH0)

Assembling the routine

In a multiple-IMS environment, all IMS systems must use the same hashing routine and compile that routine at the same time. If you write your own routine, you must store the compile time in the module using &SYSDATE and &SYSTIME. You also must place the address of the date and time in the first field of the routine's CSECT.

Communicating with IMS

IMS uses the entry registers and parameter list, and the exit registers to communicate with the routine.

Contents of registers on entry

On entry, the routine must save all registers using the provided save area. The registers contain the following:
Register Contents
1 Address of Extended Partition Specification Table (EPST).
13 Address of save area. The routine must not change the first three words.
14 Return address to IMS.
15 Entry point of hash routine.

Description of parameters

As input to the hashing routine, you need to supply one of the following:

  • the high-order byte of an RBA.
  • the names of both a database and an area.

The routine performs an EXCLUSIVELY OR on this input, stores it in a field, and returns a hash value result to the field EPSTRSHS.

EPST (Extended Program Specification Table) input to the routine

Register 1 points to the extended program specification table (EPST) that contains this input as follows:
Field name Content  
EPSTRSHS Hashing routine result. Only the low-order 14 bits are significant.
EPSTRSID Start of the lock name to be hashed. Lock resource name consists the following are shown in the following list:
EPSTLKID
A lock identifier. If EPSTLKID = 0, resource name is for CI. If EPSTLKID is not zero, name is for the area. 1 byte. See the following figure.
EPSTRBA
Bit 0 through 23 of RBA. 3 bytes.
EPSTDMCB
DB Number as defined by DBRC. 2 bytes.
EPSTAREA
Area number. 1 byte.
EPSTDBNM
Database name. 8 bytes.
EPSTARNM
Area name. 8 bytes.
Figure 1. Lock resource name
The lock resource name ESPT for a CI contains: EPSTLKID (X'00'), EPSTRBA, EPSTDMCB, EPSTAREA. The lock resource name ESPT for an area contains: EPSTLKID (nonzero), EPSTDBNM, EPSTARNM.

EPST DSECT

The DSECT of the extended program specification table (EPST) (name: DBFEPST), and the DEDB area control list (DMAC) (name: DBFDMAC) can be used. The DMAC address is set at the EPSTDMAA field.