This API lets obtain chunks of lists of locked PAC entities.
APINLCKS can be invoked with:
CALLNAT 'APINLCKS' API-PARM API-LCKS-PARM
To obtain a chunk, set API-PARM.API-MAIN-FUNC to 'D'. The value of API-PARM.API-SUB-FUNC is ignored. A definition of API-LCKS-PARM is provided in LDA UPILLCKS.
This document covers the following topics:
A definition of API-LCKS-PARM is provided in LDA UPILLCKS.
| Field Name | Format | I/O |
|---|---|---|
| API-LCKS-PARM | ||
| LOCK-USER | A9 | in |
| LOCK-TIME-FM | T | in |
| LOCK-TIME-TO | T | in |
| LOCK-FLAGS | A32 | in |
| LOCK-FLAGS | ||
| LOCK-FLAG | L (0:31) | |
| LOCK-APPLICATION | A32 | in |
| LINE-CNT | N3 | in/out |
| LINE-TOT | N10 | out |
| LINE | A250 (1:10) 1* | in/out |
| LINE | out | |
| LINEA | (1:10) | |
| LCK-USER | A8 | |
| LCK-TID | A8 | |
| LCK-TIME | T | |
| LCK-CLAUSE-1 | A50 | |
| LCK-CLAUSE-2 | A50 | |
| MOD-USER | A8 | |
| MOD-TID | A8 | |
| MOD-TIME | T | |
| ENT-CODE-1 | A1 | |
| ENT-CODE-2 | A5 | |
| ENT-ID-1 | A32 | |
| ENT-ID-2 | A32 | |
| ENT-ID-3 | B8 | |
| ENT-ID-4 | A5 | |
| ENT-ID-5 | I2 | |
| ENT-ID-6 | B4 | |
| ENT-ID-7 | B4 | |
| API-PAC-AREA | A64 | in/out |
1*: This is the proposed default value. Any value equal or greater 1 can be defined by the user.
If APINLCKS is called with all "in" parameter fields reset, it returns, chunk by chunk, a list of all locked entities in the current ACF.
The LOCK- fields can be used to restrict the listing of locked entities.
API-LOCK-PARM.LOCK-USER should carry a range of user IDs or be blank. Only entities locked for a user ID within the specified range will be selected.
A blank API-LOCK-PARM.LOCK-USER has the same effect on the selection of entities as it would have if it carried an initial asterisk.
API-LOCK-PARM.TIME-FM should, if not reset, carry a lower bound for the time of the locking of any entity to be selected.
If API-LOCK-PARM.TIME-FM = 0 then the selection of entities is not restricted on the account of this parameter.
API-LOCK-PARM.TIME-TO should, if not reset, carry an upper bound for the time of the locking of any entity to be selected.
If API-LOCK-PARM.TIME-TO = 0 then the selection of entities is not restricted on the account of this parameter.
API-LOCK-PARM.FLAGS is, unless blank, interpreted as an array of switches indicating the kinds of the locked entities to be selected. The correspondence between the numbers of the switches (the [I]s of API-LOCK-PARM.FLAG(I)) and the kinds of entities is the following:
| 0 | any kind not listed in the remainder of this table |
| 1 | job |
| 2 | object |
| 3 | status |
| 4 | application |
| 5 | event |
| 6 | FTT |
| 7 | application-status link |
| 8 | object-status link |
| 9 | migration path |
API-LOCK-PARM.APPLICATION should, unless blank, carry the name of an application. Only locked entities pertaining to the specified application will be selected. If API-LOCK-PARM.APPLICATION = ' ' then the selection of entities is not restricted on the account of this parameter.
[API-LCKS-PARM.LINE-CNT] is made 0, if negative; it is made 10, if greater than 10. It is then interpreted as the number of lines (the size of the chunk) to be returned. In particular, no lines will be returned, if LINE-CNT = 0. APINLCKS returns in API-LCKS-PARM.LINE-CNT the number of lines of the returned chunk. It may be less than the adjusted original value, if the end of the list has been reached.
When APINLCKS returns the last chunk of the list it also returns, in API-LCKS-PARM.LINE-TOT, the total number of the lines of the list.
API-LCKS-PARM.LINE will carry the returned chunk.
The various subfields of a API-LCKS-PARM.LINE(I) for any I in {1,...,[API-LCKS-PARM.CNT]} are used as follows:
| LCK-USER | carries the user ID for which the entity is locked. | ||||||||||||||||||||||
| LCK-TID | carries the terminal ID with which the lock is marked. | ||||||||||||||||||||||
| LCK-TIME | carries the time of the locking of the entity. | ||||||||||||||||||||||
| LCK-CLAUSE-1 and LCK-CLAUSE-2 | carry the contents of two fields used by PAC and to link locked entities one to another and indicate the kind of the lock. | ||||||||||||||||||||||
| MOD-USER | carries the user ID with which the entity was last modified. | ||||||||||||||||||||||
| MOD-TID | carries the terminal ID with which the entity was last modified. | ||||||||||||||||||||||
| MOD-TIME | carries the time of the last modification of the entity. | ||||||||||||||||||||||
| ENT-CODE-1 | carries a code of the kind of the entity. The
codes used in this field are the following:
|
||||||||||||||||||||||
| ENT-CODE-2 | carries an internal code of the kind of the entity. | ||||||||||||||||||||||
| ENT-ID-1 | carries the name or the first part of the compound name of the entity. The first part of a compound name is application name for an application-status link; it is object name for an object-status link. | ||||||||||||||||||||||
| ENT-ID-2 | carries status name for an application-status link or an object status link. | ||||||||||||||||||||||
| ENT-ID-3 to 7 | may carry some further entity attributes not readily usable by an end-user. |
Normally, API-LCKS-PARM.API-PAC-AREA should be reset when the first chunk of a list of locked entities is wanted. API-LCKS-PARM.API-PAC-AREA should be left untouched for a next call to obtain an immediately following chunk of the same list.
APINLCKS returns the following [API-PARM.API-MSG-NO]:
| 0000 | if a non-final chunk of the list of locked entities is being returned. |
| 1011 | if the specified [API-PARM.API-MAIN-FUNC] is meaningless (ie, is not 'D'). |
| 7205 | if the "initialisation" has failed, ie, logical files 210 and 211 have not been found set at a pair of matching ACF and PCF. |
| 7251 | if [LOCK-APPLICATION] has been specified but not found to be an application name. |
| 9999 | if the final chunk of the list of locked entities is being returned. |
Other values of API-PARM.API-MSG-NO may be received in more unusual situations.