Advantage Client Engine
Returns an array of information about records that are currently locked on the Advantage Database Server
UNSIGNED32 |
AdsMgGetLocks ( ADSHANDLE hMgmtConnect, UNSIGNED8 *pucTableName, UNSIGNED8 *pucUserName, UNSIGNED16 usConnNumber, ADS_MGMT_RECORD_INFO astRecordInfo[], UNSIGNED16 *pusArrayLen, UNSIGNED16 *pusStructSize ); |
hMgmtConnect (I) |
Management API connection handle of server to get lock information. |
pucTableName (I) |
Table name that must include a fully qualified path to that table, i.e. it must contain a drive letter and path or must contain a UNC path which includes the server name and volume/share. |
pucUserName (I) |
Either a user name or NULL. The user name of an Advantage client is the client computer name or the client computer name then the client OS user login name separated by a backslash '\'. If pucUserName contains a user name, usConnNumber is ignored. |
usConnNumber (I) |
NetWare connection number. Only applicable if running against the Advantage Database Server for NetWare. If pucUserName contains a user name, usConnNumber is ignored. |
astRecordInfo (O) |
Returned array of record lock information structures. |
pusArrayLen (I/O) |
Number of array elements in astRecordInfo on input. On output, number of astRecordInfo array elements filled with record lock information by the Advantage Database Server. |
pusStructSize (I/O) |
Size (in bytes) of each astRecordInfo array element structure on input. On output, size of ADS_MGMT_RECORD_INFO structure on the Advantage Database Server. |
AdsMgGetLocks returns an array of structures containing information about records in the given table that the specified user has locked or that are locked by any user. If pucUserName contains an Advantage client’s user name or if usConnNumber is non-zero, then astRecordInfo will contain a list of information about records that are locked in the given table by the specified user. If pucUserName is NULL and usConnNumber is zero, then astRecordInfo will contain a list of information about all records that are locked in the given table by any user. If both pucUserName contains a user name and usConnNumber is non-zero, then usConnNumber will be ignored.
The number of elements in astRecordInfo, which is the value to be input in pusArrayLen, needs to be large enough to hold all possible records in the given table that are locked for the given user or for all users. If more records are locked than is specified in pusArrayLen, then only information about the first pusArrayLen number of locked records will be returned in astRecordInfo. Information about the remaining record locks will not be returned, and pusArrayLen will be returned with the same value that was input. If fewer records are locked than is specified in pusArrayLen, then not all elements in the astRecordInfo array will be filled. The value returned in pusArrayLen will indicate how many elements in the astRecordInfo array were filled. The remaining, unfilled elements at the end of the astRecordInfo array will be left unchanged.
It is possible that the size of the ADS_MGMT_RECORD_INFO structure will increase in future releases of Advantage. Since it is possible to use a newer version of the Advantage Database Server with an older version of the Advantage Client Engine, any new and additional record information that may exist if using a newer version of the Advantage Database Server will not be returned in each element of the astRecordInfo array. Each element in the array of astRecordInfo structures will only be filled with the amount of data specified in pusStructSize. The value returned in the pusStructSize parameter is the size of the ADS_MGMT_RECORD_INFO structure in the current version of the Advantage Database Server. If the size of each element in the astRecordInfo structure input in pusStructSize is the same as the size returned in pusStructSize, then the Advantage client has received all possible record information.
Since it is possible that the size of the ADS_MGMT_RECORD_INFO structure will increase in future releases of Advantage, it is highly recommended that on input the pusStructSize parameter is literally initialized with sizeof( ADS_MGMT_RECORD_INFO ) rather than being initialized with a literal value.
If the specified table name is locked, then only the first element in astRecordInfo will be filled. The record number in that lone astRecordInfo element will be 0. pusArrayLen will be returned with the value one.
Note AdsMgGetLocks will only return information about records locked on the Advantage Database Server. Information about any records locked by non-Advantage users will not be returned.
Note With the Advantage Local Server, AdsMgGetLocks will only return information about locks instantiated by the instance of Advantage Local Server currently loaded into memory. Information about locks instantiated from other instances of Advantage Local Server will not be returned.