BUILD

Actual file designator. This is the name that identifies the KSAM file (both data and key files) and also identifies the data file when specified independently of the key file. It has the form:

filename [/lockword] [.groupname [.accountname] ]

All four sub-parameters are names that contain from 1 to 8 alphanumeric characters, beginning with a letter.

	NOTE: If specified, account name must be that of your log-on account; you cannot create a file in another account.

If file has no lockword and belongs to your log-on group, only filename is necessary. You cannot backreference files.

(Required parameter.)

Size of logical records in file. If a positive number, this represents words; characters are represented by a negative number, If the records are variable length, recsize indicates the maximum length allowed for a logical record.

Block size is determined by multiplying the specified recsize by blockfactor. For binary files or ASCII files with fixed-length records, an odd character count is rounded up to the next highest even number to insure that the record starts on a word boundary. The rounded number should be used in calculating block size since a block always starts on a word boundary.

(Optional parameter.)

Default: The configured record size of the particular device is used when recsize is omitted; for disc files, the value used is 256 characters or 128 words

An integer equal to the number of logical data records in each block.This integer should result in a data block size smaller than 4096 (4K) words. The blockfactor is used to calculate the buffer size established for transfer of data to and from the file.

For fixed-length records, blockfactor is the actual number of records in a block. For variable-length records, blockfactor is a multiplier used with recsize to calculate block size:

block size = ( (recsize+1) * blockfactor)+1

The calculation is performed in words, not characters.

(Optional parameter.)

Default: calculated by dividing the specified recsize into the configured block size; the result is rounded down to an integer never less than 1.

Data file contains fixed-length records.

(Optional parameter.)

Data file contains variable-length records. Since KSAM performs its own blocking and deblocking, a KSAM data file specified as variablelength is treated by MPE as a file with fixed-length records, each record the size of a KSAM block (refer to blockfactor above for calculation of block size). Although the MPE LISTF command shows the data file as fixed-length, the KSAMUTIL VERIFY command, option 3, shows DATA FIXED as FALSE when the file is a variable-length KSAM file.

(Optional parameter.)

Default: If both F and V are omitted, records are fixed-length.

Data file contains binary-coded records.

(Optional parameter.)

Data file contains ASCII-coded records.

(Optional parameters.)

Default: If both BINARY and ASCH are omitted, records are binary.

File is created as a session/job temporary file; when the session or job terminates, the file is deleted from the session/job temporary file directory.

(Optional parameter.)

Default: If TEMP is omitted, file is declared permanent and is saved in the system file domain.

device designates the device on which the data file resides. (The key file device is specified in the KEYDEV parameter.) device can be specified as a device class name of up to 8 alphanumeric characters beginning with a letter and terminated by any non-alphanumeric character such as a blank, or as a logical device number consisting of a three-character numeric string, or it can be a remote device identifier consisting of the device class name or logical device number followed by a pound sign (#) and a remote device class name or logical device number.

Device class names and logical device numbers are assigned to devices during system configuration. (See System Manager/System Supervisor Reference Manual).

For KSAM files, the device must be a random access device such as the disc. If the file is a newly-created disc file specified as a device class name, then all extents to the file must be members of the same class. Similarly, if the device is identified by a logical device number then all extents must have the same logical device number.

(Optional parameter.)

Default: If omitted, the device class name DISC is used.

Code indicates that the data file is specially formatted. The code is recorded in the file label and is available to processes through the FGETINFO intrinsic. It must be specified as a positive integer in the range 0 through 1023.

(Optional parameter.)

Default: If CODE is omitted, the file code is 0.

	NOTE: The CODE parameter applies only to data files; the key file code value is always 1080.

Total maximum file capacity, in terms of logical records (for files containing fixed-length records). For files containing variable-length records, this is the maximum file capacity if all the records are maximum length. Maximum file capacity allowed is 2,097,120 sectors.

(Optional parameter.)

Default: If omitted, 1024 records is the default.

Number of extents (continguously-located disc sectors) that can be dynamically allocated to the file as logical records are written to it. The size of each extent (in terms of records) is determined by the numrec parameter value divided by the numextents parameter value. Extents can allocated on any disc in the device class specified in the device parameter. If you want to ensure that all extents for a file reside on the same disc, use the logical device number of that disc or a device class name relating to a single disc device, in the device parameter. If specified, numextents must be integer value from 1 to 32.

(Optional parameter.)

Default: 8.

Number of extents to be allocated to the file at the time it is opened. Must be an integer from 1 to 32. If attempt to allocate requested space fails, an error message appears.

(Optional parameter.)

Default: 1.

Actual file designator. This is the name that identifies the KSAM key file. It has the format: filename, which is 1-8 alphanumeric characters beginning with a letter. Unlike filereference1 (the data filename) filereference2 may not be qualified by account or group names, nor may it contain a lockword. The key file contains all the key entries and key control information, whereas the data file contains the actual data. A KSAM file is always referenced by the data file name, filereference1, not the key file name, filereference2.

(Required parameter.)

One KEY specification must be included for each key in the KSAM file. The first occurrence of the KEY specification describes the primary key; each subsequent KEY specification describes an alternate key. There may be up to 15 alternate key descriptions in addition to the primary key description.

(Required parameter.)

keytype is specified as BYTE,INTEGER, DOUBLE, REAL, LONG, NUMERIC, PACKED, or *PACKED. The whole word or only the first letter need be specified (for example, B is equivalent to BYTE). If more than the first letter is used, the word must be spelled correctly. (Refer to Table 2-2 “Key Types” for a full description of each key type.)

(Required parameter.)

Location of the first character of the key within the data record counting from the first character in the record. The first character in the data record is always numbered 1. Only one key can start at the same location.

(Required parameter.)

Length of the key in characters. The length depends on keytype as follows:

(Required parameter for BYTE, NUMERIC, PACKED, and *PACKED key types: defaults are provided for INTEGER, DOUBLE, REAL, and LONG key types, as noted above.)

Number of keys per block. The keyblocking value is an even number greater than or equal to 4. It is used with the key entry size (keysize paramater) to determine the size of each key block according to the followign formula:

   5 + (keysize+1) + 4    keyblocking = key block size in words
        ---------
           2

Five words are used for control information in each block, keysize specified in characters is divided by 2 to get the key size in words, and 4 words are added for the pointers in each key entry. This key entry size in words is multiplied by the keyblocking factor to determine key block size. If the keyblocking value generates a key block size greater than 2048 (2K) words, the file cannot be created.

The resulting key block size is rounded up to a multiple of 128 words. If the file has multiple keys, KSAM forces all key blocks to the same size and adjusts the number of keys per block accordingly.

Note that the value you specify for keyblocking may be increased (never decreased) by the system in order to produce a blocking factor that does not waste disc space. Refer to appendix B for a discussion of how the system determines the most efficientblocking factor based on the value you enter for keyblocking.

Key blocking can affect access time in that the smaller the key block, the more time it may take to retrieve a record using the key file. In many cases, the default blocking factor produces the most efficient key blocking.

(Optional parameter.)

Default: key blocking is set to a value that produces a key block size of 1024 (1K) words. (Maximum size is 2K.)

In order to allow duplicate key values, this word must be included in the KEY specification. If DUPLICATE (or DUP) is not specified, records with duplicate key values are rejected and an error message issued when such records are written to the file. DUP is a legal abbreviation of DUPLICATE. When you use this option to specify duplicate keys, each new duplicate key is inserted at the end of the duplicate key chain. This maintains the chronological order of duplicate keys.

This option specifies that duplicate keys are allowed and are to be inserted randomly in the duplicate key chain. This method makes insertion of such keys faster, but does not maintain the chronological order of the duplicate key chain.

(Optional parameter.)

Default: If omitted, duplicate keys are prohibited.

The value of numentries is used to determine the key file size. The value specified for numentries should be the maximum number of primary key entries expected. When there are alternate keys, KSAM automatically adjusts the key file size to accomodate each key in addition to the primary key.

Normally, this parameter can be omitted since KSAM assigns it the value of numrec (number of fixed-length data records or blocks of variable-length records). If, however, the data records are variable length and there are many small records, the value of numrec may be too small. In this case, you should specify a value for numentries greater than the value of numrec.

The number of key entries determines the size of the key file, the file limit. When a new KSAM file is created, the MPE end-of-file marker is set to this file limit rather than to the end-of-data as is normal for MPE files. This allows any key block to be accessed in case of system failure. To determine where the actual end-of-data is, use the KSAMUTIL VERIFY command, option 3, and look at the heading KEY FILE EOF. This shows the record number of the next available key block (one record past the last used key block).

(Optional parameter.)

Default: the value of numrec in the DISC= parameter or its default value 1024 if it too is omitted.

The number of user label records to be created for the KSAM data file. Up to 254 labels (1 less than the MPE maximum) can be specified; COBOL programmers are restricted to 8 labels.

(Optional parameter.)

Default: if omitted, numlabels is equal 0.

The device on which the key file resides, specified as a device class name or a logical device number. A device class name indicates the general type of the device as a string of one to eight alphanumeric characters beginning with a letter and terminated by a non-alphanumeric character such as a blank. The logical device number is the threecharacter numeric string identifying a particular device. If the data file is created on a remote device, the key file is assigned to the same machine, and the key file device is specified in the KEYDEV=parameter.

Device class names and logical device numbers are assigned to devices during system configuration.

For KSAM files, the device must be a random-access device such as the disc.

(Optional parameter.)

Default: If omitted, the device class name DISC is used.

Determines whether record numbers in the data file are to start with zero or one. If the integer 1 is specified, then records are numbered beginning with 1; otherwise they will start with 0. The only acceptable values for recnum are 1 and 0.

Normally, record numbering in MPE files starts with zero, the default value for recnum. In order to be consistent with most commercial applications, you can specify FIRSTREC=1 to change the record numbering scheme so that data records are numbered starting with 1.

(Optional parameter.)

Default: if omitted, record numbering starts with zero.

The name or identification number of the language to use in determining the key sequence. The language specified by parameter must be installed on the system. See Appendix F for detailed information on using Native Language Support (NLS) with KSAM files.

(Optional parameter.)

Default: if omitted, NATIVE-3000 is used.

Prevents duplicate file locks ftom the same process. NODUPLOCKS controls "Lock" access to a KSAM file. Each time a process opens a file more than once and locks the file through a different open path, KSAM checks the file's lock access. If NODUPLOCKS was specified when the file was created, the process is not allowed to lock the file more than once. File locks from the same open path are always allowed.

(Optional parameter)

Default: if omitted, duplicate file locks from the same process are allowed.