CREATE.FILE

portion

identifies the part of the file to create. This may be DATA to create just the data portion, DICT to create just the dictionary portion or omitted to create both.

file.name

is the name of the VOC record to be created to refer to the file. By default, the operating system pathname used for the directory representing the data file is the same as file.name and the directory for the dictionary component of a file is the same but with a .DIC suffix.

type	specifies the file type as DIRECTORY, DYNAMIC or COLLECTION. If omitted, a dynamic file is created by default. Dictionaries are always created as dynamic files regardless of any type argument.

MULTIFILE

when creating the data portion of the file, causes the file to be created as a multifile even if no subfile is specified.

PATHNAME path

specifies the pathname of an existing operating system directory under which the file is to be created. If this is a relative pathname, it will be preserved in this form for the VOC entry of the new file.

IN name

As an alternative to the PATHNAME option, name specifies the name of an F-type VOC item that defines a directory file. The new file will be created within this directory. Although this option can be useful, the ability to create a new QM file inside the directory that represents a directory file should be used with caution as deleting name will also delete the operating system representation of any QM files within that directory, leaving their VOC entries in place.

NON.TRANSACTIONAL

The file is always to be opened in non-transactional mode. This option causes the N open mode flag to be included in field 6 of the F-type VOC entry.

The configuration options available when creating a dynamic file to specify the file's configuration are:

CASE	creates a file where the record ids will be treated as case sensitive. This is the default action unless the CREATE.FILE.NO.CASE mode of the OPTION command is enabled.

ECS {"map"}

The file will be created in ECS mode and will be able to store records that include characters outside the 8-bit character set in their id or data. Files created in this mode cannot be opened by non-ECS mode versions of QM. The optional map name specifies the name of the ECS map to be used by the file to determine uppercase/lowercase relationships and the sort order for alternate key indices. If omitted, the system's default map at the time of creating the file will be used. Note that only the map name, not the actual map, is stored in the file. Modifying the map may have undesired effects.

GROUP.SIZE size

sets the group size as a multiple of 1024 bytes. This must be in the range 1 to 8 but for best performance should be a power of two. If omitted, the default group size is taken from the GRPSIZE configuration parameter.

NO.MAP

suppresses mapping of characters in directory file record names that are normally restricted. This option affects only the data portion of the file and is therefore invalid when the DICT keyword is present. Note that when this option is used the application is responsible for ensuring that record names comply with operating system file name rules. See directory files for more information.

The USING DICT clause allows creation of a data file that is to share the dictionary of an existing file. The effect of this option is to copy the content of field 3 of the VOC entry for other.file into field 3 of the newly created entry rather than setting up a new dictionary.

The ENCRYPT keyword enables record level data encryption and prefixes the name of the encryption key to be used. If omitted when creating a hashed file, the CREATE.FILE command looks for an X-type record named $ENCR in the VOC file. If this is present, field 2 specifies the name of an encryption key that will be applied automatically. To ignore this record, use ENCRYPT "". Automatic encryption does not apply to directory files.

The NO.CASE option specifies that record ids in a hashed file are to be treated as case insensitive. QM will write records preserving the casing specified by whatever performs the write. Reads will locate records regardless of casing. If the file.name has been prefixed with DATA or DICT to create only the specified portion of the file, the NO.CASE keyword applies to that file portion. If the file name prefix is not present so that both portions will be created, the default action is for NO.CASE to apply to the data portion only. The optional DATA and DICT qualifiers to the NO.CASE option, both of which may be given, apply case insensitivity to the specified part of the file. The CREATE.FILE.NO.CASE and CREATE.DICT.NO.CASE modes of the OPTION command can be used to make case insensitivity the default.

Case sensitivity of record ids in directory files is dependent on the operating system.

The NO.QUERY option suppresses any confirmation prompts associated with the requested action.

The MODE ddd{:sss} option sets file permission modes (not Windows). The ddd component is an octal permissions mask that will be applied to the directory that represents the file. The sss component, applicable only to dynamic files, is an octal permissions mask that will be applied to the subfiles within the directory. If omitted, it defaults to ddd.

The USER and GROUP options set the owner and group for the file (not Windows). The uid and gid qualifiers may be specified either as numbers or as names. No error is reported if the user executing the command does not have sufficient access rights to apply these values. When either of these options is omitted, the behaviour of CREATE.FILE depends on the setting of the INHERIT.OWNERSHIP mode of the OPTION command. If this option is enabled, the user and group are inherited from the ownership of the account directory. If this option is not enabled, the user and group are inherited from the user executing the command.

To provide maximum flexibility, QM imposes no restrictions on the file name except that it may not contain the mark characters or the ASCII null character. Use of spaces in file names is not recommended as it is likely to lead to problems with some commands. Characters that are not valid in operating system file names are automatically transformed using the same translations as described for directory file record ids.

By default, the directories created at the operating system level to represent the QM file and its dictionary have their names converted to uppercase. The KEEP.FILENAME.CASE mode of the OPTION command can be used to suppress this conversion.

A data collection file is a special case of a dynamic hashed file in which the records represent data collections. All of the configuration options relating to dynamic files also apply to this file type.

A multifile is a collection of data files that share a common dictionary. Commands and application software refer to an individual subfile within the multifile by using a name that consists of the file name and subfile name separated by a comma. References to the file without specifying the subfile use the default subfile which has the same name as the file. For example a multifile named SALES might have subfiles named NORTH and SOUTH referenced as SALES,NORTH and SALES,SOUTH. Referring simply to SALES without a subfile name is taken as meaning SALES,SALES which does not have to exist. The subfile name will be treated as case insensitive if the VOC (and hence the file name) is case insensitive.

When creating a multifile element, the default action of CREATE.FILE is to create a subdirectory named file.name under the account and create the element within this directory as subfile. An alternative location can be specified using the PATHNAME or IN parameter. If neither of these parameters is present and the INHERIT.MFILE.PATH mode of the OPTION command is active, adding a new subfile to an existing file creates the subfile in the same directory as the default subfile.

The CREATE.FILE command can convert an existing simple file into a multifile. The existing data becomes a subfile with the same name as the file.

The MODE option can be used to set the file access permissions for the newly created file and its dictionary. This option is ignored on Windows. The ddd element is the octal value for the permission flags to be applied to the directory that represents the QM file. The first digit is the permissions for the owner of the file, the second digit is the permissions for other users in the group to which the file is assigned, and the third digit is permissions for all other users. Each digit is formed by adding 4 (write), 2 (read) and 1 (execute).

The sss element is the octal value for the permission flags to be applied to subfiles in the directory when creating a hashed file. If omitted, this defaults to the same value as ddd.

If the MODE option is not used, the file permissions are taken from the current operating system umask value.

This statement creates a dynamic file named STOCK with minimum modulus of 150 and group size 4.

This statement creates a dynamic file named INVOICES. The directory representing this file will have permission flags of 775 and the subfiles in the directory will have permission flags of 660.

This statement creates a dynamic file named SALES and applies record level data encryption using the SALESKEY key.

This statement creates the data portion of a directory file named PROGRAMS. The full pathname for this directory file is specified as D:\APPS\PROGRAMS rather than using the default location.

This statement creates a multifile component named NORTH within the ACCOUNTS file.