Retrieving data from a client

A writetext stream triggers a SRV_BULK event. Because text and image data retrieved from a client are considered bulk data, an Open Server application processes incoming text and image data from inside its bulk handler. See the Open Client and Open Server Common Libraries Reference Manual.

An application processes incoming text or image data in two steps:

1. The srv_text_info routine retrieves a description of the text or image data and places the information in a CS_IODESC structure. This call returns a variety of information, the most important of which is the total length of the data. Based on the length, the application can decide whether to retrieve the data all at once or in sections, as well as how large a buffer to allocate to store the data. srv_text_info is called with the cmd argument set to CS_GET.

2. The srv_get_text routine actually brings the data over from the client in the specified section size and stores it in the specified buffer.

Note that a call to srv_text_info must always precede a call to srv_get_text. The srv_get_text routine must be called until all text has been read from the client.

To simplify the process of updating a text or image column and potentially improve performance, a client can suppress the generation of the SQL command (update or writetext) and send data directly to the server bulk handler. To do this, the client must initiate the send-data command by calling the ct_command routine with the type parameter set to CS_SEND_DATA_NOCMD. The client application can then use send-data commands to send only text or image data to the server bulk handler. When a bulk event occurs at the server, a 4-byte field is sent indicating the total number of bytes to be sent, followed by the text or image data. The bulk handler reads the total number of bytes expected using srv_text_info and the data using srv_get_data.

The server must define a stored procedure, sp_mda, to indicate whether or not it supports the ct_send_data routine sending only text or image data without a SQL command. The server sp_mda procedure is called only if the client application sets the CS_SENDDATA_NOCMD connection property—for example, ct_con_props(CS_SENDDATA_NOCMD)—before the ct_connect routine is called. If CS_SENDDATA_NOCMD is set, the server sp_mda procedure is called during execution of ct_connect. If sp_mda indicates that the server does not support the ct_send_data routine sending only text or image data without a SQL command, any calls to the ct_command routine with the type parameter set to CS_SEND_DATA_NOCMD fail.

If the server can receive text or image data without a SQL command, sp_mda returns the following: