Initializing files

Overview

Before you can use a newly created file, you must open and initialize it. Until you initialize the file, you do not have access to it; that is, you cannot define fields, store procedures, or perform any other file-level functions.

You can initialize a file on the command line, in a procedure, or using the FILEMGMT subsystem facility.

For an un-initialized file, issue the INITIALIZE command after the OPEN command:

Syntax

OPEN filename password with necessary privileges if file is not public IN filename INITIALIZE

This topic provides additional information about using INITIALIZE with already existing files, sort or hash key files, and with record security fields.

Always use the IN filename clause

The above syntax shows the IN filename clause before the INITIALIZE command. Although this is, strictly speaking, an optional clause, its use is strongly recommended. Without it, the default file (that was most recently opened) is initialized, and sometimes the default file context is not the file which is intended to be initialized. This can result in severe unintentional effects; for example:

* This example is not the recommended approach OPEN FILEA *passwdA OPEN FILEZ *passwdB INITIALIZE

In the above, if an error occurs on OPEN FILEZ (for example, a file enqueueing conflict), the default file is FILEA and so that file is initialized, deleting all of its contents. The much better approach would have been IN FILEZ INITIALIZE.

Problems such as this can be avoided by always specifying the IN filename clause on the INITIALIZE command.

The rest of the syntax or examples of the INITIALIZE command on this page include the IN clause, to reinforce this recommendation.

Initializing existing files

You can also use a simple INITIALIZE command on an existing file that has data already in it, for example:

OPEN CARS password with necessary privileges if file is not public IN CARS INITIALIZE

These commands erase all information stored in the CARS file except for the file parameter settings. All field definitions, records, and procedures are wiped out. The INITIALIZE command and the Host Language Interface IFINIT function call clear the settings in the File Control Table (FCT) and prepare it for use.

Keeping field definitions

If you want to preserve the field definitions in addition to the file parameter settings, issue an INITIALIZE command with the KEEPDEFS argument, for example:

OPEN CARS password with necessary privileges if file is not public IN CARS INITIALIZE KEEPDEFS

Initializing sort or hash key files

To initialize a sort or hash key file (described in Sorted files and Hash key files, respectively), issue the INITIALIZE command followed on the next line by SORT or HASH, along with a description of key fields.

Note: Do not use the DEFINE command to define sort key or hash key fields.

INITIALIZE command

The syntax to initialize sort or hash key files is as follows:

INITIALIZE [KEEPDEFS] {SORT | HASH} fieldname (attribute [,attribute...])]

Where:

fieldname is the name of the sort or hash key field, followed by a list of field attributes. For example, the following commands identify the IDENT field as having the KEY and FRV attributes:

OPEN CARS IN filename INITIALIZE SORT IDENT (KEY FRV)

Specify as many field attributes as needed. For a complete listing of field attributes, see Defining fields. The complete syntax and description of INITIALIZE is located on the INITIALIZE command page.

The non-resettable FPARMS parameters SORTKEY and HASHKEY are set based on the command values.

Sort and hash key file restrictions

Certain restrictions apply to the field attributes that you can specify for sort or hash key fields. Model 204 automatically supplies the following field attributes for sort key fields:

NON-CODED VISIBLE STRING

For hash key fields, Model 204 supplies the following attributes:

NON-CODED VISIBLE STRING NON-KEY

If you specify attributes that conflict with the defaults for sort or hash key fields, the INITIALIZE command is rejected.

You cannot specify the UPDATE attribute for either sort or hash key fields.

Specifying a sort or hash key for every record in a file

If a sort or hash key is required in every record (that is, if the X'02' setting was specified in the FILEORG parameter), the key can be described as:

OCCURS n LENGTH m

Where:

• OCCURS n specifies the number of occurrences of the field that are preallocated or reserved in each Table B record.
• LENGTH m specifies the length of NON-CODED STRING and FLOAT fields.

For more information, see OCCURS and LENGTH clauses.

If keys are not required in each record, you cannot specify the OCCURS attribute. This allows Model 204 to distinguish between a missing key and a key that has a null value. See Preallocated fields for more information.

Initializing record security files

To initiate record security, set the X'20' option in the OPENCTL parameter in the CREATE command to indicate that record security is in effect. Record security is discussed in detail in Record security. The INITIALIZE command identifies the field that is to serve as the record security field.

Note: Do not use the DEFINE command to define record security fields.

Syntax

Issue the command in this form:

IN filename INITIALIZE RECSCTY fieldname (attribute [,attribute...])]

Where:

fieldname is the name of the record security field, followed by a list of field attributes. Specify as many field attributes as are needed. For a complete listing of field attributes, see Defining fields.

The non-resettable FPARMS parameter RECSTY is set based on the command values.

Examples

IN filename INITIALIZE RECSCTY PROTECT (ORD CHAR)

The RECSCTY clause can be preceded or followed by the description of the sort or hash key presented in the preceding section. For example:

IN filename INITIALIZE SORT ID (KEY,FRV) RECSCTY SECRET

All record security fields must have an indexed attribute (ORDERED or KEY). Although the NON-KEY attribute is the normal default, Model 204 automatically supplies KEY as the default for all record security fields. If you specify NON-KEY in a record security field description, the INITIALIZE command is rejected.

Specifying LENGTH on record security fields

If the record security field is defined with the LENGTH option:

LENGTH m

Ensure that the value of m is larger than the length allowed for LOGIN accounts (see Record security). Otherwise, if a user who has a long user ID attempts to store a record, Model 204 stores an empty record and cancels the user's request. The record is then inaccessible.