Creating the File With the BUILD Command

The BUILD command parameters define standard file characteristics, such as the file and record lengths, and file, record, and data types. For KSAM XL files, you must also specify characteristics of each key field and special KSAM options. The following list offers the most common file characteristics that you need to decide before building a KSAM XL file.

The file name.
Size of the record.
Record type of F for fixed-length records (required for KSAM XL files).
Binary-coded or ASCII-coded data.
Permanent or temporary file.
Device class DISC (required for KSAM XL files).
The maximum number of records.
The language ID.
A file type of KSAMXL (required for KSAM XL files).
Information about each key (repeated up to sixteen times); at least one key is required:
- Type of key data.
- The location of the first byte of the key.
- The length of the key.
- Random insertion or sequential insertion of the key, if duplication is allowed.
Record numbering starting with 0 or 1.
Reuse of deleted record space or no reuse.
Specify default data block size or allow KSAM XL to select data block size.

KSAM XL File Characteristics

The key characteristics, the method of file numbering, and the reuse option are unique to KSAM XL files. Each key must be defined in the BUILD command's ;KEY= parameter. Record numbering and the reuse option must be specified if the default values are not acceptable.

Key Characteristics

The ;KEY= parameter of the BUILD command encloses all key characteristics in parentheses. Individual characteristics for a single key are separated by commas. Each key description is separated from the next by a semicolon. The following example shows a ;KEY= parameter that defines two keys. Four characteristics are defined for each key: key type, location, size, and duplication method.

   ;KEY=(B,9,5,RDUP;I,17,3,DUP)

The following descriptions list the available options for the definition and use of keys. Four characteristics are defined for each key: key type, location,size, and duplication method.

The key type defines the data type of the key field. The type is identified by a keyword or its abbreviation. In the previous example, the first key field contains byte data and the second is an integer. The following list provides the valid key types.

byte or B: Byte data field.
integer or I: Integer data field.
real or R: Real number.
IEEE real or E: IEEE floating-point decimal number.
numeric or N: Numeric field.
packed or P: Packed decimal field, odd number of digits.
*packed or *: Packed decimal field, even number of digits.

The key's location is determined by the position of the first byte of the field in relation to the beginning of the record. The first byte of the record is considered to be 1. Only one key can start at a particular location. In the previous example, the first key begins in byte 9, the second in byte 17.

The size of the key must be specified in bytes. Specific use of any key is determined by its definition. The ranges listed below indicate the maximum possible values. The maximum length of the key varies by data type, as specified in the following list:

byte: 1 to 255 bytes.
integer: 1 to 255 bytes of integer data.
real: 1 to 255 bytes of real number data.
IEEE real: 4, 8, or 16 bytes of IEEE real number data.
numeric: 1 to 28 bytes of numeric data.
packed: 1 to 14 bytes of packed decimal data (odd number of characters).
*packed: 2 to 14 bytes of signed packed decimal data (even number of characters).

The duplication key characteristic is an optional field. If a key must be unique, such as an account number or social security number, no additional parameters are made. The default value is no duplication. If the key can be duplicated, there are two methods of inserting duplicate key values in the index's duplicate key chain.

DUP specifies that each new duplicate key is inserted at the end of the duplicate key chain, maintaining chronological order.

RDUP specifies that each new duplicate key is inserted randomly in the duplicate key chain. RDUP is used if the reuse option is selected. With RDUP, chronological order is not maintained.

First Record Number

The ;FIRSTREC= parameter of the BUILD command specifies the number of the first record in the file. Several record retrieval methods use record numbers to identify the physical location of a record. You can specify whether to use "0" or "1" to identify the first record. The default value is 0.

REUSE Option

KSAM XL files can reuse deleted record space if the REUSE option is specified. This option, however, increases the allocated space reserved for the file by 15 percent and distributes free space evenly throughout the file when the file is initially loaded. When a record is to be added to the file, free space is available so that a search for record space is not lengthy. When a record is deleted, its space is added to the free space available.

The NOREUSE option, the default value, does not allow the reuse of deleted record space. This option maintains physical record order. A new record is appended to the end of the file, even if other records have been deleted. If many records are added and deleted, the file continues to expand in size. In such cases, it is recommended that the file be copied regularly to eliminate the unusable space if disk space is needed.

Language ID

The optional ;LANG= parameter of the BUILD command 224 specifies the native language specifies the native language of the data in the file. You can select the language by entering a code of up to three digits or by entering the language name. To find out what languages can be accessed on your system, enter RUN NLUTIL.PUB.SYS. Any of the listed language IDs can be entered in this field. The default language is Native-3000. Different affectd languages may cause the sequential ordering of records to be affected.

OPTMBLK/DEFBLK Option

Users can assure efficient disk space utilization by using the OPTMBLK option of the BUILD command. When specified, OPTMBLK allows KSAM XL to choose the optimal data block size based on the record size of a file. Refer to MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-90003 and 32650-90364) for more information on using this option.

The LISTFILE, 7 command displays the optimal data block size and the 8 bit value of the flagword of the KSAM parameter.

Figure 2-1 Creating a KSAM XL file using the OPTMBLK parameter

:BUILD XOPTM;KSAMXL;KEY=(B,1,4);OPTMBLK

:LISTFILE XOPTM,7



KEY     KEYTYPE      KEY LOCATION   KEY SIZE  DUP/RDUP

---     -------      ------------   --------  --------

 1     BYTE             1       4  NONE



NUM KSAM KEYS: 1               FIRST KSAM RECORD: 0

LANGUAGE     : ENGLISH         REUSE RECORD     : NO

VERSION      : 2               COMPUTE BLK SIZE : OPTMBLK

DATA         :

The DEFBLK parameter of the BUILD command allows the user to select a data block size of 4K bytes. If neither OPTMBLK nor DEFBLK is specified, the data block size defaults to DEFBLK (block size of 4K bytes).

Figure 2-2 Creating a KSAM XL file with the data block size set at 4K bytes (default)

:BUILD XDEF;KSAMXL;KEY=(B,1,4)

:LISTFILE XDEF,7 



KEY     KEYTYPE      KEY LOCATION   KEY SIZE  DUP/RDUP

---     -------      ------------   --------  --------

 1     BYTE             1       4  NONE



NUM KSAM KEYS: 1               FIRST KSAM RECORD : 0

LANGUAGE     : ENGLISH            REUSE RECORD   : NO

VERSION      : 2               COMPUTE BLK SIZE  : DEFBLK

DATA         :

Use the FILE command along with the FCOPY command to copy a new KSAM XL file to one where the data block size is chosen using OPTMBLK.

Users with existing KSAM XL files of 4K bytes can convert their files by using FCOPY. Specify the OPTMBLK option in the file equation. This allows KSAM XL to select the data block size in the file equation. If a file equation does not specify either option, FCOPY uses the FROM= file's setting of OPTMBLK or DEFBLK.

Sample BUILD Command

Figure 2-3 “Building the AR Master File” builds a sample KSAM XL master file to process 80-byte accounts receivable records in English. The maximum size of the file is 100 records. Record numbering in the sample file begins with number 1. Reuse of deleted record space is allowed.

In this sample, four key fields are defined to sequence data for various programming functions:

A unique 6-digit account number as the primary key.
A 25-character field containing the client's last name.
A 5-digit zip code field.
A 3-character branch ID.

Figure 2-3 “Building the AR Master File” creates the ARMSTR file with the preceding specifications using the BUILD command. (Note that ampersands have been included at the end of each line to continue the command on subsequent lines to improve readability.)

Figure 2-3 Building the AR Master File

 :BUILD ARMSTR.MGR;REC=-80,,F,ASCII;&

 DEV=DISC;DISC=100;KSAMXL;&

 KEY=(N,4,6;&            Specifies account number (primary) key

 B,10,25,RDUP;&          Defines the last name key

 N,65,5,RDUP;&           Defines the zip code key

 B,70,3,RDUP);&          Defines the branch ID key

 FIRSTREC=1;REUSE ;LANG=5      Specifies that the first record is 

                               identified by number 1, 

                               that deleted record space can be reused, 

                               and that the native language is English.

Specifying an Indirect File

To reduce errors, the characteristics for key data fields can be contained in an indirect file and referred to in the BUILD command. Such a file can be created using an editor, such as HP EDIT. The information is structured as it would be if it were included in the command. The format of the key data in the indirect file is shown in the following example.

(N,4,6;&

B,10,25,RDUP;&

N,65,5,RDUP;&

B,70,3,RDUP)

Figure 2-4 “Using a Key Data File” shows the command for setting up the same accounts receivable master file as in Figure 2-3 “Building the AR Master File”. The KEY= parameter, however, refers to the indirect file named KEYDATA for the key data specifications. The character ^ specifies that an indirect file contains the data.

Figure 2-4 Using a Key Data File

:BUILD ARMSTR.MGR.AR;REC=-80,,F,ASCII;DEV=DISC;&

DISC=100;KSAMXL;KEY=^KEYDATA;&

FIRSTREC=1;REUSE ;LANG=5