Smart large object read functions
You use smart large object read functions to transfer captured data to a buffer where your application can access it.
You can use any of the smart large object read functions that are listed in the following table, depending on your application language. You must use the same smart large object read function for all read calls during a particular session. Using different functions in the same session can result in incomplete delivery of captured data.
| Read function | Arguments | Informix® API | Application language |
|---|---|---|---|
| mi_lo_read() | A pointer to a connection descriptor A smart large object file descriptor A data buffer The maximum number of bytes to read |
DataBlade® API | Use in a C language application. |
| ifx_lo_read() | A smart large object file descriptor A data buffer |
ODBC | Use in an ODBC application. |
| ifx_lo_read() | A smart large object file descriptor A data buffer The maximum number of bytes to read A pointer to an error code |
ESQL/C | Use in a C language application. |
| IfxLoRead() | A smart large object file descriptor A data buffer The maximum number of bytes to read |
JDBC | Use in a Java™ application. |
| IfxBlob.Read() | A data buffer | .NET | Use in a .NET application. |
Read timeout
If no captured data is available to retrieve, the read call waits for data for the timeout period that is specified by the cdc_opensess() function. If the timeout period is exceeded, a CDC_REC_TIMEOUT record is returned to the read call. The read call passes the CDC_REC_TIMEOUT record into the data buffer and returns successfully.
Read buffer size
The size of the buffer that is specified in the read call must be at least 128 bytes. The maximum size of a read buffer is 2 GB. You can calculate the approximate minimum size of the buffer for your application by calculating the largest possible CDC record size, for example, a CDC_REC_INSERT record, and multiplying that value times the maximum number of records to return per read call that you specify in the cdc_opensess() function.
Amount and structure of data returned
The amount of data that is returned by a read call is limited by the size of the buffer that is specified in the read call and the maximum number of records to return. No more than the maximum number of records is returned by one read call, even if the number of bytes contained in those records is less than the maximum number of bytes allowed by the read call. However, no more than the maximum number of bytes allowed by the read call is returned, even if the number of records returned is less than the maximum number allowed.
The amount of data that is returned by smart large object read functions can differ from the size of the read buffer. The data that is returned is structured into CDC records. The number of CDC records that are returned by a smart large object read function varies and might not be an integral number. If a read call returns only part of a CDC record, the next read call returns more data for that record. The application must merge the parts of the record together. The Change Data Capture sample program provides examples of merging parts of records.
Smart large object file descriptor
The value for the smart large object file descriptor argument in the read functions is the CDC session ID returned by the cdc_opensess() function.
Smart large object read function for the Informix® .NET Provider
conn = new IfxConnection(..)// to SYSCDC database
execute function informix.cdc_opensess() // on the same connection
IfxBlob( IfxConnection connection )// construct it using the same connection
IfxBlob.Open(ReadOnly) // open it
IfxBlob.Read(long plofd, byte[] buff)