HP 3000 Manuals

FILE Command (KSAM) [ HP ALLBASE/4GL Developer Reference Manual Vol. 2 ] MPE/iX 5.0 Documentation

HP ALLBASE/4GL Developer Reference Manual Vol. 2

FILE Command (KSAM)

The file command allows you to perform various operations on application
data files. You can use the file command to perform operations on HP
ALLBASE/SQL tables and select lists, HP TurboIMAGE/iX data sets, KSAM
data files, and serial data files.

This description covers the use of the FILE command with KSAM data files.

Formats

{*BUFFER}
FILE {*CLOSE } file_ref [;command]
{*MODIFY}
{*UNLOCK}

{*FIRST }
FILE {*LAST } [*NOLOCK]file_ref[*INDEX=index_name][;command]
{*NEXT }
{*PREVIOUS}

{*DELETE}
{*FIND }
FILE {*INSERT} [*NOLOCK]file_ref [*INDEX=index_name][*KEY=key][;command]
{*READ }
{*WRITE }
Window

Parameters

file_ref

Specifies the HP ALLBASE/4GL name of the application file on which the
operation is to be performed. It can be expressed in either of the
following ways:

* file_id

- or

* file_id.record_name

If you don't specify .record_name for the file, HP ALLBASE/4GL uses the
default record for the file.

*NOLOCK

The *NOLOCK term is a command argument to control file locking for the
file access. If the *NOLOCK argument is present, no locking is performed
by the file access provided the file is not already locked. If the file
has already been locked by an earlier access, the * NOLOCK argument has
no effect. Refer to KSAM File Locking for further information.

index_name

This parameter allows you to specify the name of the index or the number
of the index to be used to access the file. The index name must be the
name of a field specification that you have defined as a key field on the
default record layout for the file. You can also specify the index by
entering the number of an index for the file. The index you specify here
is used for one file access only. Specifying an index name or number
here does not change the current value in the communication area field
*INDEXNO.

If you don't specify an index name or number, HP ALLBASE/4GL accesses the
file according to the index specified by the current value of * INDEXNO.

key

This parameter defines the key data to be used to access the file. It
can be one of the following:

* Literal.

* Alphanumeric constant.

* Variable or calculated item.

* Screen field reference.

* Scratch-pad field reference.

* File record field reference.

* Work area field reference.

* Non-numeric communication area field.

This parameter is optional. If you don't specify a key, HP ALLBASE/4GL
accesses the file according to the existing value in the record buffer
key field identified by the current value of *INDEXNO or the * INDEX=
argument. If you do specify a key value, HP ALLBASE/4GL moves this value
to the key field (as identified by *INDEXNO or the *INDEX= argument) in
the file record buffer.

command

A command to be executed if the requested file operation fails. You can
use any of the following HP ALLBASE/4GL logic commands:

* ENTER

* EXIT

* EXTERNAL

* MESSAGE

* PROCEED

* SERIES

* TOP

* VISIT

* ZIP

Description

The FILE command performs various operations on KSAM data files.

Opening and Closing Files

HP ALLBASE/4GL automatically opens each KSAM file when it is first
accessed in a process. There is no need to explicitly open KSAM data
files. If a file is specifically closed (refer to *CLOSE below), HP
ALLBASE/4GL automatically opens the file when it is next accessed.

HP ALLBASE/4GL automatically closes all data files at the start of a
process.

File Indexes

The communication area field *INDEXNO specifies the number of the index
used to access the file. HP ALLBASE/4GL initializes the value in this
field to 1 when the application starts, assuming that all file access is
via the primary file indexes. HP ALLBASE/4GL does not reset the value of
*INDEXNO if you change it at any time. Therefore, you must ensure that
*INDEXNO is set to the correct value before each FILE command is
executed.

If you want to access records on a file with more than one index, you
must set *INDEXNO to the number of the required file index before the
FILE command is executed.

You can specify a different index for a particular file access by
specifying the name of a field defined as a key field on the default
record layout for the file in *INDEX= argument on the FILE command. You
can also specify the index for a file access by specifying the number of
an index in *INDEX= clause.

File Access Modes

You must specify any files that are to be updated in the current process
by using the MODE command with the *WRITE, *LOCK, or *UNLOCK argument.
Any files not specified are available for reference purposes only.
(Refer to the MODE command.)

File Record Buffers

HP ALLBASE/4GL maintains a separate buffer for each record layout defined
for each file.

HP ALLBASE/4GL clears the file record buffer or buffers automatically
when a file is first accessed, or at the start of any process.

Where multiple records have been defined for an indexed (KSAM) file, data
in one record buffer is not automatically available to another record
buffer for the same file. To make the data available, you can read the
record again, or move the data between buffers using either the MOVE or
MOVELOOP commands.

Communication Area Fields

HP ALLBASE/4GL places the external name of the file currently being
accessed in the communication area field *FILENAME.

File Operations

Operations you can perform on KSAM files are:

*BUFFER. Clears the specified buffer of all data. The buffer cleared is
defined by file_ref.

*CLOSE. Closes the nominated file. You can use this operation to close
any file that is not required. HP ALLBASE/4GL automatically reopens the
file if it is accessed after being closed. Closing a file releases all
locks belonging to the current process, regardless of the original file
access mode.

*DELETE. Deletes a record from the file. If the file has unique primary
keys, the record deleted is determined by the primary key value.

If the file allows duplicate primary key values, you must read a record
before it can be deleted. If you haven't read a record, HP ALLBASE/4GL
returns an error number 19112.

After a delete operation, the file pointer position may be undefined.
You may need to use a FILE *FIND, or a FILE *READ command to reposition
the file pointer before performing further operations.

*FIND. Finds the first record in the file whose key is greater than or
equal to the value of key. The file key is tested using the index number
specified in *INDEXNO or by *INDEX=.

HP ALLBASE/4GL does not place data into the record buffer as a result of
a *FIND. To retrieve the record found, use the operation *NEXT.

HP ALLBASE/4GL only maintains one file position pointer for the *FIND
operation. To retrieve a record located by the *FIND operation, you must
use the *NEXT operation to read the record before you perform any other
operation on the same file.

You can use *FIND to locate a record in the file when the complete value
of the key is not specified. For example, If key contains SMIT, *FIND
will find SMITH.

The *FIND operation returns error status 19111 (record not found) if
there is no record with a key value equal to or greater than the value of
key.

*FIRST. Reads the first record in the file for the index specified by the
current value in *INDEXNO or by *INDEX=.

*INSERT. Adds a new record to the file.

This operation forces new records onto the file if duplicate primary key
values have been specified for the file.

If the file does not allow duplicate primary key values, using *INSERT
will cause an error if you attempt to add a record to the file with a
primary key value the same as one that already exists.

*LAST. Reads the last record in the file for the index specified by the
current value in *INDEXNO or by *INDEX=.

*NEXT. Reads the next record in the file for the index specified by the
current value in *INDEXNO or by *INDEX=.

*MODIFY. Changes an existing record in the file.

You must read a record before you can use the *MODIFY command to change
its contents.

*PREVIOUS. Reads the previous record in the file for the index specified
by the current value in *INDEXNO or by *INDEX=.

*READ. Reads the record in the file whose key value, for the index
specified by the current value in *INDEXNO or by *INDEX=, exactly matches
the value specified by *KEY=key. If you don't specify the *KEY=key
argument on the FILE command, HP ALLBASE/4GL uses the current value in
the record buffer field specified by *INDEXNO or the *INDEX= argument.

*UNLOCK. The *UNLOCK argument releases the locks on a file that has been
accessed under MODE *WRITE or MODE * UNLOCK. HP ALLBASE/4GL ignores this
argument if the file is being accessed under MODE *READ or MODE *LOCK.

*WRITE. Writes a new record or modifies an existing record on the file.

Don't use this operation if the file allows duplicate primary key values.
Use the *INSERT operation instead.

If the file does not allow duplicate primary key values, then one of the
following actions occurs:

* If a record exists on the file whose primary key matches the
primary key value in the record buffer, the file record is
modified. The modify is performed in the same manner as the
*MODIFY operation.

* If a record does not exist, a new record is added to the file.
The add is performed in the same manner as the *INSERT operation.

*WRITE performs the same operation as the UPDATE command except that it
operates on one file only.

Error Handling

If the FILE command contains an optional logic command, HP ALLBASE/4GL
executes the command if an error occurs as a result of the file access.
For example, when performing a *NEXT operation, the optional command is
executed if the end of the file is encountered.

When an error occurs, the HP ALLBASE/4GL data manager writes an error
code into the communication area field *IOSTATUS. Appendix C lists the
data manager error codes. The value returned to *IOSTATUS is zero if the
file command is successful.

If you include the optional error command, the data manager errors for
the following conditions are not displayed on the terminal screen:

* Duplicate key errors (error 19100).

* Record locked (error 19107).

* End of file (error 19110).

* Record not found (error 19111).

* Record not read (error 19112).

* File exclusively locked (error 19113).

* File already locked (error 19130).

For other error conditions, even if you have specified an error command,
the error message is displayed on the screen.

File Errors

The following table summarizes the most common file error values returned
to the communication area field *IOSTATUS. Refer to appendix C for a list
of MPE/iX KSAM file error returns.

*IOSTATUS

Value Condition

19000 MPE/iX file access error detected by the KSAM file manager

19013 MPE/iX error. Access permission denied to file.

19100 Duplicate primary key error. The file only allows unique primary key
values, and a record with the same primary key value already exists.

19107 Record locked error. Another user or process has locked the record
you are attempting to access.

19110 Beginning or end of file reached during a *NEXT or *PREVIOUS file
operation.

19111 Record not found. No record has a key value matching the value
specified for *KEY=key.

19112 Record not read. No record has been read for the file.

19113 Exclusive locking error. Another user or process has locked the
file.

19130 File locking error. The current process cannot lock the file because
the file is already locked by another process.

KSAM File Locking

HP ALLBASE/4GL provides file locking for entire files only. The KSAM
data manager does not provide record level locking. The file locking
system prevents two users modifying the same file in such a way that
records or the file structure may be corrupted.

If a file is locked, another user or process cannot lock the same file
while the lock is current.

Data file locking in HP ALLBASE/4GL depends on both the file operation
used with the FILE command, and the file access mode specified in the
MODE command. The following table summarizes the file access and locking
that can occur if two users (or a user and a background process) attempt
to access the same data file.

Under the MODE *LOCK, MODE *WRITE, or MODE *UNLOCK commands, the file is
normally locked when it is first accessed. However, the file is not
locked when you first access a file if you access the file using a
command that contains the *NOLOCK argument.

When a file is accessed under MODE *WRITE or MODE *UNLOCK, the file
remains locked until the end of the process, the file is closed with the
FILE *CLOSE command, or the file is unlocked with a FILE *UNLOCK command.

When a file is accessed under MODE *LOCK, the file remains locked until
the end of the process, or until the file is closed with the FILE *CLOSE
command.

All file locks are also released by a TRANSACT *END command or a TRANSACT
*UNDO command.

When a file is accessed under MODE *READ, no file locking is performed.

At any time, you can explicitly specify that a particular file access
does not lock a file by specifying the *NOLOCK argument on the FILE
command.

Note that any time you read a file without locking the file, HP
ALLBASE/4GL clears the MPE/iX buffer using the FCONTROL intrinsic with
code 7 to ensure that the record is read from the disk. This is
necessary to ensure that the latest possible information is obtained by
the read. As a result, performing a large number of reads on a KSAM file
without locking the file can create a substantial disk I/O overhead.

*LOCKWAIT Communication Area Field

HP ALLBASE/4GL uses the value in the communication area field *LOCKWAIT
to determine its behavior when it attempts to access a file that is
locked by another process. The *LOCKWAIT field can contain the values
-1, 0, or a positive integer number. The actions taken by HP ALLBASE/4GL
for different values in *LOCKWAIT are summarized below.

Value Action

+n HP ALLBASE/4GL waits for n seconds to access the file. If the file
is not accessible after n seconds, HP ALLBASE/4GL returns an error
number 19107.

0 P ALLBASE/4GL attempts to access the file every second for 5 seconds.
If the file is not accessible after 5 seconds, HP ALLBASE/4GL returns
an error number 19107.

-1 HP ALLBASE/4GL waits indefinitely to access locked files.

When HP ALLBASE/4GL starts an application, the value in *LOCKWAIT is
initialized to zero. You can use the MOVE command to move a different
value into *LOCKWAIT. HP ALLBASE/4GL does not reset the value in *
LOCKWAIT at any time except when the application starts.

Example 1

5 FILE *READ stock *KEY=S-stock_no.stock_add; ENTER 12
.
.
12 MESSAGE no_stock

This command reads the file stock, and searches for a record with its key
value equal to the value of the field stock_no on the screen stock_add.
If the record cannot be located, the system executes step 12, which
displays the message no_stock.

Example 2

FILE *BUFFER trans.cust

This command clears the buffer for the record cust in the file trans.
Example 3

4 FILE *NEXT trans; ENTER 11
5 SHOW *REFRESH
6 TOP
.
.
11 MESSAGE no_transactions

These commands read and display records from the file trans. When the
system encounters the end of the file, it executes step 11 which displays
the message no_transaction.

Example 4

FILE *WRITE stock *KEY=*S01

This command checks if a record with a key equal to the contents of
screen field number 1 exists on the file stock. If such a record exists,
the system updates it. If the record doesn't exist, the system creates a
new record.

Example 5

1 MODE *LOCK filename
2 FILE *READ filename *KEY=*; ENTER 8
.
.
5 FILE *WRITE filename *KEY=*; ENTER 8
6 FILE *CLOSE filename
7 EXIT
8 FILE *CLOSE filename
9 MESSAGE fileerrmsg
10 EXIT

In this logic block, the file filename is locked to the logic block. The
file is locked at step 2 when the first file access occurs. When the
logic block is completed or an error occurs, the file is closed,
releasing the file locks.

MPE/iX 5.0 Documentation