HYPER-CREATE

Creates a hyper file by creating a hyper file definition item (H-pointer) and optionally the hyper sections.

The command prompts for the information it needs:

• A predefined data definition item for extracting hyper keys from item IDs.

• A series of hyper key values and file names to define the lookup table and the hyper sections; if a hyper section does not already exist it is created.

• An optional BIN section in which to create items that cannot otherwise be mapped by the lookup table.

Command class

TCL-I command.

Syntax

HYPER-CREATE dictionary{,data}

Syntax elements

dictionary The name of the hyper file. A dictionary of this name is created if it does not exist already.

data The data section name of the hyper file. If omitted, it defaults to the hyper file name.

Operation

First, you are reminded that a predefined data definition item to extract hyper keys from item IDs is a prerequisite.

NOTE before creating a hyper file you must have a data definition
item that can be used to extract one or more fields from an item ID.
This will be used to generate a key to be looked up in a table, which you
must supply as part of creating the hyper file, to identify which file an
item goes in.

The command then offers a series of prompts.

Enter file name to use for data definition item ?

Enter the name of the dictionary containing the data definition item. DICT is optional when specifying this.

Enter name of data definition item to be used for item ID look up ?

Enter the name of the data definition item to be used to extract hyper keys.

Do you want a table where a range of item IDs can
map to one section Y/N [N] ?

Press Return for a simple lookup table, or enter Y for a range lookup table. The type of lookup table determines how the hyper keys generated from item IDs are mapped to hyper sections.

Do you want right-aligned fields to be treated as left-aligned Y/N [N] ?

Press Return if you want right-aligned hyper keys are to be treated as numeric, or enter Y if you want them to be treated as alphanumeric (that is, including any leading zeros). This may affect how the hyper keys are mapped by the lookup file. (Answering Y here is equivalent to using the L option with the CREATE-INDEX command.)

Use hyper file as item lock container Y/N [Y] ?

Press Return if you want item locks to be associated with the hyper file, or enter N if you want them to be associated with the individual hyper sections instead.

Update lock all hyper sections Y/N [Y] ?

Press Return if you want update locks to be associated with the hyper file, or enter N if you want them to be associated with the individual hyper sections instead.

By default, associating item and update locks with the hyper file means that the hyper sections cannot be updated except though the hyper file. Conversely, answering N to these two questions means that the hyper sections can be updated independently of the hyper file.

You must now enter the lookup table used to resolve items to files.

A series of prompts follows in which you are required to supply pairs of key values and hyper section names. Each pair creates an entry in the lookup table.

Enter value to match hyper key  ?

Enter a hyper key value. If you have specified that this is a range lookup table, the value represents the (inclusive) upper bound of the range.

Enter section name [dictionary_key-value] ?

The command suggests a name for a data section within the hyper file's dictionary, based on the specified key value. Press Return to accept this name, or enter a different name. To specify a data section in another dictionary use the usual dictionary,data syntax.

If the named data section does not already exist, you are prompted to specify its modulo:

Enter the modulo to use when creating hyper-section-name [7] ?

Press Return to accept the default modulo 7, or enter the required modulo. The data section is created:

[417] File 'hyper-section-name' created.
D code =DL, modulo = mod, separ = 1

You are now prompted to specify the next key value, and so on. This continues until you press Return at the Enter value to match hyper key ? prompt, signifying that the lookup table is complete.

Add BIN section to take unidentified items Y/N [Y] ?

Press Return if you want to specify a BIN data section to hold items that are not mapped by the lookup table; enter N otherwise. If you decide to add a BIN section, the command prompts you for its name and modulo (with suggested defaults) and the BIN section is created:

Enter section name for BIN section [dictionary_BIN] ?
Enter the modulo to use when creating bin-section-name [7] ?

After these values are specified, the BIN section is created:

[417] File 'bin-section-name' created.
D code =DL, modulo = mod, separ = 1

The HYPER-CREATE command summarises what you have specified so far, including the lookup table, and gives you the opportunity to change anything:

   0) Data def: BY item-id (H
      Right justified
      Ascending
      Item-lock using Hyper File as container

File table specified as:

   1) key-value1  hyper-section-name1 
   2) key-value2  hyper-section-name2 
   3) key-value3  hyper-section-name3
      ...
   N) BIN  bin-section-name

Enter field number or A-Append, D-Delete, <RETURN>-Continue ?

Finally, when you press Return to accept the definition, the command prompts you to create the hyper file.

Create HyperFile dictionary,data using above definition Y/N [Y]: ?

Press Return to create the hyper file, or enter N to cancel.

On creating the hyper file a HYPER-VALIDATE is automatically run to verify the information given is consistent with the hyper sections.

Comments

If the optional BIN section is not specified then an attempt to write an unmapped item results in a write failure (which in general is handled poorly by DataBasic applications).