HP 3000 Manuals

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

HP ALLBASE/4GL Developer Reference Manual Vol. 2

FILE Command (HP TurboIMAGE/iX)

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 HP TurboIMAGE/iX
data sets.

Formats

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

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

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

FILE *READ {[*REC = recno] }[*NOLOCK]file_ref
{[*KEY = key] [*INDEX = index_name]}
Window

Parameters

file_ref

Specifies the HP ALLBASE/4GL name of the application data set 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 data set, HP ALLBASE/4GL uses
the default record for the data set.

*NOLOCK

The *NOLOCK term is a command argument to control file locking for the
data set access. If the *NOLOCK argument is present, no implicit locking
is performed when the data set is accessed, provided the data set is not
already locked. If the data set has already been locked by an earlier
access, the *NOLOCK argument has no effect. The *NOLOCK also has no
effect on locks set by the DM IMAGE *LOCK command. Refer to Data Set
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 data set. 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 data set. You can also specify the
index by entering the number of an index for the data set.

The index you specify here is used for one data set 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
data set according to the index specified by the current value of
*INDEXNO.

key

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

* A literal.

* An alphanumeric constant.

* A variable or calculated item.

* A screen field reference.

* A scratch-pad field reference.

* A file record field reference.

* A work area field reference.

* A non-numeric communication area field.

This parameter is optional. If you don't specify a key, HP ALLBASE/4GL
accesses the data set 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 data set operation fails. You
can use any of the following HP ALLBASE/4GL logic commands:

* ENTER

* EXIT

* EXTERNAL

* MESSAGE

* PROCEED

* SERIES

* TOP

* VISIT

* ZIP

recno

HP ALLBASE/4GL allows you to access an HP TurboIMAGE/iX data set record
by specifying the number of the record. Record number 1 is the first
physical record in the data set.

You can specify recno with any of the following items containing a
non-negative integer number.

* A whole number.

* A numeric constant.

* A variable or calculated item.

* A screen field reference.

* A scratch-pad field reference.

* A file record field reference.

* A work area field reference.

* A communication area field.

Using FILE *READ with the *REC = recno option performs the same task as
the HP TurboIMAGE/iX library procedure DBGET in mode 4 (directed read).

Description

The FILE command performs various operations on HP TurboIMAGE/iX data
sets.

Opening and Closing Data Sets

HP ALLBASE/4GL automatically opens an HP TurboIMAGE/iX data set when it
is first read, written to, or locked, in an HP ALLBASE/4GL process.
There is no need to explicitly open an HP TurboIMAGE/iX data set. If a
data set is specifically closed (refer to *CLOSE below), HP ALLBASE/4GL
automatically reopens the data set when it is next accessed.

HP ALLBASE/4GL automatically closes all HP TurboIMAGE/iX data sets at the
start of a process. A data set can also be specifically closed using the
FILE *CLOSE command, which is described later. All data sets in a
database, that is, the whole database, can be closed at once using the DM
IMAGE *CLOSE command.

File Indexes

The communication area field *INDEXNO specifies the number of the index
used to access the data set. HP ALLBASE/4GL initializes the value in
this field to 1 when the application starts, assuming that all data set
access is via the data set primary index. 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 in a data set with more than one index, you
must set *INDEXNO to the number of the required data set index before the
FILE command is executed.

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

File Access Modes

The DM IMAGE *MODE command and the MODE command work in conjunction to
set the access mode for the database and data sets.

You must ensure that the access mode for the database is set
appropriately with the DM IMAGE *MODE command. If no DM IMAGE *MODE is
specified, the default mode allows shared read access (with locks) to all
data sets within a database.

You must also specify the data set access modes for any data sets that
are to be accessed in the current HP ALLBASE/4GL process by using the
MODE command with the *READ, *WRITE, *LOCK, or *UNLOCK argument. (Refer
to the MODE command.) If you do not specify a data set access mode, the
default mode *READ is assumed.

The capabilities specified in the MODE command must be a subset of the
capabilities specified in the DM IMAGE *MODE command. (Refer to the DM
IMAGE *MODE command for more information.)

File Record Buffers and Position Pointers

HP ALLBASE/4GL maintains a separate buffer for each record layout defined
for each data set. HP ALLBASE/4GL clears the data set record buffer or
buffers automatically when a data set is first accessed, or at the start
of any process.

Where multiple record layouts have been defined for an HP TurboIMAGE/iX
data set, data in one record buffer is not automatically available to
another record buffer for the same data set. To make the data available,
you can read the record again, or move the data between buffers using
either the MOVE or MOVELOOP commands. This will only work if both record
layouts have the same structure.

HP ALLBASE/4GL also maintains a data set position pointer which contains
the address of the current record.

Communication Area Fields

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

File Operations

Operations you can perform on HP TurboIMAGE/iX data sets are:

*BUFFER. Clears the specified buffer of all data. The buffer cleared is
defined by file_ref. Unless the data set has been opened in mode
*UNLOCK, clearing the data set record buffer unlocks the current data set
record.

*CLOSE. Closes the nominated data set. You can use this operation to
close any data set that is not required. HP ALLBASE/4GL automatically
reopens the data set if it is accessed after being closed. Data sets are
automatically closed when the process exits. They are also closed when
the entire database is closed with the DM IMAGE *CLOSE command.

*DELETE. Deletes a record from the data set.

Detail data set records must be read before they can be deleted. If you
haven't read a record, HP ALLBASE/4GL returns an error number.

Master data sets act as indexes to detail data sets, so you cannot delete
a master data set record if any detail data set records contain the key
value of the master data set record.

When a manual master data set record is deleted, it may cause a secondary
record in the data set to migrate to the position of the deleted record.
If the next serial operation were to move the data set position pointer
to the next or previous record, the record migrating to the position of
the deleted record would not be read. To avoid this, HP ALLBASE/4GL sets
an indicator so that the next serial operation re-establishes the data
set position pointer on the same record. For more information about
migrating secondary records, refer to the HP TurboIMAGE/iX Database
Management System Reference Manual.

The following diagram illustrates backward migration. Forward migration
is similar.

Automatic master data set records are deleted automatically if all the
detail data set records linked to it are deleted.

*FIND

For detail data sets, *FIND finds the first record whose key is equal to
the value of key. This operation is used to place the data set position
pointer at the beginning of a chain of detail data set records with the
same key value. After the *FIND operation, *NEXT and *PREVIOUS
operations will move the pointer along the chain rather than serially
through the records.

Master data sets must contain unique keys, so chains of records with
identical key values do not exist. To find the record in a master data
set with a certain key value, *FIND mimics the operation of *READ *KEY =
key.

*FIND only places the data set position pointer; to move the data into
the record buffer, use the FILE *NEXT operation. Because HP ALLBASE/4GL
maintains only one position pointer for each data set, you must use the
*NEXT operation before you perform any other operation on the same data
set.

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

*FIRST. Reads the first record for the data set.

If *KEY is not specified, the first record in serial order is read. If
*KEY is specified, the first record with that key value is read.

*INSERT. Adds a new record to the data set.

This operation adds new records to detail data sets. HP TurboIMAGE/iX
also adds a record to any automatic master data sets linked to the detail
data set.

This operation causes an error if a manual master data set linked to the
detail data set does not contain a record with the key value of the
detail data set being added.

Using *INSERT with master data sets causes an error if you attempt to add
a record to the data set with a primary key value the same as one that
already exists.

*LAST. Reads the last record for the data set.

If *KEY is not specified, the last record in serial order is read. If
*KEY is specified, the last record with that key value is read.

*MODIFY. Changes an existing record in the data set. Automatic master
data sets linked to a detail data set that is modified are automatically
updated.

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

You can only alter a key value for a master data set if no detail data
sets linked to the master data set have records containing the key value.

When a master data set record is modified and a key value is changed, the
record may be moved to a new address and cause a secondary record to
migrate to the position of the modified record. Because of this, do not
use the FILE *NEXT or FILE *PREVIOUS command after modifying the key
value of a master data set record. The record migrating to the old
position of the modified record may not be read.

*NEXT. Serially reads the next record in the data set.

For detail data sets, it is possible to read along a chain of records
with the same key value. This will occur if the *NEXT operation is
preceded by a *FIND operation, or a *READ operation with a key provided.
If the *NEXT operation is executed when the data set position pointer is
at the end of a chain, HP ALLBASE/4GL returns the error status 19115.

In some cases, for master data sets, *NEXT re-reads the current record.
This occurs when a secondary master data set record has migrated backward
to the position of a newly deleted record. If *NEXT was to move the data
set position pointer to the next record before the read, the record
migrating backward to the position of the deleted record would not be
read. To avoid this, HP ALLBASE/4GL sets an indicator so that *NEXT
re-establishes the data set position pointer at the same position before
the read. For further information about migrating secondary records,
refer to the HP TurboIMAGE/iX Database Management System Reference
Manual.

With master data sets, do not use a FILE *NEXT command after a FILE
*MODIFY command that modifies a key value. The record migrating to the
old position of the modified record may not be read.

*PREVIOUS. Serially reads the previous record in the data set.

For detail data sets, it is possible to read along a chain of records
with the same key value. This will occur if the *PREVIOUS operation is
preceded by a *FIND operation, or a *READ operation with a key provided.
*PREVIOUS reads the previous record in the chain. If the *PREVIOUS
operation is executed when the data set position pointer is at the start
of a chain, HP ALLBASE/4GL returns the error status 19115.

In some cases, for master data sets, *PREVIOUS re-reads the current
record. This occurs when a secondary record has migrated forward to the
position of a newly deleted record. If *PREVIOUS was to move the data
set position pointer to the next record before the read, the record
migrating forward to the position of the deleted record would not be
read. To avoid this, HP ALLBASE/4GL sets an indicator so that *PREVIOUS
re-establishes the data set position pointer at the same position before
the read. For further information about migrating secondary records,
refer to the HP TurboIMAGE/iX Database Management System Reference
Manual.

With master data sets, do not use a FILE *PREVIOUS command after a FILE
*MODIFY command that modifies a key value. The record migrating to the
old position of the modified record may not be read.

*READ. If a key value is specified, *READ reads the first record in the
data set whose key value exactly matches the value specified by *KEY =
key. If you don't specify the *KEY = key argument in the FILE command,
HP ALLBASE/4GL uses the current value in the record buffer field
specified by *INDEXNO or the *INDEX = argument.

If you include the *REC = recno argument, *READ reads the specified
record number. If no record exists at that address, HP ALLBASE/4GL
returns an error status 19111.

In some cases, for master data sets, *READ re-reads the current record.
This occurs when a secondary record has migrated backward to the position
of a newly deleted record. If *READ was to move the data set position
pointer to the next record before the read, the record migrating backward
to the position of the deleted record would not be read. To avoid this,
HP ALLBASE/4GL sets an indicator so that *READ re-establishes the data
set position pointer at the same position before the read. For further
information about migrating secondary records, refer to the HP
TurboIMAGE/iX Database Management System Reference Manual.

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

NOTE If you unlock a data set, you release ALL locks held on the
database that contains the data set specified in the *UNLOCK
operation.

*WRITE. Writes a new record or modifies an existing record within a
manual master data set.

You cannot use this operation for automatic master data sets because
these are automatically maintained by HP TurboIMAGE/iX.

Don't use this operation for detail data sets, which allow duplicate
primary keys. Use the *INSERT operation instead.

When you use this operation for manual master data sets, one of the
following actions occurs:

* If a record exists on the data set whose primary key matches the
primary key value in the record buffer, the data set 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 data set.
The addition 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 data set only.

Error Handling

HP ALLBASE/4GL executes an optional logic command specified in the FILE
command if an error occurs as a result of the data set access. For
example, when performing a *NEXT operation, the optional command is
executed if the end of the data set 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
data set command is successful.

If you include the optional error command, no data manager errors are
displayed on the terminal screen.

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 file error returns.

*IOSTATUS

Value Condition

19000 MPE/iX file access error detected by HP
TurboIMAGE/iX.

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.

19115 Beginning or end of detail data set chain reached
during a *NEXT or *PREVIOUS file operation.

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

In addition to HP ALLBASE/4GL error numbers, each HP TurboIMAGE/iX
library procedure returns a status array. This is recorded in the
*IMSTAT communication area field. The first halfword (16 bits) of the
status array contains the HP TurboIMAGE/iX error number, and this error
number is also returned to the *IOSTATDM communication area field.

The meaning of status arrays and error numbers returned by HP
TurboIMAGE/iX library procedures can be found in the HP TurboIMAGE/iX
Database Management System Reference Manual. Refer to chapter 10 of this
manual for a list of the common library procedures initiated by HP
ALLBASE/4GL.

The communication area field *ERRORDM contains the text of any error
messages returned from HP TurboIMAGE/iX.

Data Set Locking

You may control data set locking with the DM IMAGE *LOCK and *UNLOCK
commands. This allows you to make the best use of HP TurboIMAGE/iX
locking capabilities, and is recommended for applications with multiple
users. If you do not use these commands, HP ALLBASE/4GL uses implicit
locking. The type of implicit locking used is determined by the MODE
command.

HP TurboIMAGE/iX provides three levels of explicit locking; database
locking, data set locking, and record locking. All three levels of
locking are provided by the DM IMAGE *LOCK command. To delete or insert
detail data set records, only record level locking is required. To
delete or insert master data set records, use data set level locking.
For updating master data set records, record level locks are adequate.

Implicit File Locking.

Implicit data set locking in HP ALLBASE/4GL depends on both the data set
operation used with the FILE command and the data set access mode
specified by the MODE command.

MODE *WRITE should be used with care. It does not guarantee any
transaction integrity, but can be used by developers without significant
knowledge of HP TurboIMAGE/iX locking. When using MODE *WRITE, a data
set level lock is placed.

The record remains locked to the current process until another record is
accessed through the same file buffer, the buffer is cleared, the file is
closed, or a FILE *UNLOCK command is executed.

NOTE When a lock is released, all locks held on the database are
released.

MODE *UNLOCK is similar to MODE *WRITE, except that a lock is not
released until a specific FILE *UNLOCK command is executed. If a data
set is locked, another user or process cannot lock the same data set
while the lock is current.

The command MODE *LOCK specifies that the process has write access to the
file. Each file is locked when it is first accessed. The file or files
remain locked until the end of the process, or the files are closed.

While a file is locked to a process that uses the *LOCK form of the MODE
command, another process or user can read the file provided that the file
is accessed under MODE *READ.However, while the MODE *LOCK command is in
effect, other processes or users cannot write to the file or lock the
file.

The following table summarizes the data set access and locking that can
occur if two users (or a user and a background process) attempt to access
the same data set.

Under the MODE *LOCK, MODE *WRITE, or MODE *UNLOCK commands, the data set
is normally locked when it is first accessed. However, the data set is
not locked if you access the data set using a command that contains the
*NOLOCK argument. Any read or write access that does not use the *NOLOCK
argument will lock the data set. It remains locked until one of the
following occurs:

* The process ends.

* The data set is closed with the FILE *CLOSE command.

* Any data set from the same database is unlocked with the FILE
*UNLOCK command within the current process.

Data set locks are also released by a DM IMAGE *CLOSE command or a
TRANSACT *END command.

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

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

*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 data set 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 attempts to access the data set every second
for n seconds. If the data set is not accessible after n
seconds, HP ALLBASE/4GL returns an error number 19107.

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

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

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 data set stock, and searches for a record with its
key value equal to the value of the screen 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 data set 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 data set trans. When
the system encounters the end of the data set, 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 data set 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 DM IMAGE *MODE *MODLOCK :D-customer_db
2 MODE *WRITE customer
3 DM IMAGE *LOCK :D-customer_db :R-customer
.
5 FILE *WRITE customer *KEY=*; ENTER 8
6 FILE *CLOSE customer
7 EXIT
8 MESSAGE customer_errmsg
9 EXIT

In this logic block, the database customer_db is opened in a mode that
allows shared modify access to the database if data sets are locked. The
data set access mode is set to *WRITE in step 2, and step 3 locks the
customer data set. If step 5 executes correctly, the data set closes and
all locks on the database are released. If an error occurs, the data set
remains open until the end of the current process.

The database is not closed until the end of the HP ALLBASE/4GL session,
or until the DM IMAGE *CLOSE logic command is issued.

MPE/iX 5.0 Documentation