HP 3000 Manuals HP 3000 Manuals
DM IMAGE *LOCK Command
The DM IMAGE *LOCK command locks an entire HP TurboIMAGE/iX database, or
specifed data sets or records within an HP TurboIMAGE/iX database.
Formats
DM IMAGE *LOCK :D-database [descriptor]...[;command]
Parameters
database
The name of the HP TurboIMAGE/iX database that is to be fully or
partially locked. The name must be an HP ALLBASE/4GL name for the
database, as defined in the administrator application.
descriptor
The descriptors identify the parts of the database to be locked. This
field is optional. If you do not supply a descriptor, the entire
database is locked.
Each descriptor takes the following format:
{:R-fileref }
descriptor = {:F-field.fileref <= value}
{:F-field.fileref >= value}
{:F-field.fileref = value }
field
The name of a field specification.
fileref
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 of the file.
value
The value can be one of the following:
* Numeric or alphanumeric literal.
* Numeric or alphanumeric constant.
* Master title.
* Scratch-pad field reference.
* Screen field reference.
* File record field reference.
* Variable or calculated item.
* Work area field reference.
* Communication area field.
You must precede a reference to an HP ALLBASE/4GL item with a colon (:).
That is, you must express the reference in the format:
:V-due_date
Literal text must not be preceded by a colon.
command
A command to be executed if an error occurs while the DM IMAGE *LOCK
command is being executed. You can use any of the following commands:
* ENTER
* EXIT
* EXTERNAL
* MESSAGE
* PROCEED
* SERIES
* TOP
* VISIT
* ZIP
Description
This command allows you to lock all or parts of an HP TurboIMAGE/iX
database. The lock is maintained until one of the following occurs:
* A DM IMAGE *UNLOCK command is executed for the locked database.
* A DM IMAGE *CLOSE command is executed for the locked database.
* A FILE *UNLOCK command is executed for any part of the database
(if any locked data sets have an access mode of MODE *WRITE or
MODE *UNLOCK).
* The current process ends.
Locking Strategy.
In general, you should establish locks that cover all records that you
intend to modify, or all records which must not change during the
transaction. However, you must also consider whether other users would
be likely to access the same database or data set at the same time. If
you lock a whole database, no other user can alter any part of the
database. A data set lock ensures that all records within the data set
will not be accessed by another user.
You do not need to lock any parts of a database accessed when the DM
IMAGE *MODE is set to *MODEXCL or *READEXCL, because these modes
guarantee the user exclusive use of a database.
When adding or deleting entries from a detail data set, record level
(data entry level) locking is sufficient. You do not need to have locks
covering additions or deletions that occur in any associated automatic
masters.
To delete or insert master data set records, use data set level locking.
For updating master data set records, record level locks are adequate.
If you wish to establish multiple record level locks for a single data
set, each lock descripter must use the same field (or data item) to
identify the record. HP TurboIMAGE/iX does not allow more than one field
per data set to be used for locking purposes at the same time. You may
also use the DM IMAGE *LOCK command to lock the whole data set instead.
For more guidance, use the locking guidelines provided in the HP
TurboIMAGE/iX Database Management System Reference Manual.
The DM IMAGE *LOCK command maps to the HP TurboIMAGE/iX DBLOCK library
procedure. If the *LOCKWAIT communication area field contains the value
-1, the lock is unconditional, and mode 1, 3 or 5 of the DBLOCK library
procedure is used, depending upon the descriptor provided. Otherwise,
mode 2, 4 or 6 of the DBLOCK library procedure is used, depending upon
the descriptor provided.
*LOCKWAIT Communication Area Field
If any of the specified records, data sets, or databases are already
locked, you may use the *LOCKWAIT communication area field to make the
current process or function wait for the lock to be released.
The actions taken by HP ALLBASE/4GL for different values in *LOCKWAIT are
summarized below.
Value Action
+n HP ALLBASE/4GL attempts to lock the file every second for n
seconds. If the file cannot be locked after n seconds, HP
ALLBASE/4GL returns an error number 19107.
0 HP ALLBASE/4GL attempts to lock the record every second for 5
seconds. If the record cannot be locked after 5 seconds, HP
ALLBASE/4GL returns an error number 19107.
-1 HP ALLBASE/4GL waits indefinitely to access locked records.
Implicit Locking.
If you do not use the DM IMAGE *LOCK command, HP ALLBASE/4GL will use
implicit locking when data sets are accessed. The type of implicit
locking is determined by the MODE command.
For details about implicit locking, refer to the FILE Command (HP
TurboIMAGE/iX) and the MODE command.
Example 1
DM IMAGE *LOCK :D-stock_ctrl
This command locks all records within the stock_ctrl database.
Example 2
DM IMAGE *LOCK :D-stock_ctrl :F-supp_no.supplier = V-last_supplier}
This command locks all records in the supplier data set (which is part of
the stock_control database), where the supplier number (supp_no) equals
the value of the last_supplier variable.