CREATE-FILE

Creates a file in the current, or a specified, account.

Syntax

CREATE-FILE file-name {m1{,s1} {m2{,s2}}} {(options}

to create a dictionary and a default data section;

or

CREATE-FILE file-name,data-section-name {m2{,s2}} {(options}

to create a named data section for an existing file;

or

CREATE-FILE DICT file-name {m1{,s1}} {(options}

to create a dictionary, but no data section.

Command class

TCL-I command

Syntax elements

If neither m1 nor m2 are provided, automatic file sizing is assumed.

Options

A Specifies that the data section should be configured for automatic file sizing. Use this option to create an automatically sized data section if automatic file sizing is not selected (see Comments).

C Specifies that the data in the file should be encrypted. You are prompted for the id of an encryption key in the REK file.

Note that encryption can be specified as the default with the ENCRYPT-SET command.

E Specifies that the file is Recoverable (Rapid Recovery). Takes precedence over the L option.

I Prompts for the account name on which the file is to be created.

L Suppresses the transaction logging tag (L) in attribute 1 of the file definition item, but logs the file creation.

S Suppresses the creation of a self-referencing Q-pointer in a single level file.

U Creates a file with case-sensitive item-ids.

W Creates a file with case-insensitive item-ids. Only valid if the database is enabled for item-id case-insensitivity.

X Suppresses the logging of the file creation as well as suppressing the transaction logging tag (L) in attribute 1 of the file definition item.

(For more information on the logging status of files, please refer to Resilience.)

Z Specifies that the file should be created on the local database and should not be automatically sized or encrypted. Overrides the AutoFileSize database configuration parameter, and the effects of the AFS-SET, FDB-SET and ENCRYPT-SET commands. See also Comments.

Restrictions

Requires SYS1 privileges.

Comments

• You can select AFS mode as the default for a database by setting the AutoFileSize configuration parameter. This parameter is normally set in the master configuration file, so that automatic file sizing will be used on new databases.

  Note

  If AFS is enabled with the AutoFileSize parameter, you cannot create a file with a modulo less than 7. If you specify a modulo less than 7, CREATE-FILE responds with the requested modulo but in fact defaults to modulo 7.

• When creating an automatically sized file, the m2 parameter sets the data section's default (initial) modulo. If this is close to the data section's optimum size, it can result in faster file population.

• Multiple data sections can be created. However, the dictionary level file must be created before you can create a data section. The default data section is created at the same time as the dictionary if the first form of the syntax listed is used.

• Because a dictionary cannot be automatically sized, if you use the default modulo for a large dictionary, it could become badly sized, resulting in poor performance. Refer to Changing the Modulo of a Dictionary for the best way of resizing a dictionary.

• To create Reality files on a foreign (SQL-based) database, use the FDB-SET command to specify the required database before executing CREATE-FILE.

  Note

  When you execute CREATE-FILE, the required foreign database must be online.

• Because the Z option suppresses automatic file sizing and encryption, if both are enabled and you want an automatically sized, unencrypted file, or an encrypted file that is not automatically sized, you must use both the Z option and the A or C option as appropriate.

• Omitting the m2 parameter (intending an automatically sized data section) and at the same time specifying the Z option (to suppress automatic file sizing) generates an error; the file is not created.

• The break key is disabled during CREATE-FILE.

• The U and W options can be used to override the default item-id case setting (set with the INSENS.CREATE.FILE environment option). See Case Sensitivity for more details.

  If both U and W are specified an error message is displayed and the file is not created.

Examples

Creating a dictionary with default data

To create the file ADDRESSES with a dictionary and default data section at the same time, enter:

CREATE-FILE ADDRESSES 7 13

ADDRESSES is the name of the dictionary and default data section name. The numbers 7 and 13 are the moduli for the dictionary and default data section, respectively.

The following messages are displayed:

[417] FILE 'ADDRESSES' CREATED.
D/CODE =DL, MODULO = 7, SEPAR = 1
[417] FILE 'ADDRESSES' CREATED.
D/CODE =DL, MODULO = 13, SEPAR = 1

Creating an automatically-sized data section

If automatic file sizing is not active, you can create the same file with the data section configured for automatic file sizing by entering:

CREATE-FILE ADDRESSES 7 13 (A

To create the same file using the default modulo settings (dictionary modulo = 1, data section modulo = 7), enter:

CREATE-FILE ADDRESSES

Because the data section modulo has been omitted, an automatically sized data section is created.

Creating a dictionary-only file

To create the dictionary-only file CUSTOMERS with a modulo of 7 enter:

CREATE-FILE DICT CUSTOMERS 7

The dictionary level file CUSTOMERS is created. A file definition item CUSTOMERS is placed in the MD with item-id CUSTOMERS (the same as if you create a two-level file).

A data level descriptor is not placed in the dictionary level file CUSTOMERS. Instead, a Q-pointer is placed in the dictionary CUSTOMERS that points back to itself. This makes it possible to access the dictionary with LIST CUSTOMERS or EDIT CUSTOMERS.

Creating a data section

To create the data section CUSTOMERS after you have created the dictionary, enter:

CREATE-FILE CUSTOMERS,CUSTOMERS 13

In this case, the default data section is created with modulo 13. You can if you wish give the data section a different name from that of the dictionary.

Creating multiple data sections

To create two more data sections RECEIPTS and INVOICES, the following commands are entered and messages displayed:

:CREATE-FILE CUSTOMERS,RECEIPTS 7

[417] FILE 'RECEIPTS' CREATED.
D/CODE =DL, MODULO = 7, SEPAR = 1
:CREATE-FILE CUSTOMERS,INVOICES 13

[417] FILE 'INVOICES' CREATED.
D/CODE =DL, MODULO = 13, SEPAR = 1

Creating a Reality file on a foreign database

To create the Reality file CUSTOMERS on the Oracle database FINANCE, supplying a user-id of REALITY with a password of WELCOME, the following commands are entered and messages displayed:

:FDB-SET FINANCE,REALITY,WELCOME

[5426] Foreign Database active: Dsn 'FINANCE', User 'REALITY'
:CREATE-FILE CUSTOMERS

[417] File 'CUSTOMERS' created.
D code =DL, modulo = 1, separ = 1
[417] File 'CUSTOMERS' created.
D code =DL, modulo = 1, separ = 1