HP 3000 Manuals

Indexed Disc Files (KSAM) [ HP RPG/XL Programmer's Guide ] MPE/iX 5.0 Documentation

HP RPG/XL Programmer's Guide

Indexed Disc Files (KSAM)

The following list summarizes the advantages and disadvantages of using
KSAM files. For in-depth information on KSAM files, see the KSAM/3000
Reference Manual.

Advantages:

* Can access records sequentially, chronologically, and by partial or
generic key value

* Efficient disc usage; the data portion of the file grows as records
are added

* No special utilities are required for loading and unloading data

* Multiple keys

* Key fields can be updated

* Deleted records are retrievable

* Duplicate keys

* KSAM files can be processed by FCOPY, SORT, EDITOR; you can also use
the operating system FILE command with them

* Fast updating when processing data sequentially

* RPG Specifications are easy to code

* Fixed or variable length data records

Disadvantages:

* No query facilities

* No automatic maintenance of data relationships

* Extra memory usage when several users access the same file
simultaneously

Creating a KSAM Disc File

There are three ways to create a KSAM disc file:

Use this method: When:

KSAMUTIL You want to build an empty KSAM file or when
you cannot use an RPG program to build it (RPG
programs won't let you specify more than one
key field, for instance).

(KSAMUTIL is a KSAM utility that creates an
empty KSAM file.)

FCOPY You want to create an empty KSAM file or when
you want to copy all or part of a KSAM or MPE
file to an existing KSAM file.

(FCOPY is a general-purpose system command that
creates and copies files.)

RPG program You want to create a new KSAM file and load it
with data at the same time.

When you create a KSAM file, you specify the record keys (key fields)
that it contains. The first key that you enter is called the primary
key. The second and successive keys that you enter are called secondary
keys. Secondary keys are independent of primary keys; they are not
subordinate to them. Secondary keys can be thought of as alternate keys.
Both primary and secondary keys are maintained in the same KSAM key file.

Creating KSAM files using KSAMUTIL, FCOPY and RPG programs are discussed
in the next three sections.

Creating a KSAM File Using KSAMUTIL. The most flexible method of
creating a KSAM file is to use KSAMUTIL. You define the file size and key
fields using this utility. KSAMUTIL creates an empty file. It does not
load the file with actual data. (Use FCOPY or an RPG program to load
data into a file created by KSAMUTIL.)

The following steps tell you how to create a KSAM file using KSAMUTIL.
For detailed information about KSAMUTIL commands, see the KSAM/3000
Reference Manual.

Follow these steps to create a KSAM file using KSAMUTIL:

1. Enter the following command at the operating system colon prompt
(:),

RUN KSAMUTIL.PUB.SYS

You see the prompt, >. KSAMUTIL is prompting you to enter
information about the KSAM file.

2. Enter a KSAMUTIL BUILD command to create the KSAM file.

For example, the following command creates a file MASTFL having
256 characters per record. Its key file is MASTFLK. Its primary
key is a 5-byte field (KEY=B) starting in position 1 of the
record:

>BUILD MASTFL;REC=-256,1,F,ASCII;KEYFILE=MASTFLK;KEY=B,1,5

3. End KSAMUTIL by typing,

EXIT

Creating a KSAM File Using FCOPY. Use FCOPY when you want to create an
empty KSAM file or when you want to copy all or part of a KSAM or MPE
file to an existing KSAM file.

To use FCOPY, enter an FCOPY command at the operating system prompt.
(For detailed information on the FCOPY command, see the FCOPY Reference
Manual.)

For example, the following command copies 50 records (records 0 through
49) from the KSAM file, TRANSFL, to the KSAM file, MASTFL. MASTFL is a
new file and is created along with its key file, MASTFLK.

FCOPY FROM=TRANSFL;TO=(MASTFL,MASTFLK);SUBSET=0,49

If MASTFL and its key file already exist, the following command can be
used to copy the first 50 records in TRANSFL to it.

FCOPY FROM=TRANSFL;TO=MASTFL;SUBSET=0,49

NOTE You can create an empty KSAM file by specifying SUBSET=0,0 in the
FCOPY command. To copy all records to the new file (to duplicate
it), omit the SUBSET=option.

Creating a KSAM File Within an RPG Program. You can use an RPG program
to create and load data into a single-key KSAM file. You define the KSAM
file as an output file and include KSAM entries in the File Description
and File Description Continuation Specifications. If the KSAM file does
not already exist, RPG creates it using these specifications.

Figure 3-1 shows part of the transaction file used by the program in
Figure 3-2 to create a KSAM file. The transaction file, TRANSFL,
contains customer charge information that is used to create a master KSAM
transaction file, MASTFL. The first field of each record in the
transaction file is the customer's identification number and it is the
key field for MASTFL. For example, the first customer identification
number is 00216. (Records do not have to be sorted by customer
identification number before running the RPG program; KSAM automatically
orders the records.) Following the customer number in each transaction
record is the charge amount field. For example, 00342 ($3.42) is the
charge amount for customer 00216.
_____________________________________
| |
| 0021600342 |
| 0365416514 |
| 0720001517 |
| 0021601802 |
| 0321004532 |
| 0045318455 |
| 8206603324 |
| 5122101088 |
| 0321006702 |
| . |
| . |
| . |
| |
| |
_____________________________________

Figure 3-1. Creating a KSAM File Within an RPG Program - A Sample Input File TRANSFL

The KSAM file in Figure 3-2 can contain up to 1023 records (this is the
default). If your KSAM file is larger, enter a FILE command before
running the program (for information on the FILE command, see the MPE XL
Commands Reference Manual). For example, this FILE command specifies a
MASTFL size of 10,000 records:

:FILE MASTFL;DISC=10000

Figure 3-2. Creating a KSAM File Within an RPG Program Comments

Comments

1 This line defines the input customer transaction file, TRANSFL.

2 This line defines the master transaction file, MASTFL.

Column 15 is O to indicate that the file is an output file.

Columns 20-23 are blank to specify that there is one record per
block.

Columns 24-27 contain 256 to specify the number of characters
per record.

Columns 29-30 contain 5 to specify the number of characters in
the key field.

Columns 35-38 contain 1 to specify the starting position of the
key field.

Column 66 is blank (not A) to start writing data at the
beginning of the output file.

3 This line gives more details about the KSAM file, MASTFL.

Column 53 is K to indicate that this line is a Continuation
line.

Columns 54-59 contain the option name, KEYFL.

Columns 60-65 contain the name of the KSAM key file, MASTFLK.

Column 69 contains D to allow duplicate keys (optional).

Column 70 contains C to maintain the chronological order of
duplicate keys (optional).

4 This line starts the description of the input record format for
TRANSFL.

5 This line starts the description of the output record format for
MASTFL.

Reading a KSAM Disc File

There are several ways to read records in a KSAM file. Three methods,
sequential, random and chronological, are discussed in this chapter.

Reading a file sequentially means that RPG retrieves records
automatically in key sequence. You can process the entire file
automatically or you can process a portion of the file. To process part
of the file, you give RPG the key value of the first record to access.
Records are retrieved starting with that record and proceeding
sequentially until the last record (having a certain key value or
end-of-file) is processed.

Reading a file randomly means that you supply RPG with the key values for
each record to be processed. RPG goes to those records directly, without
passing through others first.

Reading a KSAM file chronologically means retrieving records in the
sequence in which they were added to the file.

Reading a KSAM File Sequentially. This section explains how to read
records in a KSAM file sequentially, starting with the first record in
the file and ending with the last. You can access records in sequence by
any key field. You can also read records in sequence by a non-key field.
To do this, the KSAM file must first be sorted on that field.

The following lines list the KSAMUTIL commands that create the KSAM file
used in Figure 3-3 and Figure 3-4. The KSAM file, MASTFL, has two keys.
The primary key field (KEY=B,1,4) does not have duplicates. The
secondary key field (KEY=B,25,15,,RDUP) can have duplicates but they are
not maintained in chronological order.

:RUN KSAMUTIL.PUB.SYS
>BUILD MASTFL;REC=-256,4,F,ASCII;DISC=20000,20,4;KEYFILE=MASTFLK;&
>KEY=B,1,4;KEY=B,25,15,,RDUP

Reading a KSAM File Sequentially by Key

This section explains how to read an entire KSAM file sequentially by
key. You can read a KSAM file in order by any field that was specified
as a key when the file was created.

Figure 3-3 shows the File Description Specification that reads the KSAM
file MASTFL by its primary key. (The previous section shows how MASTFL
is created.) MASTFL is defined as a primary file. If the KSAM file is
defined as a demand file, include a Calculation Specification containing
the READE operation.

Figure 3-3. Reading a KSAM File Sequentially by Key

Comments

1 This line defines the KSAM file, MASTFL.

Columns 29-30 contain 4 to specify the length of the key, DEPT.

Column 31 contains A to specify that the key field is
alphanumeric.

Column 32 contains I to specify that this is a KSAM file.

Columns 35-38 contain 1 to specify the starting location of the
key field.

Reading a KSAM File Sequentially by a Non-Key Field

This section explains how to read an entire KSAM file sequentially by a
non-key field. You can use any field that was not defined as a key when
the file was created. (This method of reading KSAM files also applies to
MPE files.)

To read a KSAM file sequentially by a non-key field, you must first
create a Record Address File (RAF). The RAF contains addresses of the
data records in the KSAM file in sorted order. You can use either
SORT/3000 or XSORT to create a RAF. XSORT is an RPG utility that is
documented in the RPG Utilities Reference Manual. SORT/3000 is a
general-purpose sort described in the SORT-MERGE/XL Programmer's Guide.
Once you create a RAF, you can use it in an RPG program to retrieve the
KSAM records in sorted order.

The following lines show how to enter XSORT parameters to order an
employee file, MASTFL, by employee zip code. (When MASTFL was created,
zip code was not specified as a key field.) The zip code field occupies
positions 60 through 64 in the KSAM records. The H Specification of
XSORT directs XSORT to create an Address Output (ADDROUT) file. ADDROUT
files are a special type of RAF containing sorted record addresses.

:FILE XSORTIN=MASTFL
:FILE XSORTOUT=RAFFILE;SAVE
:RUN XSORT.PUB.SYS
HSORTA 5A
FNC 60 64
:EOD

To process the ADDROUT file created by XSORT above, enter File
Description and File Extension Specifications as shown in Figure 3-4.

Figure 3-4. Reading a KSAM File Sequentially by a Non-Key Field

Comments

1 This line defines the RAF, RAFFILE.

Column 16 contains an R to indicate that RAFFILE contains record
addresses.

Column 17 is E to specify that reading continue to the end of
the file.

Columns 24-27 specify the record length, 4. (XSORT always
creates ADDROUT records that are four bytes long.)

Columns 29-30 contain the key field length, 4.

Column 32 is T to specify that this is an ADDROUT file.

Column 39 is E to indicate that there is a File Extension
Specification for this file.

2 This line defines the KSAM file, MASTFL.

Column 28 is R to indicate that MASTFL is accessed randomly.

Column 31 is I to specify that records in MASTFL are accessed by
their record addresses.

3 This line specifies that RAFFILE contains the record addresses
for accessing records in MASTFL.

Reading a KSAM File Sequentially Within Key Limits. When you need to
process a set of records in a KSAM file that have continuous key values,
you can process that file sequentially within key limits. Reading within
key limits may be used to process a range of part numbers (15000-15999)
in an inventory file, for example.

To read sequentially within key limits, specify the key value for the
first record then read the KSAM file sequentially until all records with
that key have been processed.

The following lines list the KSAMUTIL commands that create the KSAM file
used in Figure 3-5, through Figure 3-8. The KSAM file, MASTFL, has two
keys. The primary key field (KEY=B,1,4) cannot have duplicates. The
secondary key field (KEY=B,25,15,,RDUP) can have duplicates.

:RUN KSAMUTIL.PUB.SYS
>BUILD MASTFL;REC=-256,4,F,ASCII;DISC=20000,20,4;KEYFILE=MASTFLK;&
>KEY=B,1,4;KEY=B,25,15,,RDUP

Supplying Full Key Values (Method 1)

Figure 3-5 shows how to read all records in a KSAM file having a specific
key value. The KSAM file, MASTFL, is read by its secondary key field,
LNAME (positions 25-39). In this example, a user enters a specific last
name from the terminal. The program reads all records in the file with
this last name. When there are no more records for the name, the program
prompts the user to enter another name.

Figure 3-5. Reading a KSAM File Sequentially Within Key Limits - Supplying Full Key Values

Comments

1 This line defines the KSAM file, MASTFL.

Column 16 is D to indicate that MASTFL is a demand file.

Column 28 is L to specify that MASTFL will be processed within
key limits.

Columns 29-30 contain 15 to specify the length of the secondary
key, LNAME.

Column 31 contains A to specify that the secondary key is an
alphanumeric key.

Column 32 contains I to specify that this is a KSAM file.

Columns 35-38 contain 25 to specify the starting location of the
key field.

2 This line specifies the starting secondary key value for reading
MASTFL.

Columns 28-32 are SETLL to position the file pointer to the
first record having a key equal to the value placed in the LNAME
field.

3 This line reads the next record in last name sequence in MASTFL
(it is included in a loop that processes only those records
whose last name is equal to LNAME.)

Columns 28-32 are READE to specify the Read Equal key operation.

Supplying Full Key Values (Method 2)

If you know the key values of records to be accessed in a KSAM file, you
can place them into a RAF and let RPG use the RAF to access records in
the KSAM file. Figure 3-6 shows ranges of department numbers (the
primary key) to be accessed in a KSAM file. The ranges are: 0005-0100,
1200-1280, 2000-2475 and 5000-5999. (The department numbers are shown
exactly as they are entered into the RAF.) You can create a RAF using any
standard text editor, for example EDITOR. Enter key ranges starting with
position one. Enter the lower key value first followed immediately by
the upper key value. (See the HP RPG Reference Manual for details on
creating a RAF.)
_____________________________________
| |
| 00050100 |
| 12001280 |
| 20002475 |
| 50005999 |
| |
| |
_____________________________________

Figure 3-6. Reading a KSAM File Sequentially Within Key Limits - RAF Entries

To process a KSAM file sequentially using a RAF, enter both a File
Description and a File Extension Specification in your program similar to
those shown in Figure 3-7. Once the program in Figure 3-7 finds a
record, it displays the first 20 characters in it.

Figure 3-7. Reading a KSAM File Sequentially Within Key Limits - Using a RAF

1 This line defines the RAF, RAFFILE.

Column 16 contains R to indicate that RAFFILE is a RAF.

Column 17 contains E to specify that the program will not end
until all records in the RAF are processed.

Column 30 is 4 to specify the length of key values in RAFFILE.

2 This line defines the KSAM file, MASTFL.

Column 28 is L to indicate that MASTFL is processed within
limits.

Column 32 contains I to indicate that MASTFL is a KSAM file.

3 This line specifies that RAFFILE contains the key values for
records to be processed in MASTFL.

Supplying Partial Key Values

Figure 3-8 shows how to read all records in a KSAM file having a range of
key values. All records in the KSAM file, MASTFL, are read that have
last names starting with a specific character (for example "A"). A user
at a terminal enters the letter and the program reads the first record in
alphabetical sequence that starts with the letter. When there are no
more records in the file, the user is prompted to enter another letter.
The KSAM file, MASTFL, is created using the KSAMUTIL commands shown at
the beginning of this section.

Figure 3-8. Reading a KSAM File Sequentially Within Key Limits - Supplying Partial Key Values

Comments

1 This line defines the KSAM file, MASTFL.

Column 16 is D to indicate that MASTFL is a demand file.

Column 28 is L to specify that MASTFL will be processed within
key limits.

Columns 29-30 contain 15 to specify the length of the secondary
key (last name).

Column 31 contains A to specify that the secondary key is an
alphanumeric key.

Column 32 contains I to specify that this is a KSAM file.

2 This line specifies the starting secondary key value for reading
MASTFL.

Columns 28-32 are SETLL to position the file pointer to the
first record having a key equal to the value placed in the NCHAR
field.

3 This line reads the next record in MASTFL. READ is included in a
loop that processes only those records whose last name starts
with a specific character.

Columns 28-32 are READ to specify the Read key operation.

Reading a KSAM File Randomly. This section explains how to randomly
access records in a KSAM file by one of its key fields. There are two
ways to do this. The first method lets you supply the key value
dynamically in your RPG program. Use it when the key values are computed
by the program or when the program is run interactively. The second
method lets you enter the key values ahead of time into a RAF. RPG
accesses records in the KSAM file that match key values in the RAF. Use
the RAF method when you know what the key values are or when they can be
generated automatically by other programs. Examples of both of these
methods are included in the next two sections.

The following lines show how to use KSAMUTIL to create a KSAM file with
one (primary) key. The KSAM file is called MASTFL and duplicate keys are
not allowed:

:RUN KSAMUTIL.PUB.SYS
>BUILD MASTFL;REC=-256,4,F,ASCII;DISC=20000,20,4;KEYFILE=MASTFLK;&
>KEY=B,1,4

Specifying the Key Dynamically

If the records that you need to access in the KSAM file vary from one
program run to the next, you probably need to supply the record keys
dynamically. That is, you must retrieve or calculate them in the RPG
program before reading the KSAM file.

To process a KSAM file randomly by key, enter both a File Description and
a Calculation Specification similar to those shown in Figure 3-9. See
the KSAMUTIL commands in the previous section, "Reading a KSAM File
Randomly" for information on how this KSAM file is created.

Figure 3-9. Reading a KSAM File Randomly by Key

Comments

1 This line defines the KSAM file, MASTFL.

Column 16 contains C to indicate that the KSAM file is accessed
in chained fashion.

Column 28 is R to specify random processing.

Columns 29-30 contain 4 to specify the key length.

Column 31 contains A to specify that the key is alphanumeric.

Column 32 contains I to specify that this is a KSAM file.

2 This line reads MASTFL by primary key.

Columns 18-21 contain the name of the key field, DEPT.

Columns 28-32 contain the word CHAIN to read the file in a
chained fashion during the calculation portion of the logic
cycle.

Columns 54-55 contain the resulting indicator (60) that is
turned on when no record can be found for the value in DEPT.

Specifying the Keys Using a RAF

If you need to process KSAM records randomly by key and you know (before
running a program) what the key values are, use a RAF to hold them. RPG
will then use the key values in the RAF to access records in the KSAM
file. RAFs let you change key values without modifying and recompiling
the RPG program.

You can create a RAF using any standard text editor, for example EDITOR.
Enter key values starting with position one. You can enter more than one
key on each line, if you wish, but there must be no intervening spaces.
(See the HP RPG Reference Manual for details on creating a RAF.)

Figure 3-10 and Figure 3-11 show how to read a KSAM file randomly using a
RAF. Figure 3-10 lists the key values in the RAF and Figure 3-11 gives
the RPG program that processes the RAF. The keys in the RAF are four
digits long. They are: 0006, 0010, 0028, 0012, 0013, 0016, 0020, 0036,
0040, 0026, 0011, 0029, 0030 and 0080.
_____________________________________
| |
| 00060010002800120013 |
| 00160020 |
| 00360040 |
| 0026001100290030 |
| 0080 |
| |
_____________________________________

Figure 3-10. Reading a KSAM File Randomly by Primary Key - RAF Entries

The KSAMUTIL entries to create a file that can be accessed randomly is
shown in the previous section "Reading a KSAM File Randomly". To process
a KSAM file randomly using a RAF, enter both a File Description and a
File Extension Specification in your program similar to those shown in
Figure 3-11. Once the program in Figure 3-11 finds a record, it displays
the first 20 characters in it.

Figure 3-11. Reading a KSAM File Randomly by Primary Key - Using a RAF

Comments

1 This line defines the RAF, RAFFILE.

Column 16 contains R to indicate that RAFFILE is a RAF.

Column 17 contains E to specify that the program will not end
until all records in the RAF are processed.

Column 30 is 4 to specify the length of key values in RAFFILE.

2 This line defines the KSAM file, MASTFL.

Column 28 is R to indicate that MASTFL is processed randomly.

Column 32 contains I to indicate that MASTFL is a KSAM file.

3 This line specifies that RAFFILE contains the key values for
records to be processed in MASTFL.

Reading a KSAM File Randomly and Sequentially Using the Same Key. This
section explains how to read a KSAM file both randomly and sequentially
using the same key field. Use this method when you want to process the
file as a CHAINed file and as a demand file in the same program.

To read randomly and sequentially by the same key define the file as a
full procedural file in the File Description Specification. Figure 3-12
show how to read a KSAM file randomly and sequentially using the key
field, DEPT. A department number is entered by a user from the terminal.
The program randomly reads the KSAM file, MASTFL, to access that
department. Once the department record is read, the program reads
subsequent records sequentially until no more records for that department
are found.

Figure 3-12. Reading a KSAM File Randomly and Sequentially - Using Full Procedural Files

Comments

1 This line defines the KSAM file, MASTFL.

Column 16 is F to indicate that the file is a full procedural
file.

Column 32 is I to specify that this is a KSAM file.

2 This line reads MASTFL randomly by the department number field,
DEPT.

Columns 28-32 are CHAIN to specify that chained random
processing be performed for MASTFL. This key is DEPT.

3 This line starts the code that processes MASTFL sequentially by
key.

Columns 28-32 are SETLL to set the beginning key value for
MASTFL. SETLL sets the file pointer to the key value placed in
DEPT.

4 This line starts the loop that reads the KSAM file sequentially
by key.

5 This line reads MASTFL until there are no more records having a
department equal to DEPT.

Reading a KSAM File Randomly and Sequentially Using Different Keys. This
section explains how to access a file both randomly and sequentially
using different key fields. There are two ways to do this. For both
methods you describe the files in the program as if they were two
separate entities. In the first method, enter two FILE commands (file
equations) before executing the program. This method is easier to use
and less likely to result in access conflicts than the second method. In
the second method, enter File Description Continuation lines for each
file, equating them to the same physical file. The second method treats
the two files as one in the program and is more memory-efficient. The
next two sections give examples of these two methods.

Using File Equations

To use this method of processing a file randomly and sequentially, enter
File Description and Calculation Specifications similar to those shown in
Figure 3-13. The file MASTERC is a KSAM file that is processed randomly
and MASTERC is a KSAM file that is processed sequentially within key
limits.

Before executing the program shown in Figure 3-13 two FILE commands see
the MPE XL Reference Manual for information on the FILE command) must be
entered.

:FILE MASTERC=MASTFL
:FILE MASTERD=MASTFL

The FILE commands equate both MASTERC and MASTERD to the KSAM file,
MASTFL. MASTERC and MASTERD each have their own operating system file
number and current record pointer and each is opened and processed
independently of the other.

Figure 3-13. Reading a KSAM File Randomly and Sequentially - Using File Equations

Comments

1 This line defines the KSAM file, MASTERC.

Column 16 is C to indicate that the file is processed in a
CHAINed fashion.

Column 28 is R to indicate that MASTERC is processed randomly.

Column 32 is I to specify that this is a KSAM file.

2 This line defines the KSAM file, MASTERD.

Column 16 is D to indicate that MASTERD is a demand file.

Column 28 is L to specify that MASTERD will be processed within
key limits.

Column 32 contains I to specify that this is a KSAM file.

3 This line reads MASTERC randomly by department number, DEPT.

Columns 28-32 are CHAIN to specify that chained (sequential)
processing be performed for the file MASTERC. The key is DEPT.

4 This line starts the code that processes MASTERD sequentially by
secondary key.

Columns 28-32 are SETLL to set the beginning secondary key value
for MASTERD. SETLL sets the file pointer to the key value placed
in LNAME.

5 This line starts the loop that reads the KSAM file sequentially
by secondary key.

6 This line reads MASTERD until there are no more records having a
last name equal to LNAME.

Using File Description Continuation Lines.

The second way to read a KSAM more than one way in a program is to enter
two separate files in the program but include File Description
Continuation lines for each of them. These lines equate the two files to
the same physical KSAM file (you don't need FILE equations to do this).
Figure 3-14 shows how this is done. The file, MASTERC, is processed
randomly and the files, MASTERD is processed sequentially within key
limits. The File Description Continuation lines contain DSNAME entries
that equate the files to the KSAM file, MASTFL. When you use File
Description Continuation lines in this way, both files are treated as
one. They have the same file number and pointer and they share the same
buffer. Therefore, when you use this method, make sure that the read
operations restore the file pointer values properly.

Figure 3-14. Reading a KSAM File Randomly and Sequentially - Using File Description Continuation Lines

Comments

1 This line defines the KSAM file, MASTERC.

Column 16 is C to indicate that the file is processed in a
CHAINed fashion.

Column 28 is R to indicate that MASTERC is processed randomly.

Column 32 is I to specify that This is a KSAM file.

2 This line equates the KSAM file, MASTERD to MASTFL.

Column 53 is K to indicate that this line is a Continuation line
for MASTERC.

Columns 54-58 are DSNAMEMASTFL to specify that the file MASTFL
is to be used for MASTERC.

3 This line defines the KSAM file, MASTERD.

Column 16 is D to indicate that MASTERD is a demand file.

Column 28 is L to specify that MASTERD will be processed within
key limits.

Column 32 contains I to specify that this is a KSAM file.

4 This line equates the KSAM file, MASTERD, to MASTFL.

Column 53 is K to indicate that this line is a Continuation line
for MASTERD.

Columns 54-58 are DSNAMEMASTFL to specify that the file MASTFL
is to be used for MASTERD.

5 This line reads MASTERC randomly by department number, DEPT.

Columns 28-32 are CHAIN to specify that chained (random)
processing be performed for the file MASTERC. The key is DEPT.

6 This line starts the code that processes MASTERD sequentially by
secondary key.

Columns 28-32 are SETLL to set the beginning secondary key value
for MASTERD. SETLL set the file pointer to the key value placed
in LNAME.

7 This line starts the loop that reads the KSAM file sequentially
by secondary key.

8 This line reads MASTERD until there are no more records having a
last name equal to LNAME.

Reading a KSAM File Chronologically. When you read a KSAM file in
chronological order, you're reading the KSAM data file from beginning to
end. Records are read from the data file in the order that they were
originally added to the file. The KSAM file key file is not used.

Figure 3-15 gives an example of how records are stored in a KSAM data
file. In this example, only the key values are shown and the key field
occupies the first two bytes of the record. Notice that the records are
not physically ordered by key value. Records that are inactive (deleted)
have a value of FFFF (hexadecimal) in the first two bytes (regardless of
where the key is located). When you read chronologically, inactive
records are bypassed automatically.

Figure 3-15. The Chronological Order of Records in a KSAM Data File

The following File Description Specification processes a KSAM file in
chronological order.

Figure 3-16. Reading a KSAM File in Chronological Order

Comments

1 This line defines the KSAM file, MASTFL.

Column 17 is E to specify that processing proceed to the end of
the file.

Column 32 contains C to indicate the file that the file be
processed in chronological order.

Updating a KSAM Disc File

This section shows how to randomly update a KSAM file using its primary
key.

Figure 3-17 lists a program that updates a customer master file (MASTFL)
for a large department store. The master file is updated by a daily
sales transaction file (TRANSFL). Each sales transaction contains an
identification code that is used to access the customer's record in the
customer master file. Each transaction also contains the amount charged
by the customer. This amount is used to update the customer's account
balance.

Figure 3-17. Updating a KSAM File Randomly by Primary Key

Comments

1 This line defines the sales transaction file, TRANSFL. This file
is an MPE file.

2 This line defines the KSAM customer master file, MASTFL.

Columns 7-14 contain the name of the customer master file,
MASTFL.

Column 15 is U to indicate that MASTFL will be updated.

Column 16 is C to indicate that MASTFL will be processed in a
chained fashion.

Column 28 is R to specify that MASTFL will be processed
randomly.

3 MSGFL is a message file that is used to report program and other
errors. MSGFL is directed to the line printer.

4 This line defines the record type for all records in TRANSFL and
is followed by the field definitions for that record.

5 This line defines the record type for active records in MASTFL
and is followed by the field definitions for that record.

6 This line defines the record type for inactive records in
MASTFL.

Column 27 specifies that inactive records have an I in position
5. Inactive records may exist, but they cannot be updated.
(Inactive records reflect customers whose information either has
been deleted or is obsolete. They remain in the file to
facilitate error handling.)

7 This line reads MASTFL randomly by primary key.

Columns 18-21 define IDNO as the key to be used for reading
MASTFL.

Columns 28-32 are CHAIN to specify a chained read operation for
MASTFL.

Columns 54-55 turn on indicator 60 when a record matching IDNO
is not found in MASTFL.

8 This line adds the contents of field CHARGE to the filed CURBAL
(customer balance field in MASTFL) when an active record for
IDNO is found.

9 This line defines the output record for MASTFL.

Columns 24-25 specify that indicator 01 must have been turned on
(a transaction record must have been read) before records in
MASTFL are updated.

Columns 27-28 specify that indicator 02 must be turned on (an
active record is found in MASTFL) before records in MASTFL are
updated.

10 This line defines the customer balance field, CURBAL. This field
is the only field that is updated in MASTFL.

11 This line defines the first output record format for the message
file, MSGFL.

Columns 27-28 contain 03 to print an error message when a
deleted record is encountered in MASTFL.

12 The message, DELETED/OBSOLETE RECORD, is printed when indicator
03 is on.

13 This line defines the second record format for the message file,
MSGFL.

Columns 27-28 contain 60 to print an error message when a record
is not found in MASTFL.

14 The message MISSING RECORD, is printed when indicator 60 is on.

NOTE The CHAIN operation in line 7 turns on indicator 60 when a record
is not found for the key. The program handles the error by
displaying "MISSING RECORD". If no indicator is used with the
CHAIN operation, the halt indicator H0 is turned on and, if an
error response was not entered with the Header Specification, the
program halts and performs run-time error processing.

Adding Records to a KSAM Disc File

This section explains how to add Records to a KSAM file that already
contains data. You can add records in any order. They do not have to be
in sequence by a key field.

Figure 3-18 shows how to add records to a KSAM file. You define the file
as a CHAINed file by entering C in Column 16 of the File Description
Specification. The program in this example adds records using EXCPT
output (you can add records at detail-time also). The CHAIN operation
reads the file to see if a record already exists for the value in the key
field, DEPT. If a record does not exist, it is added.

Figure 3-18. Adding Records to a KSAM File Randomly by Primary Key

Comments

1 This line defines the KSAM file, MASTFL.

Column 16 is U to indicate that the KSAM file will be updated.

Column 17 is C for CHAINed (random) access.

Column 66 is A to indicate that records will be added to the
file.

2 This line reads MASTFL randomly.

Columns 18-27 contain DEPT to specify the primary key field for
MASTFL.

Columns 28-32 contain CHAIN to read a record randomly.

Columns 54-55 contain 80 to turn on indicator 80 when a record
is not found in MASTFL.

3 This line directs RPG to perform exception output when a
department record is not found (indicator 80 is turned on).

Columns 10-11 contain 80 to specify that this line be executed
when indicator 80 (line 2) is turned on.

Columns 28-32 contain EXCPT to direct RPG to write records while
calculations are in progress.

Columns 43-48 are ADDREC, the EXCPT Name for the record to be
added.

4 This line defines the MASTFL file output record for new (added)
records.

Column 15 is E to identify this record as an exception output
record.

Columns 16-18 are ADD to specify that records be added to the
KSAM file.

Columns 32-37 are ADDREC to specify the EXCPT Name for the
record to be added.

Deleting Records from a KSAM Disc File

This section tells you how to delete records from a KSAM file.

When you delete a record, you mark it as inactive. KSAM automatically
enters a -1 (hexadecimal FFFF) in the first two bytes of the record.
Deleted records remain in the file but are ignored when you read it.

When using KSAM files, it is a good idea to start the data fields of each
record in position three. This enables you to recover inactive records
in their entirety, if this becomes necessary. There are two ways to
access records that have been marked as deleted. You can use an RPG
program to read the file chronologically or you can use FCOPY. When using
FCOPY, copy the KSAM file with the NOKSAM file option.

To physically remove inactive records from a KSAM file, use FCOPY (with
the KSAM default option). FCOPY copies the file,except for inactive
records to either an MPE file or another KSAM file. You can also use an
RPG program to remove inactive records by copying the KSAM file to
another file.

Figure 3-19. Deleting Records From a KSAM File

Comments

1 This line defines the KSAM file, MASTFL.

Column 15 is U to indicate that the file will be updated.

2 This line reads the KSAM file, MASTFL, in a chained fashion.

Columns 18-27 contain EMPNO, which is key field name.

Columns 28-32 contain CHAIN to specify a CHAINed read operation.

Columns 33-42 contain MASTFL to name the KSAM file.

3 This line performs exception output when the appropriate record
in MASTFL is found.

4 This line defines the delete operation to be performed for
exception output.

Columns 16-18 are DEL to delete the current output record from
MASTFL.

Columns 32-37 contain DELREC to specify the EXCPT Name for the
record to be deleted.

Providing Security for KSAM Disc Files

When a KSAM file is going to be accessed by several programs, you must
decide on the type of security the file should have. If you want to
allow the programs to access the file simultaneously or do you want only
one program at a time to access the file? You specify the type of file
security with the operating system FILE command (see the MPE XL Commands
Reference Manual for details on the FILE command).

The following list summarizes the level of file security that you can use
for KSAM files.

* Exclusive

Exclusive access prevents others from accessing a file that is used
in your program. When you close the file, or when your program
finishes, the file is available to others. For example, entering
this FILE command before running a program gives the program
exclusive access to the file, MASTER:

:FILE MASTER;EXC

* Semi-exclusive

Semi-Exclusive access lets others read a file but prevents them
from updating it. When you close the file, or when your program
finishes, the file is available to others. For example, entering
this FILE command before running a program gives the program
semi-exclusive access to the file, MASTER:

:FILE MASTER;SEMI

* Shared

Shared access lets others read and write records in the same file
simultaneously. Different records can be accessed independently.
Each user has separate buffers, record pointers and file control
information. For example, entering this FILE command before
running a program gives the program shared access to the file,
MASTER:

:FILE MASTER;SHR

There are two ways to process shared files in an RPG program. You
can have RPG keep track of the records that are being accessed and
lock and unlock the file automatically. Alternatively, you can
control the locking process, yourself. If you do this, you must be
careful to lock the file before updating it and unlock it when
you're finished. The next two sections discuss automatic and
manual locking in detail.

__________________________________________________________________

NOTE All RPG programs processing the same file concurrently must
either use manual or automatic locking or must not use
locking at all.

__________________________________________________________________

Both automatic and manual locking enable the MPE Dynamic Locking
Facility. RPG programs that use automatic or manual locking for a
file cannot run concurrently with programs that do not have it
enabled. For non-RPG programs, enable the MPE Dynamic Locking
Facility by entering a FILE command similar to FILE MASTER;LOCK.

Automatically Locking and Unlocking Shared KSAM Files. Using LOCK in the
File Description Continuation Specification enables RPG automatic
looking. When you read or write a record, RPG locks and unlocks the file
for you. Figure 3-20 shows how to use LOCK in a program that adds
records to the KSAM disc file, MASTFL.

Each user, before running a program that accesses a KSAM file
concurrently with another user, must enter a file equation similar to the
following:

:FILE MASTFL;SHR

Figure 3-20. Automatically Locking and Unlocking KSAM Files

Comments

1 This line defines KSAM file, MASTFL, as an Update CHAINed file.

2 This line enables the automatic lock facility for MASTFL.

Column 53 is K to indicate that this is a Continuation line.

Columns 54-59 are LOCK to enable RPG automatic locking.

3 The line reads MASTFL randomly by department number, DEPT.

4 This line directs RPG to perform exception output when a
department record is not found (indicator 80 is turned on).

5 This line defines the MASTFL file output record for new (added)
records.

Manually Locking and Unlocking Shared KSAM Files. Using NOLOCK in the
File Description Continuation Specification lets you manually lock and
unlock a KSAM file yourself.

Figure 3-21 shows how to enter the File Description and Calculation
Specifications that lock and unlock a KSAM file. The purpose of the
program is to add records to the file. Before they are added, the
program checks to see if they already exist. The KSAM file is locked
before the check is made and unlocked after the new record is added.

When manually locking and unlocking a KSAM file, you must enter a file
equation similar to the following before running the program:

:FILE MASTFL;SHR

Figure 3-21. Manually Locking and Unlocking KSAM Files

Comments

1 This line defines the KSAM file,MASTFL, as an Update CHAINed
file.

2 This line enables the manual locking facility for the file,
MASTFL.

Column 53 is K to indicate that this is a Continuation line.

Columns 54-59 are NOLOCK to enable RPG manual locking.

3 This line locks the file, MASTFL, before a record is read from
it.

Columns 28-32 contain LOCK. This locks MASTFL before the chain
operation (next line).

Columns 33-42 contain the name of the KSAM file, MASTFL.

Columns 58-59 contain 12 to turn on indicator 12 when the lock
operation is successful.