Using KSAM XL and KSAM 64 > Chapter 2 Creating a KSAM File

Creating the File With the BUILD Command

	MPE documents
	Complete PDF
	Table of Contents
	Index

	E0300 Edition 4 ♥
	E0394 Edition 3

The BUILD command parameters define standard file characteristics, such as the file and record lengths, and file, record, and data types. For KSAM 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 file.

The file name.
Size of the record.
Record type of F for fixed-length records (required for KSAM files).
Binary-coded or ASCII-coded data.
Permanent or temporary file.
Device class DISC (required for KSAM files).
The maximum number of records.
The language ID.
A file type of KSAMXL (required for KSAM XL files).
A file type of KSAM64 (required for KSAM64 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 to select data block size.

KSAM File Characteristics

The key characteristics, the method of file numbering, and the reuse option are unique to KSAM 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 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 to choose the optimal data block size based on the record size of a file. Refer to MPE/iX Commands Reference Manual 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

[Creating a KSAM XL file using
the OPTMBLK parameter]

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 64 file using the OPTMBLK parameter

[Creating a KSAM 64 file using
the OPTMBLK parameter]

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

[Creating a KSAM XL file with
data block size set at 4K bytes (default)]

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

[Creating a KSAM 64 file with
data block size set at 4K bytes (default)]

Use the FILE command along with the FCOPY command to copy a new KSAM 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-5 "Building the AR Master KSAM XL 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-5 "Building the AR Master KSAM XL 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-5 Building the AR Master KSAM XL File

[Building the AR Master KSAM XL
File]

Figure 2-6 Building the AR Master KSAM64 File

[Building the AR Master KSAM64 File]

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-7 "Using a Key Data File to Create a KSAM XL File" shows the command for setting up the same accounts receivable master file as in Figure 2-5 "Building the AR Master KSAM XL 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-7 Using a Key Data File to Create a KSAM XL File


  :BUILD ARMSTRXL.MGR.AR;REC=-80,,F,ASCII;DEV=DISC;&
  DISC=100;KSAMXL;KEY=^KEYDATA;&
  FIRSTREC=1;REUSE ;LANG=5

Figure 2-8 Using a Key Data File to Create a KSAM 64 File


  :BUILD ARMSTR64.MGR.AR;REC=-80,,F,ASCII;DEV=DISC;&
  DISC=100;KSAM64;KEY=^KEYDATA;&
  FIRSTREC=1;REUSE ;LANG=5

Chapter 2 Creating a KSAM File

Loading Data to a KSAM XL File