MAKE-FUNCTION (op-code 3)

This routine is used to create a new indexed file. It will overwrite any existing file. This routine will not overwrite a file that is currently in use. If the file is in use, the error E_FILE_LOCKED will be returned. The MAKE routine has six parameters, name, comment, p_parms, l_parms, keys, and trans.

This routine does not automatically terminate its parameters with LOW-VALUES, you must insure that the parameters are correctly terminated yourself. If you do not wish to supply an alternate collating sequence in the trans parameter to MAKE, then simply omit the parameter. The I$IO routine does not allow you to specify a NULL parameter which is what is expected by the MAKE routine. Instead, by omitting the parameter, the I$IO routine will construct a NULL parameter for you.

The host file system may ignore any or all of the values specified by comment, p_parms and trans. If the host system cannot perform the requested operation, it is ignored (however, if the trans value is ignored, F-ERRNO is set to W_NO_SUPPORT). If the host system cannot support one of the values specified in l_parms or keys, then MAKE fails and RETURN-CODE is set to the error condition E_NO_SUPPORT. If any of the parameters are ill-formed or contain values outside of the legal range of values, E_PARAM_ERR is returned.

Name points to the name of the file. This must be null-terminated.
Comment may be NULL or may point to comment string that describes the file. This comment is stored in the file, but has no other functional use. The comment may be up to 30 characters long and must be null-terminated. Many host file systems cannot store comments. On these systems, this parameter is ignored.
P_parms points to a string that describes various physical characteristics of the file. This string consists of five numeric fields separated by commas and must be null-terminated. Each of these fields advises the file system of desired treatment for the physical storage of the file. Individual file systems may ignore some or all of these fields. Furthermore, p_parms may be NULL to imply 0 for each of the fields.

The filesys.def COPY file has a data item containing these fields.

The fields are as follows:

  1. Blocking factor. This value is the number of disk sectors to store in a single file block. It may be zero to request the default blocking factor for the file system.
  2. Pre-allocate amount. This is the number of file blocks (the size of which depends on the blocking factor above) to initially allocate to the file. The purpose of this is to allocate contiguous disk space for the file. It does not limit the file's total size. This value may be zero to request the default initial allocation amount.
  3. Extension factor. This is the number of file blocks to add to the file when it needs to grow. The purpose of this is to help reduce disk fragmentation. This value may be set to zero to request the default extension amount.
  4. Compression factor. This is a value between zero and 100. It represents the amount of file compression desired. A value of zero indicates no compression and a value of 100 indicates maximum compression. Values in between indicate varying degrees of compression. The exact meaning of this depends on the host file system.
  5. Encryption flag. If this value is 1, then encryption is desired for the disk file. If it is zero, then no encryption is desired. The results of encryption depend on the host file system. Since no key is supplied, the results of encryption are usually only moderately secure.
l_parms points to a string that describes various logical characteristics of the file. The string consists of three numeric fields separated by commas. The string must be null-terminated.

The filesys.def COPY file has a data item containing these fields.

The fields are as follows:

  1. Maximum record size. This is the size of the largest record to be placed in the file. For Vision 5 files, this may range from 1 to 67,108,864. For Vision 2, 3, and 4 files, this may range from 1 to 32,767.
  2. Minimum record size. This is the size of the smallest record to be placed in the file. This may range from 1 to the maximum record size. If this field is the same as the maximum record size, then fixed-length records are implied.
  3. Number of keys. This is the number of keys in the file, including the primary key. This may range from 1 to MAX_KEYS.
keys points to a null-terminated string that describes the key structure for the file. keys is a string of numbers separated by commas. The first key described is the primary key. It may not allow duplicate values. The primary key is called key 0. The next key described is key 1 and so on. There should be as many keys described as the "number of keys" field of l_parms indicates.

The filesys.def COPY file has a data item containing these fields.

Each key description contains the following information:

  1. Number of segments. This is the number of segments in this key. A segment is a contiguous region of bytes in the record. You may describe a split key by specifying more than one segment. With Vision Version 3 files, this may range from 1 to V3_MAX_SEGS. With Vision Version 4 and 5 files, this may range from 1 to MAX_SEGS.
  2. Duplicates flag. If this value is 1, then duplicate keys are allowed. If 0, then duplicate values are not allowed. This must be 0 for the primary key.
  3. Segment size. This is the number of bytes in the first segment. This may be between 1 and MAX_KEY_SIZE.
  4. Segment offset. This is the offset from the beginning of the record to the first byte of the segment. A segment that starts at the beginning of the record has an offset of 0.
  5. Remaining segments. The segment size and segment offset fields are repeated for each additional segment in the key. The sum of the segment sizes may not exceed MAX_KEY_SIZE.

For example, a file with two keys, the first one having two segments (offset zero, length 10 and offset 50, length 5) and the second one with one segment (offset 20, length 15) and allowing duplicates would be written: 

2,0,10,0,5,50,1,1,15,20
trans This parameter specifies an alternate collating sequence for the keys. If this parameter is NULL, then keys are ordered in ascending sequence based on their native unsigned value. If trans is not NULL, it must point to a 256 byte region of memory. Unlike other strings, this need not be null-terminated and is likely to contain nulls within it. This 256 byte region is used as a translation table on the bytes of each key to arrive at a new key-ordering. Each byte is used as an index into this table, and the resulting value is used to order the keys. Some host file systems cannot do key translations. On these systems, this parameter is ignored.
Parent topic: I$IO