Receive a TDS (Tabular Data Stream) packet from a server.
CS_RETCODE ct_recvpassthru (cmd, recvptr) CS_COMMAND *cmd; CS_VOID **recvptr;
A pointer to a CS_COMMAND structure.
The address of a pointer variable. ct_recvpassthru sets the variable to the address of a buffer containing the most recently received TDS packet. The application is not responsible for allocating this buffer.
ct_recvpassthru returns the following values:
Return value |
Meaning |
|---|---|
CS_PASSTHRU_MORE |
Packet received successfully; more packets are available. |
CS_PASSTHRU_EOM |
Packet received successfully; no more packets are available. |
CS_FAIL |
The routine failed. |
CS_CANCELED |
The passthrough operation was canceled. |
CS_PENDING |
Asynchronous network I/O is in effect. See “Asynchronous programming”. |
CS_BUSY |
An asynchronous operation is already pending for this connection. See “Asynchronous programming”. |
TDS is a communications protocol used for the transfer of requests and request results between clients and servers. Under ordinary circumstances, non-gateway applications do not usually have to deal with TDS, because Client-Library manages the data stream.
ct_recvpassthru and ct_sendpassthru are useful in gateway applications. When an application serves as the intermediary between two parties (such as a client and a remote server, or two servers), it can use these routines to pass the TDS stream from one server to the other, eliminating the process of interpreting the information and re-encoding it.
ct_recvpassthru reads a packet of bytes from a server connection and sets *recvptr to point to the buffer containing the bytes.
Default packet sizes vary by platform. On most platforms, a packet has a default size of 512 bytes. A connection can change its packet size through ct_con_props.
ct_recvpassthru returns CS_PASSTHRU_EOM if the TDS packet has been marked by the server as EOM (End Of Message). If the TDS packet is not marked EOM, ct_recvpassthru returns CS_PASSTHRU_MORE.
A connection which is being used for a passthrough operation cannot be used for any other Client-Library function until CS_PASSTHRU_EOM has been received.
