HP 3000 Manuals HP 3000 Manuals
DBLOCK
INTRINSIC NUMBER 409
Applies a logical lock to a database, one or more data sets, or one or
more data entries.
Syntax
DBLOCK,base,qualifier,mode,status
Parameters
base is the name of the array used for the base
parameter when opening the database. The first
element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more
information about base ID.)
qualifier Modes 1 and 2: Ignored.
Modes 3 and 4: An integer variable referencing the
data set number or the name of an array containing
a data set name. Could also be "@", when applying
a database lock.
Modes 5 and 6: The name of the array containing
the lock descriptors. The format for lock
descriptors is given in Figure 5-2 .
Use care when changing modes. The qualifier
parameter can also change.
mode contains an integer indicating the type of locking
desired (refer to Table 5-15 ).
__________________________________________________
NOTE If the database is open in user access mode
1, a lock must be in effect on either the
data set or the whole database when adding to
or deleting from master data sets. If a data
entry level lock is specified, any subsequent
DBPUTs or DBDELETEs will fail with error
number -12 and the following message is
returned:
intrinsic name CALLED WITHOUT COVERING LOCK IN EFFECT
Note, however, that a lock on either the
entire database or data set can be achieved
with a data entry lock when an @ sign is used
to specify either all data sets or all data
items.
__________________________________________________
status is the name of an array of 10 halfwords in which
TurboIMAGE/XL returns status information about the
procedure. If the procedure executes successfully,
the status array contents are:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-17 describes
the contents of element 1 when the
procedure does not succeed.
2 The number of lock descriptors that were
successfully applied in the DBLOCK
request. For successful locks in modes
1 through 4 this will be 1.
3 If the return status is 20, this element
contains 0 if the database is locked, 1
if the data set or entries are locked.
4 Reserved: Contents undefined.
5-10 Information about the procedure call and
its results. Refer to "Library
Procedure Error Messages" in appendix A
for a complete description of this
information.
NOTE Concurrent processes running in a process-handling environment must
have MR capability if they call DBLOCK.
Discussion
The format of the array containing a list of lock descriptors is
illustrated in Figure 5-2 and applies only for locking modes 5 or 6.
The number of lock descriptors (n) is a one-halfword binary integer.
Only the first n lock descriptors are processed. If n is zero, DBLOCK
returns without taking any action. The format of a lock descriptor is
illustrated in Figure 5-3 , and the lock descriptor fields are
described in Table 5-16 .
The shortest possible descriptor is 9 halfwords long consisting of the
length field and a dset field containing @. Although the dset field only
contains an at-sign, it must still be 8 halfwords long. The length of
the entire descriptor array cannot exceed 4094 bytes.
Lock descriptors are sorted by data set number, then by value provided
for the lock item. TurboIMAGE/XL does not sort by item within the set,
because more than one item per data set constitutes a conflicting lock
descriptor (TurboIMAGE/XL error -134).
Table 5-15. Locking Mode Options
-------------------------------------------------------------------------------------------------
| | | | |
| Lock | Lock | Locking | |
| Mode | Level | Type | Description |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| 1 | Base | Unconditional | DBLOCK applies an unconditional lock to the whole |
| | | | database, returning to the calling program only |
| | | | after the lock is successful (or if an error |
| | | | occurs). The qualifier parameter is ignored. |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| 2 | Base | Conditional | DBLOCK applies a conditional lock to the database |
| | | | and returns immediately. A return status of zero |
| | | | indicates success. A non-zero return status |
| | | | indicates the reason for failure. (Refer to Table |
| | | | 5-17.) |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| 3 | Set | Unconditional | DBLOCK applies an unconditional lock to a data set. |
| | | | The qualifier parameter must specify the name of an |
| | | | array containing the left-justified name of the |
| | | | data set or the name of an integer referencing the |
| | | | data set number. The data set name can be 16 |
| | | | characters long or, if shorter, terminated by a |
| | | | semicolon or blank. |
| | | | |
| | | | The data set need not be accessible for read or |
| | | | write access to the user requesting the lock. |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| 4 | Set | Conditional | DBLOCK applies a conditional lock of the same type |
| | | | as mode 3. It always returns to the calling |
| | | | program immediately. A return status of zero |
| | | | indicates success and a non-zero return status |
| | | | indicates a reason for failure. (Refer to Table |
| | | | 5-17.) |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| 5 | Entry | Unconditional | DBLOCK applies unconditional locks to the data |
| | | | entries specified by lock descriptors. The |
| | | | qualifier parameter must specify the name of an |
| | | | array containing the lock descriptors. The format |
| | | | of the array is shown in Figure 5-2. It returns |
| | | | only when all the locks have been acquired. |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| 6 | Entry | Conditional | DBLOCK applies conditional locks of the same type |
| | | | as mode 5. If multiple lock descriptors are |
| | | | specified and DBLOCK encounters a lock descriptor |
| | | | that it cannot apply, it returns. All locks that |
| | | | have been applied until that point are retained. |
| | | | |
| | | | Because the locks are not executed in the order |
| | | | supplied by the user, it is not predictable which |
| | | | locks are held and which are not after an |
| | | | unsuccessful mode 6 DBLOCK. Status element 2 |
| | | | indicates how many lock descriptors were actually |
| | | | successful. It is recommended that a DBUNLOCK be |
| | | | issued after any unsuccessful mode 6 DBLOCK. |
| | | | |
-------------------------------------------------------------------------------------------------
NOTE Be careful when changing modes. The qualifier parameter can
change.
![[]](../../pic3k/M012332/FFN253c50.gif)
Figure 5-2. Qualifier Array Format for Locking Modes 5 and 6
![[]](../../pic3k/M012332/FFN263c50.gif)
Figure 5-3. Lock Descriptor Format
Table 5-16. Lock Descriptor Fields
---------------------------------------------------------------------------------------------
| | |
| Field Name | Description |
| | |
---------------------------------------------------------------------------------------------
| | |
| length | A halfword integer specifying the physical length in halfwords of the |
| | lock descriptor, including the length field itself. |
| | |
---------------------------------------------------------------------------------------------
| | |
| dset | Describes the data set in which locks are placed. It is always 8 |
| | halfwords long and can be one of the following: |
| | |
| | |
| | * A data set name, left-justified, 16 characters long or, if |
| | shorter, terminated with a blank or semicolon (for example, |
| | SALES;). |
| | |
| | * A data set number, an integer in the range of 1 to 199 stored |
| | in the first element. |
| | |
| | * An at-sign (@) stored in the first byte of the dset and a lock |
| | descriptor length of 2 indicating that the whole database is |
| | to be locked. All unused bytes are ignored. In this case, |
| | the ditem, relop, and value fields are ignored and can be |
| | omitted if desired. |
| | |
| | * A blank or semicolon (first byte) or binary zero (first |
| | halfword) indicating that the whole lock descriptor is to be |
| | ignored. (It is counted as one of the n descriptors.) |
| | |
| | The data set, if specified, need not be accessible for read or write |
| | access to the user requesting the lock. |
| | |
---------------------------------------------------------------------------------------------
| | |
| ditem | Always 8 halfwords long unless an @ is stored in the first byte. It |
| | can be one of the following: |
| | |
| | * A data item name, left-justified, 16 characters long or, if |
| | shorter, terminated with a blank or semicolon. |
| | |
| | * A data item number stored as an integer in the first halfword. |
| | It can be in the range of 1 to 1023. |
| | |
| | * An at-sign (@) stored in the first byte of the dset indicating |
| | that the whole data set specified in dset is to be locked. |
| | All unused bytes are ignored and can be omitted if desired. |
| | |
| | The data item need not be a search item, nor does it have to be |
| | accessible to the user requesting the lock. However, it cannot be a |
| | compound item or a P-type item longer than P28. |
| | |
---------------------------------------------------------------------------------------------
| | |
| relop | One halfword long, it contains one of the three relational operators |
| | represented as two ASCII characters: |
| | |
| | <= less than or equal |
| | |
| | >= greater than or equal |
| | |
| | =_ or _= equal (_ indicates space character) |
| | |
---------------------------------------------------------------------------------------------
| | |
| value | The value of the data item to be locked. It must be stored in |
| | exactly the same way as it is stored in the database. TurboIMAGE/XL |
| | extracts as many halfwords as required by the corresponding data item |
| | definition (in the schema). The rest (if any) are ignored. |
| | |
---------------------------------------------------------------------------------------------
If you specify a data item of type P, U, or Z in a lock descriptor,
TurboIMAGE/XL checks that the value is valid for that data item type.
The following checks are made:
* If the data item is type P, the right half of the rightmost byte
must contain a sign and all preceding nibbles must contain decimal
digits represented in Binary Coded Decimal (BCD) format. For
example, if a data item is defined as type P with a length of 20,
the format must be as shown here:
![[]](../../pic3k/M012332/FFN273c50.gif)
This would be declared in COBOL II as 19 digits plus a sign or 20
nibbles (P20 in the schema):
S9(19) COMP-3
Type P data item used in a lock descriptor cannot exceed 28
nibbles (7 halfwords) in length. The locking system treats all
sign digits other than 11012 as identical. 11012 is assumed to be
a negative sign.
* If the data item is type U, the value cannot contain any lowercase
alphabetic characters in the range of a through z (for non-native
language use only).
* If the data item is type U or X, and a lock specifies an
inequality, the language of the database is used.
* If the data item is type Z, each byte preceding the last one must
contain an 8-bit digit represented in ASCII format and the last
byte must contain a value representing a digit and a sign.
* If the data item is type R, it is sorted based on the HP 3000
floating point number format.
Table 5-17. DBLOCK Return Status Values
-----------------------------------------------------------------------------------------------
| Calling Errors: | -11 | Bad database reference. |
| | -31 | Bad mode value. |
| | -121 | Descriptor count error. |
| | -123 | Illegal relop in a descriptor. |
| | -124 | Descriptor too short. Must be greater than or |
| | -125 | equal to 9. |
| | -126 | Bad set name/number. |
| | -127 | Bad item name/number. |
| | -128 | Attempt to lock using a compound item. |
| | -129 | Value field too short in a descriptor. |
| | -130 | P-type item longer than P28 specified. |
| | -131 | Illegal digit in a P-type value. |
| | -132 | Lowercase character in type U value. |
| | -133 | Illegal digit in type Z value. |
| | -134 | Illegal sign in type Z value. |
| | -135 | Two descriptors conflict. |
| | -136 | DBLOCK called when locks already in effect. |
| | -222 | Descriptor list exceeds 4094 bytes. |
| | | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
-----------------------------------------------------------------------------------------------
| Communications Errors: | -102 | DSWRITE failure. |
| | -103 | Remote 3000 stack too small. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
-----------------------------------------------------------------------------------------------
| Exceptional Conditions: | | Applicable Modes |
| | 20 | Database locked or contains locks. (2,4,6) |
| | | (Status element 3: 0 = database |
| | | locked (2) |
| | 22 | 1 = data set or entries locked) (4,6) |
| | 23 | Data set locked by another (4,6) |
| | 24 | process. (6) |
| | 25 | Entries locked within set. (6) |
| | 26 | Item conflicts with current locks. (1,2,3,4,5,6) |
| | 62 | Entry or entries already locked. (3,4,5,6) |
| | | Lock not performed since deadlock |
| | | would occur. |
| | | DBG full. |
| | | (If this error occurs when |
| | | multiple lock descriptors are |
| | | specified, some of the descriptors |
| | | may have been successfully |
| | | completed. If so, they are not |
| | | unlocked by TurboIMAGE/XL before |
| | 63 | returning the error. Therefore, |
| | | issue a DBUNLOCK after any |
| | -192 | positive-numbered error, unless |
| | | you have reason to do otherwise.) |
| | | DBG disabled; potential damage; |
| | | only DBCLOSE allowed. |
| | | Invalid DBU. |
-----------------------------------------------------------------------------------------------
Appendix A contains more information about these conditions.