Macro type: type S (E form/L form/D form/C form); see "Macro types"
The CREAIX macro defines one or more secondary keys for an NK-ISAM file. Up to 30 secondary keys may be declared for one file; each must be identified by a name defined in the CREAIX macro. Each of these secondary keys can then be addressed via its name in the macros GET, GETR, GETKY and SETL, thus permitting the user to access records on the basis of secondary key values.
In order to create a secondary key, all the records in the file are first read sequentially. For each record, a triplet is formed from the index in the list of secondary keys to be created, the current secondary key itself and the current primary key. These triplets are then sorted for each secondary key, in ascending order of the secondary key values, a time stamp is added to each and they are transferred to the secondary index blocks created for this secondary key.
Secondary keys can be created only for existing NK-ISAM files, i.e. for files which have already been opened at least once with OUTPUT or OUTIN. Furthermore, there must be no duplicate primary keys in a file for which a secondary key is to be created (no DUPKEYs) and neither logical nor value flags may be defined for the file. When the macro is called, neither SHARED-UPDATE=*YES (via an ADD-FILE-LINK command), nor SHARUPD=YES (by a macro) must have been set for the NK-ISAM file, and no other user can access it while the secondary key is being set.
If the program is aborted during creation of the secondary key, the secondary key is flagged as incomplete in the control block of the file. If the user then attempts to open the file, control branches to the OPENER exit (assuming it has been defined in the program) and error code 0D84 is placed in the FCB. The file cannot be opened again until the incomplete secondary key has been deleted (and, if applicable, defined again by means of CREAIX).
For performance reasons, it is advisable not to define secondary keys for a file until it has been filled with records.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
DUPKEY
Specifies whether duplicate values may exist in different records for each secondary key to be created (KEYNAME operand).
The parentheses in this entry can be omitted if the list only contains one specification for DUPKEY. A list can only be specified for VERSION=2; for VERSION=1, only an entry without parentheses is allowed.
= YES
Default value; the same value of the secondary key may occur in more than one record in the file.
= NO
Different records in the file must not have the same value for the secondary key.
FILE = pathname
Denotes the NK-ISAM file for which a secondary key is to be created, with:
<c-string 1..54: filename 1..54>.
When the CREAIX macro is called, the file must have been opened at least once with OUTPUT or OUTIN and it must not contain duplicate primary key values, logical or value flags. The value specified for the FILE operand is ignored if the LINK operand is also specified.
Pathname means [:catid:][$userid.]filename
catid
Catalog ID: if omitted, the default catalog ID for the user ID is assumed.
userid
User ID: if omitted, the user ID in the SET-LOGON-PARAMETERS or LOGON command is assumed.
filename
Fully qualified file name.
KEYLEN = (keylen1 [,keylen2,...] )
Specifies the length of each secondary key (KEYNAME operand) to be created (in bytes). “keylen” is any whole number where 1 <= keylen <= 127.
KEYPOS and KEYLEN must be selected such that the secondary key
is completely contained in even the shortest record of the file and
lies entirely within a data block and does not extend into an overflow block.
The parentheses in this entry can be omitted if the list only contains one specification for KEYLEN. A list can only be specified for VERSION=2; for VERSION=1, only an entry without parentheses is allowed.
KEYNAME = (keyname1 [,keyname2,...] )
Specifies the name of the secondary key to be created. A maximum of 30 names may be specified in the list and it must be noted that a maximum total of 30 secondary keys can be created for an NK-ISAM file.
The name must not already have been defined for another secondary key. “keyname” may be up to eight characters long and may contain any letters or digits and the special characters “$”, “#” and “@”; it must begin with a letter or special character.
The parentheses in this entry can be omitted if the list only contains one name. A list can only be specified for VERSION=2; for VERSION=1, only an entry without parentheses is allowed.
KEYPOS = (keypos1 [,keypos2,...] )
Specifies the position within a record, of the first character of each secondary key (KEYNAME operand) to be created.
“keypos” may be any integer in the range 1 <= keypos <= 32496.
In variable-length records, the four bytes used for the record length and control field must be taken into account.
KEYPOS and KEYLEN must be selected such that the secondary key
is completely contained in even the shortest record of the file and
lies entirely within a data block and does not extend into an overflow block.
The parentheses in this entry can be omitted if the list only contains one specification for KEYPOS. A list can only be specified for VERSION=2; for VERSION=1, only an entry without parentheses is allowed.
LINK = linkname1
Specifies the link name for the file for which a secondary key is to be created. When the program is executed, an NK-ISAM file must be assigned to this link name. When CREAIX is called, this file must have been opened at least once with OUTPUT or OUTIN and it must not contain duplicate primary key values, logical flags or value flags.
“linkname1” may be up to eight characters long. If the file link name is to be accessible via the command interface, it must comply with the data type <structured_name 1..8> (see the “Commands” manual [3]).
MACID
Defines the second through fourth characters of each field name and equate generated when the macro is expanded.
Default value: | MACID = ISS |
= macid
Three-character string defining the second through fourth characters of the generated field names and equates.
PARAM
Specifies the address of the operand list; it is evaluated only if MF=E applies (see "Macro types").
= addr
Symbolic address (name) of the operand list.
= (r)
Number of the register which contains the address of the operand list. The register must be loaded with this address value before the macro is called.
PREFIX
Defines the first character of each field name and equate generated when the macro is expanded.
Default value: | PREFIX = D |
= pre
One-character prefix with which the generated field names and equates are to begin.
SORTLNK = linkname2
Specifies the file link name of a work file for the sort program. This work file is used only if there is not enough virtual address space for sorting the entries for the secondary index block.
If a work file is needed for sorting and SORTLNK was not specified, or if no file is assigned to the file link name when the program is executed, the macro creates a work file with the name DISWORK.tsn (where “tsn” is the task sequence number of the task which called the macro).
“linkname2” may be up to eight characters long and must be formed from letters, digits and special characters in accordance with the rules governing the format of file names.
VERSION
Defines the version of the generated CREAIX macro.
= 1
The “old” macro version is generated.
= 2
The version of the CREAIX macro, which is valid as of BS2000/OSD-BC V3.0, is generated.
Programming notes
The C and D forms of the macro generate field names and equates for return codes. They begin with the string DISS..., which can be modified with the PREFIX and MACID operands.
If no symbolic address is specified with the D form, the DSECT name DISCRAIX is generated, where the first character is modified by a PREFIX entry.
When the CREAIX macro is expanded, a field is created in the parameter list with the name KEY# (with the default prefix DISS or correspondingly modified by the PREFIX and MACID operands). This field contains the number of secondary indices to be created (maximum 30), supplied by the macro expansion. If, however, the parameter list is built up dynamically at program runtime, the KEY# field must be supplied explicitly by the program.
If an error occurs, the parameter list contains the index of the secondary index in the specified list with which the error occurred. In addition to this, any DMS error that occurs is also stored in the parameter list (the name of the field containing the index of the secondary index with which the error occurred is DISAERR or <xxxy>AERR depending on PREFIX and MACID)
A total of up to 30 secondary indices can be created for an NK-ISAM file. It must therefore be noted that, on the one hand, the list of names in specified in the macro for the secondary indices to be defined may not contain more than 30 elements. On the other hand, the sum of existing secondary indices and those to be created may also not exceed 30 (both cases lead to a corresponding return code).
It must be ensured that for a parameter list VERSION is consistently given a value for calls with different MF formats.
Return codes
The return codes output by the CREAIX macro are stored in the standard header of the operand list. The standard header must be defined for the CREAIX parameter list before generating the DSECT.
By default, the return codes generated with the C or D form of the macro start with the string DISS, which can be modified by specifying PREFIX (first character) and/or MACID (second through fourth characters).
Standard header: ccbbaaaa
The following code relating to execution of the CREAIX macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'bb' | X'aaaa' | Meaning |
X'00' | X'0000' | The function was executed successfully. |
X'01' | X'0001' | The operand list is not available. |
X'40' | X'0003' | The specified catalog ID does not exist. |
X'40' | X'0004' | The catalog cannot be accessed. |
X'01' | X'0005' | The operand list contains an invalid name. |
X40' | X'0006' | The specified file contains duplicate keys. |
X'40' | X'0007' | The secondary key to be created already exists. |
X'01' | X'0009' | The value specified for KEYLEN is invalid. |
X'40' | X'000A' | The specified file contains logical or value flags. |
X'20' | X'000B' | System error. |
X'40' | X'000C' | The user address space is too small. |
X'01' | X'000D' | The value specified for KEYPOS is invalid. |
X'40' | X'000E' | The control block of the file is incorrect. |
X'40' | X'000F' | A record in the specified file is too short for the secondary key to be defined |
X'40' | X'0010' | There are already 30 secondary keys defined for the file. |
X'40' | X'0011' | The file contains incomplete secondary index blocks. |
X'40' | X'0012' | The ISAM pool is overloaded. |
X'40' | X'0013' | The secondary key has already been defined with other attributes. |
X'40' | X'0014' | Interruption via CANCEL. |
X'40' | X'0015' | Interruption via BREAK. |
X'01' | X'0017' | There was no file specified in the operand list. |
X'40' | X'0018' | The file was set to SHARUPD=YES when the macro was called. |
X'40' | X0019' | The file link name is invalid. |
X'40' | X'001A' | Although DUPKEY=NO was specified, duplicate secondary key values exist in different records. |
X'40' | X'001B' | Invalid list element. |
X'40' | X'001C' | Invalid number of secondary indices in the list. |
X'40' | X'0040' | OPEN error. |
X'40' | X'0041' | CLOSE error. |
X'40' | X'0042' | An error occurred when writing the secondary index blocks. |
X'40' | X'0043' | An error occurred when reading the file. |
X'40' | X'0044' | The file is not an NK-ISAM file. |
X'40' | X'0081' | A DMS special status occurred when sorting the secondary index entries. |
X'40' | X'0082' | An internal error occurred when sorting the secondary index entries. |
X'01' | X'FFFF' | Linkage error (function not supported). |
X'02' | X'FFFF' | Linkage error (function not available). |
X'03' | X'FFFF' | Linkage error (version not supported). |
Further return codes, whose meanings are defined by conventions valid for all macros, can be found in the table in chapter "Standard header".
The calling program is terminated if one of the following errors occurs with respect to the parameter list:
the list is not assigned to the called
the list is not aligned on a word boundary
the list is write-protected.