IB Statements/create

From CometWiki

CREATE statement
Syntax: CREATE filename, record-size, file-type [,key-size,[key-position]] DIR=directory [,EXCP=statement-label | NOEXCP] or

CREATE text-file-name, DIR=directory [,EXCP=statement-label | NOEXCP]

Discussion: The CREATE statement creates a new data file on a specified Comet directory. The first version shown above creates any type of Comet data file, while the second version creates a text file.

The filename parameter is the name of the file to be created. It can be a string constant or a string variable, with a length up to 12 characters in 8.3 format.

The record-size parameter defines the number of bytes in each record of the file. It may be a numeric constant or numeric variable with a maximum value of 8000 for CFAM files and a maximum value of 1024 for non-CFAM files. For sequential and keyed files, each record in the file has the same size. For text files, the record size is automatically set, regardless of the record-size parameter specified in the CREATE statement. For key-only files, the record-size parameter should equal 0.

File-type is a one-character designator that defines the type of file being created, as follows:

 Character Type of data file
 ==============================
 S         Indexed Sequential
 K         Keyed
 T         Text (although a text file can be created
           using the alternate syntax shown above)

The key-size parameter, required only for keyed files, defines the number of characters in the record key (index). A maximum of 254 characters is allowed. (Note: Prior to Comet 2005 this limit was 64 and remains that for legacy keyed files.) Optionally a key-position may be specified. This indicates an "extended keyed file" (added in Comet 2005). In these files, CFAM automatically stores a copy of the key data in your record and may be up to 254 characters. This helps to insure integrity between the key tree and the record set and makes rebuilding the key tree a snap in the event a recovery is required. For Key-position, the first character in the record is at position 0.

The directory parameter is the name of the Comet directory where the file will be created. The directory can be a string constant or a string variable, with a maximum length of three characters.

If an exception occurs when this statement is executed (e.g., if the file already exists), the program will branch to the specified statement label.

If an exception 13 occurred when the second form of this statement is executed, Comet did NOT create an empty file, but simply registered it in the Comet directory for subsequent use.

History: The text-file-only CREATE statement was added to Comet98 in Build 266.

Example 1: CREATE "HISTFILE",500,K,20,DIR="DSK",EXCP=9999

In this example, the CREATE statement is used to create a keyed file called HISTFILE on Comet directory DSK. The file will have 500 bytes in each record and 20 bytes in each key. If an exception occurs when this statement is executed (e.g., if the file already exists), the program will branch to statement- label 9999.

Example 2: CREATE "CUSTNAME",0,K,35,DIR="DSK",EXCP=9999

In this example, the CREATE statement is used to create a key- only file called CUSTNAME on Comet directory DSK. The file will have 0 bytes in each record and 35 bytes in each key.

Example 3: CREATE "LOGFILE",250,S,DIR="DSK"

In this example, the CREATE statement is used to create a sequential file called LOGFILE on Comet directory DSK. The file will have 250 bytes in each record.

Example 4: CREATE "TEXTFILE.TXT",DIR="DSK", excp=Check . . Check: if excp=13 goto Its.There  ! The underlying text file was already in the directory

In this example, the CREATE statement is used to create a text file called TEXTFILE.TXT in Comet directory DSK.

Example 5: LENGTH 8 & LOCAL FILENAME$

LENGTH 3 & LOCAL DIRNAME$

. . . PRINT (0) "ENTER THE FILE NAME:"

INPUT (0) FILENAME$

PRINT (0) "ENTER THE DIRECTORY NAME:"

INPUT (0) DIRNAME$

CREATE FILENAME$,256,K,12,DIR=DIRNAME$,EXCP=8000

In this example, the user is prompted for the filename and Comet directory name (defined at the beginning of this program segment). The CREATE statement then creates a file by the name entered by the user (on the directory entered by the user). The file will be created with a record size of 256 and a key size of 12.

If an exception occurs when this statement is executed (e.g., if the file already exists), the program will branch to statement- label 8000.