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;

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

#: All the records in the TAM table can be searched for by using the first record search and NEXT search in the following conditions:

• The hash format is specified as the index type.
• When a TAM table file is created, a key value is assigned to the data part (the -s option not specified in the tamcre command).

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:

• Even if one of the records causes an error, the processing of all the records specified in the function dc_tam_read() results in an error.

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;
                 };

• keyname
  Specify the address of the key value. The key value must be specified with the length of the key area of the record to be input.
  

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:

• Record search type
• Record access type
• Whether to enable lock for reference processing when the lock is specified (lock enabled/disabled type)
• Lock release wait type if competition for a resource occurs
  

  {Flag 1} |{DCTAM_REFERENCE[|{DCTAM_EXCLUSIVE|DCTAM_NOEXCLUSIVE}] |DCTAM_MODIFY}[|{DCTAM_WAIT|DCTAM_NOWAIT}]

• Flag 1
  

  The specification of record search type cannot be omitted. More than one record search type cannot be specified at a time.

  DCTAM_EQLSRC: 'key-value=' is searched for. (Hash and tree formats)

  DCTAM_GRTEQLSRC: 'key-value<=' is searched for. (Tree format)

  DCTAM_GRTSRC: 'key-value<' is searched for. (Tree format)

  DCTAM_LSSEQLSRC: 'key-value>=' is searched for. (Tree format)

  DCTAM_LSSSRC: 'key-value>' is searched for. (Tree format)

  DCTAM_FIRSTSRC: Search processing starts from the first record. (Hash format)

  DCTAM_NEXTSRC: Search processing starts from the record following the specified key value. (Hash format)

• Flag 2
  The specification of record access type cannot also be omitted. More than one access type cannot also be specified at a time.
  DCTAM_REFERENCE: Lock for reference processing
  DCTAM_MODIFY: Lock for update processing
  
• Flag 3
  If lock for reference processing is specified, also specify whether to enable the lock. More than one lock enabled/disabled type cannot be specified at a time. The default is DCTAM_NOEXCLUSIVE.
  DCTAM_EXCLUSIVE: Lock is enabled.
  DCTAM_NOEXCLUSIVE: Lock is disabled.
  
• Flag 4
  More than one lock release wait type cannot also be specified. The default is DCTAM_NOWAIT.
  DCTAM_WAIT: The function waits for the resource to be released from lock.
  DCTAM_NOWAIT: The function does not wait for the resource to be released from lock, and returns with an error.
  

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

EQLSRC
GRTEQLSRC
GRTSRC
LSSEQLSRC
LSSSRC
FIRSTSRCN
EXTSRC

REFERENCE

EXCLUSIVE

WAIT

NOWAIT

NOEXCLUSIVE

MODIFY

WAIT

NOWAIT

Legend:

N/A: Cannot be specified.

--: Specify always EXCLUSIVE. NOEXCLUSIVE cannot be specified.

#1: The default is NOEXCLUSIVE.

#2: The default is NOWAIT.