Create Database Hash (qdbcrtha) API

The Create Database Hash (qdbcrtha) API sets up the environment to enable the Run Database Hash (qdbrunha) API for a physical file that has a uniquely keyed logical file built over it. The logical file may have up to five integer keys associated with it. It is called as a function call of the form 'xx = qdbcrtha(parameter-list)', where xx is a long integer and the parameter list is as defined here. The value of xx is set to a return code as defined in the Returned Value topic.

Authorities and Locks

HASH User Space in Library QUSRSYS

*OBJOPR, *READ, and *UPDATE

Library Authority

*EXECUTE

File Authority

*OBJOPR

File Lock

*SHRNUP

Required Parameter Group

Hash name

INPUT; CHAR(10)

The hash name to be created. A unique name must be selected for each hash function that will be used on the system.

Physical file

INPUT; CHAR(10)

The name of the physical file that will be accessed using the hash.

Physical file library

INPUT; CHAR(10)

The name of the library where the physical file resides.

Logical file

INPUT; CHAR(10)

The name of the logical file that will be used to build the hash. The logical file must be uniquely keyed.

Logical file library

INPUT; CHAR(10)

The name of the library where the logical file resides.

Expression

INPUT; CHAR(64)

A valid mathematical expression that uses all the key values of a uniquely keyed logical file to determine the hash value for a particular record. The special value of *DFT can be used to allow the API to create an expression based on expected cardinalities (number of expected unique values for each key) of the keys in the logical file. Possible values are:

*DFT 

The system default expression is used (requires the use of the number of keys parameter and the key ranges parameter).

expression

The user-defined expression is used. For example: (where K1, K2, ... K5 are the names of the key fields used in the logical file)

Number of keys

INPUT; BINARY(4)

The number of keys used in the logical file.

Key ranges

INPUT; CHAR(*)

A two-value structure with up to five occurrences, containing the names of the key fields followed by the expected cardinality of the key. For more details, see Field Descriptions.

Offset		Type	Field
Dec	Hex
		CHAR(10)	Name of key
		BINARY(4)	Cardinality

Field Descriptions

Name of key. The name of the key field that is used in the logical file, which is referenced in this API. The names are for documentation purposes only.

Cardinality. The number of sequential values expected to be used for each key, respectively. The cardinality values are required if *DFT has been specified for the value of the expression parameter.

Returned Value

The returned value contains a numeric indication as to what took place during the request to add a hash function. The possible values are:

0

No errors.

-2

The physical file has multiple formats. The create database hash function cannot be completed.

-3

The logical file is not uniquely keyed. The create database hash function cannot be completed.

-4

The logical file does not correlate to the physical file specified. The create database hash function cannot be completed.

-5

The wrong number of keys was specified for the logical file. The create database hash function cannot be completed.

-99

Another error was encountered and ignored. See job log for details.

Error Messages

Only the error conditions listed in the Returned Value are monitored. No error messages other than the value of the return code parameter are returned.