Create Database Hash (qdbcrtha) API
Required Parameter Group:
1 | Hash name | Input | Char(10) |
2 | Physical file | Input | Char(10) |
3 | Physical file library | Input | Char(10) |
4 | Logical file | Input | Char(10) |
5 | Logical file library | Input | Char(10) |
6 | Expression | Input | Char(64) |
7 | Number-of-keys | Input | Binary(4) |
8 | Key ranges | Input | Char(*) |
Service Program Name: QDBCRTHA
Default Public Authority: *USE
Threadsafe: No
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.
API introduced: V4R3