Building a KSAM File Programmatically

The HPFOPEN and FOPEN intrinsics can be used within a program to create and open a KSAM file in a single step. As with the BUILD command, file and key characteristics are provided as parameter data.




	NOTE: The `HPFOPEN` intrinsic can be used only in an MPE/iX environment. If a program is to be developed for both MPE/iX and MPE V/E systems, the `FOPEN` intrinsic should be used. Refer to “Mixed Mode Operation” in Chapter 8 for information regarding cross development.

The unique KSAM file and key characteristics are contained in an array that varies in length from 40 to 162 words. The format of the array is shown in Figure 2-9 “KSAM Parameter Format”. Characteristics for a maximum of sixteen keys need to be specified in the array. Standard file characteristics are contained in the file options parameter of the intrinsic.

Language ID

Enter the three digit code for the native language that you desire. To find out what languages can be accessed on your system, enter RUN NLUTIL.PUB.SYS. A list of languages and their IDs is displayed on the screen. Any of the listed language IDs can be entered in this field.

Flag word

The flag word contains two bytes defining the KSAM file characteristics:

Bits

Value/Meaning

15:1

Reserved.

14:1

Enter a 1 if record numbering is to start with 1.

Enter 0 if record numbering is to start with 0.

13:1

Enter 1 if only sequential writing by primary key is allowed.

Enter 0 if random writing by primary key is allowed.

12:1

Enter 1 if deleted record space can be reused.

Enter 0 if deleted record space cannot be used.

11:1

Enter 1 if a language type is specified.

Enter 0 if a language type is not specified.

10:1

Enter 1 if the primary key cannot be changed with the FUPDATE intrinsic for files that are opened for sequential processing.

Enter 0 if the primary key can be changed with the FUPDATE intrinsic for files that are opened for sequential processing.

9:1

Enter 1 if the file is programmatically accessed by the COBOL programming language. Enter 0 if the file is not programmatically accessed by the COBOL programming language. This enables KSAM to process COBOL information according to COBOL standards.

8:1

Enter 1 if KSAM is to select the optimal data block size. Enter 0 if KSAM is to use the default data block size.

0:9

Enter 0. These bits are reserved and must contain zeros.

Figure 2-9 KSAM Parameter Format

Number of Keys

Enter a digit between 1 and 16 in word 16 to specify the number of keys to be defined for this file. Refer to Figure 2-9 “KSAM Parameter Format” for the location of this field.

Key Parameters

The following parameters are defined for each key. The information about each key is similar to the BUILD command's KEY= parameter.

key type

Enter one of the following codes specifying the type of data the key will contain.

Code: Key Data Type
1: Byte key (1 to 255 bytes)
2: Short integer key (255 bytes)
3: Integer key (255 bytes)
4: Real number key (255 bytes)
5: Long real number key (255 bytes)
6: Numeric display key (1 to 28 bytes)
7: Packed decimal key, odd number of digits (1 to 14 bytes)
8: Packed decimal key, even number of digits (2 to 14 bytes)
9: IEEE floating-point decimal key (4, 8, or 16 bytes)

key length

Enter the length of the key in bytes. A maximum of 255 bytes is allowed, but the length is dependent on the type of key data specified.

key location

Enter the relative location in bytes of the key field in the record. Note that the first byte of the record is considered 1.

duplicate key flag

Enter 1 if duplicate key values are allowed for this key.

Enter 0 if duplicate key values are not allowed for this key.

random insert flag

This field specifies the method of inserting duplicate key values. To use this feature, the previous duplicate key flag must be set to 1.

Enter 0 if duplicate key values are to be inserted at the end of the duplicate key chain.

Enter 1 if the duplicate key values are to be inserted randomly in the duplicate key chain.

Figure 2-10 “KSAM Parameter Settings” provides an example of the declarations that are needed to define and load a KSAM XL parameter array using Pascal/iX. Chapter 4 “Opening and Closing the File” provides an example of an HPFOPEN intrinsic call that creates and opens a KSAM file.

Figure 2-10 KSAM Parameter Settings

  type
    bit1=0..1;
    bit4=0..15;
    bit7=0..127;
    bit8=0..255;
    bit12=0..4095;
    bit15=0..32767;
    bit16=0..65535;
    pac80     = packed array [1..80] of char;
    ksam_rec    = packed record
           case integer of
           1 : (bitword : bit16);
           2 : (lang_id : bit16);
           3 : (resrvd0 : bit8;
              optm_blk: bit1;
              cm   : bit1;
              chg_primary : bit1;
              kslang : bit1;
              ksreuse : bit1;
              seq_random : bit1;
              rec_numbering : bit1;
              resrvd2 : bit1);
           4 : (resrvd3 : bit8;
              num_keys : bit8);
           5 : (key_type : bit4;
              key_length : bit12);
           6 : (dflag : bit1;
              maxkeyblk : bit15);
           7 : (resrvd5 : bit8;
              rflag : bit1;
              resrvd6 : bit7);
           8 : (key_location : bit16); 
           end;
    ksam_struc   = ARRAY[0..80] OF ksam_rec;
    .
    .
    .
  var
    ksam_param,
    ksamparam : ksam_struc;
    keylocation,
    reserved : bit16;
    .
    .
    .

  begin
    ksamparam[10].lang_id := 5; 
    ksamparam[16].resrvd3 := 0;
    ksamparam[16].num_keys := 1;
    ksamparam[17].key_type := 2;
    ksamparam[17].key_length := 5;
    keylocation := 5;
    ksamparam[18].bitword := keylocation;
  .
  .
  .

The HPFOPEN intrinsic uses item number pairs to identify intrinsic parameters. Item number 54 is paired with the KSAM parameter array to define the KSAM XL key structure. Other item number pairs that relate to KSAM XL files specifically are listed below:

10: This item number identifies the KSAM XL file type. Enter 3 to indicate that a KSAM XL file is to be created. Enter 7 to indicate that a KSAM64 file is to be created.
17: A KSAM XL file can be accessed only as its own type. Enter 0 for a KSAM XL file.

The FOPEN intrinsic can also be used to create and open a KSAM file. The same KSAM parameter array is used as an FOPEN parameter option. The FOPEN intrinsic uses parameter values rather than item number pairs to identify file characteristics and the KSAM key value array. Refer to Chapter 4 “Opening and Closing the File” for a description of the FOPEN intrinsic.

Building a KSAM File Programmatically

Technical documentation

» Table of Contents

» Index

Language ID

Flag word

Number of Keys

Key Parameters