dc_tam_read - Input a TAM table record

Format

ANSI C, C++

#include <dctam.h>
int  dc_tam_read (DCLONG tblid, struct DC_TAMKEY *keyadr,
                 int keyno, char *bufadr, int bufsize,
                 DCLONG flags)

K&R C

#include <dctam.h>
int       dc_tam_read (tblid, keyadr, keyno, bufadr, bufsize,
                  flags)
DCLONG    tblid;
struct DC_TAMKEY   *keyadr;
int       keyno;
char      *bufadr;
int       bufsize;
DCLONG    flags;

Description

According to the search type specified for flags, the function dc_tam_read() inputs a TAM table record for reference or update processing. The table below shows the relationship between search types and index types.

Table 2-2 Relationship between search types and index types

Search typeOutline of search processing
Index type: hash formatIndex type: tree format
'key-value='searchThe record having the specified key value is searched for.
If the record having the specified key value is not found, an error is returned.
The record having the specified key value is searched for.
If the record having the specified key value is not found, an error is returned.
'key-value<='searchAn error is returned.The record having a key value equal to or greater than the specified key value is searched for.
'key-value<'searchAn error is returned.The record having a key value greater than the specified key value is searched for.
'key-value>='searchAn error is returned.The record having a key value equal to or smaller than the specified key value or less is searched for.
'key-value>'searchAn error is returned.The record having a key value smaller than the specified key value is searched for.
First record search#The first record that was hashed in correspondence with the key value is searched for. The key value specified for keyadr is ignored.An error is returned.
NEXT search#The next record that was hashed in correspondence with the key value is searched for.An error is returned.
#: All the records in the TAM table can be searched for by using the first record search and NEXT search in the following conditions:

If lock is specified with input for reference processing, lock in tables and lock in records are enabled with lock for reference processing. If a TAM table open under lock in records is input for update processing, lock in tables is enabled with lock for reference processing, and lock in records is enabled with lock for update processing.

If the function dc_tam_read() returns with an error, all the resources specified in this function are released, and the status before this function was called is regained. However, if a record which was acquired under lock for reference processing before this function was called is input for update processing, lock for update processing is enabled. (Lock for reference processing is not regained.) If an error is returned, the buffer contents cannot be ensured.

Note the following when multiple records are specified for input:

Arguments whose values are set in the UAP

tblid

Specify the table descriptor of the TAM table to which a record is to be input. The table descriptor is the value returned with the function dc_tam_open().

keyadr

Specify the address of the structure having the key value address for searching for the record. The structure format is as follows:

struct DC_TAMKEY {
                char *keyname;
                };

keyno

Specify the number of request records (number of structures specified for keyadr).

bufadr

Specify the address of the buffer to which the record is to be input.

bufsize

Specify the length of the buffer to which the record is to be input. The return buffer length must be equal to or greater than (record length x number of request records).

flags

Specify the following items in the format shown below:

The table below shows the correspondence between flag values specified for flags and the specified type of lock.

Flag 1Flag 2Flag 3#1Flag 4#2Lock specified for flags

EQLSRC
GRTEQLSRC
GRTSRC
LSSEQLSRC
LSSSRC
FIRSTSRCN
EXTSRC

REFERENCE

EXCLUSIVE

WAIT

Input for reference, lock used, and waiting for release from lock if a lock error occurs

NOWAIT

Input for reference, lock used, and error return if a lock error occurs

NOEXCLUSIVE

N/AInput for reference, and lock not used

MODIFY

--

WAIT

Input for update, and waiting for release from lock if a lock error occurs

NOWAIT

Input for update, and error return if a lock error occurs
Legend:
N/A: Cannot be specified.
--: Specify always EXCLUSIVE. NOEXCLUSIVE cannot be specified.
#1: The default is NOEXCLUSIVE.
#2: The default is NOWAIT.

Return values

Return valueReturn value (numeric)Explanation
DC_OK0The TAM table record was input normally.
DCTAMER_PARAM_TID-1700The table descriptor specified for tblid is invalid.
DCTAMER_PARAM_KEY-1702The key value specified for keyadr is invalid.
DCTAMER_PARAM_KNO-1703The value specified for keyno is invalid.
DCTAMER_PARAM_BFA-1704The value specified for bufadr is invalid.
DCTAMER_PARAM_BFS-1705The buffer length specified for bufsize is too short.
DCTAMER_PARAM_FLG-1708The value specified for flags is invalid.
DCTAMER_NOTTAM-1709The table specified for tblid is not a TAM table.
DCTAMER_TAMEND-1720The TAM service is being terminated.
DCTAMER_PROTO-1721The sequence of accessing the TAM table is invalid.
The resource manager registration of the object file for transaction control having a linkage with the UAP is invalid.
Alternatively, there is no linkage between the object file for transaction control and the UAP.
atomic_update=N (nontransaction attribute) is specified in the user service definition of the UAP which called the function.
DCTAMER_RMTBL-1723The TAM table was deleted.
DCTAMER_NOLOAD-1724The TAM table was not loaded.
DCTAMER_NOOPEN-1726The TAM table is not open.
DCTAMER_LOGHLD-1727The TAM table is in logical shutdown state.
DCTAMER_OBSHLD-1728The TAM table is in shutdown state due to an error.
DCTAMER_IDXTYP-1729Execution is impossible with the index type of the TAM table specified for creation of a TAM table file.
DCTAMER_ACSATL-1730Execution is impossible in the access mode of the TAM table specified in the TAM service definition.
DCTAMER_NOREC-1731A record satisfying the search conditions specified for flags is not found.
DCTAMER_LOCK-1736A lock error occurred. If DCTAM_WAIT is specified for flags, the resource could not be acquired because a timeout occurred (the wait time specified in the lock service definition was exceeded).
DCTAMER_DLOCK-1737A deadlock occurred.
DCTAMER_TBLVR-1760The version of the TAM library linked to the UAP does not allow the UAP to operate with the current TAM table.
DCTAMER_FLSVR-1761The version of the TAM library linked to the UAP does not allow the UAP to operate with the current OpenTP1 file service.
DCTAMER_RECOBS-1764The record has been damaged.
DCTAMER_TRNNUM-1765The number of transactions exceeds the maximum number of transactions which can be managed by the TAM service.
DCTAMER_OPENNUM-1766The number of open character special files exceeds the specified limit.
DCTAMER_ACCESSS-1767The access permission for special files has not been granted.
DCTAMER_ACCESSF-1768The access permission for TAM files has not been granted.
DCTAMER_MEMORY-1769The memory became insufficient.
DCTAMER_IO-1770An input/output error occurred.
DCTAMER_TMERR-1771A transaction service error occurred.
DCTAMER_ACCESS-1773A TAM file to be accessed is protected with the security facility. The UAP that called the function dc_tam_read() has no access permission.