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;

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

to create a named data section for an existing file;

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

to create a dictionary, but no data section.

Command Class

TCL-I command

Syntax Elements

file-name The name of the file to be created. The format of a valid file name is described in Rules for File and Data Section Names.

The file-name is the name of the dictionary level file and of the default data section created using the first form of the syntax.

data-section-name
The name of the data section to be created. The format of a valid data section name is described in Rules for File and Data Section Names.

m1 The modulo value for the dictionary level of the file. If omitted, this defaults to 1.

If you are creating a file on a foreign database, any modulo value you supply is ignored.

s1 The separation value for the dictionary level of the file. This is always set to 1; any value you specify is ignored.

m2 The modulo value for the data level of the file. If omitted, this defaults to 7 and an automatically sized data section is created (see A option). The topic Selecting the Modulo for a File describes how to choose a modulo value.

If you are creating a file on a foreign database, any modulo value you supply is ignored.

s2 The separation value for the data level of the file. This is always set to 1; any value you specify is ignored.

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).

Note: You can also create an automatically sized data section by omitting the m2 parameter.

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.

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 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.
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.
Both omiting the m2 parameter and specifying the Z option (thus suppressing automatic file sizing) generates an error; the file is not created.
The break key is disabled during CREATE-FILE.

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

Note: If automatic file sizing is active, the data section will be automatically sized, with the specified modulo (parameter m2) as the initial value.

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