3.3 Operations and Signals

In this section we discuss the sequence of message-passing that takes place between a data node and an API node for each of the following operations:

• Primary key lookup

• Unique key lookup

• Table scan or index scan

• Explicit commit of a transaction

• Rollback of a transaction

• Transaction record handling (acquisition and release)

Primary key lookup.  An operation using a primary key lookup is performed as shown in the following diagram:

Figure 3.1 Messages Exchanged In A Primary Key Lookup

Note

* and + are used here with the meanings “zero or more” and “one or more”, respectively.

The steps making up this process are listed and explained in greater detail here:

1. The API node sends a TCKEYREQ message to the data node. In the event that the necessary information about the key to be used is too large to be contained in the TCKEYREQ, the message may be accompanied by any number of KEYINFO messages carrying the remaining key information. If additional attributes are used for the operation and exceed the space available in the TCKEYREQ, or if data is to be sent to the data node as part of a write operation, then these are sent with the TCKEYREQ as any number of ATTRINFO messages.

2. The data node sends a message in response to the request, according to whether the operation succeeded or failed:

   • If the operation was successful, the data node sends a TCKEYCONF message to the API node. If the request was for a read operation, then TCKEYCONF is accompanied by a TRANSID_AI message, which contains actual result data. If there is more data than can be contained in a single TRANSID_AI can carry, more than one of these messages may be sent.

   • If the operation failed, then the data node sends a TCKEYREF message back to the API node, and no more signalling takes place until the API node makes a new request.

Unique key lookup.  This is performed in a manner similar to that performed in a primary key lookup:

1. A request is made by the API node using a TCINDXREQ message which may be accompanied by zero or more KEYINFO messages, zero or more ATTRINFO messages, or both.

2. The data node returns a response, depending on whether or not the operation succeeded:

   • If the operation was a success, the message is TCINDXCONF. For a successful read operation, this message may be accompanied by one or more TRANSID_AI messages carrying the result data.

   • If the operation failed, the data node returns a TCINDXREF message.

The exchange of messages involved in a unique key lookup is illustrated in the following diagram:

Figure 3.2 Messages Exchanged In A Unique Key Lookup

Table scans and index scans.  These are similar in many respects to primary key and unique key lookups, as shown here:

Figure 3.3 Messages Exchanged For A Table Scan Or Index Scan Operation.

1. A request is made by the API node using a SCAN_TABREQ message, along with zero or more ATTRINFO messages. KEYINFO messages are also used with index scans in the event that bounds are used.

2. The data node returns a response, according to whether or not the operation succeeded:

   • If the operation was a success, the message is SCAN_TABCONF. For a successful read operation, this message may be accompanied by one or more TRANSID_AI messages carrying the result data. However—unlike the case with lookups based on a primary or unique key—it is often necessary to fetch multiple results from the data node. Requests following the first are signalled by the API node using a SCAN_NEXTREQ, which tells the data node to send the next set of results (if there are more results). This is shown here:

     Figure 3.4 Fetching Multiple Result Data Sets Following A Table Or Index Scan Read Operation

     
     
     

   • If the operation failed, the data node returns a SCAN_TABREF message.

     SCAN_TABREF is also used to signal to the API node that all data resulting from a read has been sent.

Committing and rolling back transactions.  The process of performing an explicit commit follows the same general pattern as shown previously. The API node sends a TC_COMMITREQ message to the data node, which responds with either a TC_COMMITCONF (on success) or a TC_COMMITREF (if the commit failed). This is shown in the following diagram:

Figure 3.5 Messages Exchanged In Explicit Commit Operation

Note

Some operations perform a COMMIT automatically, so this is not required for every transaction.

Rolling back a transaction also follows this pattern. In this case, however, the API node sends a TCROLLBACKTREQ message to the data node. Either a TCROLLACKCONF or a TCROLLBACKREF is sent in response, as shown here:

Figure 3.6 Messages Exchanged When Rolling Back A Transaction

Handling of transaction records.  Acquiring a transaction record is accomplished when an API node transmits a TCSEIZEREQ message to a data node and receives a TCSEIZECONF or TCSEIZEREF in return, depending on whether or not the request was successful. This is depicted here:

The release of a transaction record is also handled using the request-response pattern. In this case, the API node's request contains a TCRELEASEREQ message, and the data node's response uses either a TCRELEASECONF (indicating that the record was released) or a TCRELEASEREF (indicating that the attempt at release did not succeed). This series of events is illustrated in the next diagram: