Support for batched parameters

Starting with ESD #4, Open Client and Open Server allow multiple sets of command parameters to be sent without ending the command itself. In an Open Client application, use the new ct_send_params() routine repeatedly to transfer parameters without needing to process the results of the previous command and without needing to resend the command itself. In an Open Server application, set SRV_S_PARAM_BATCHING property to CS_TRUE.

Send command parameters in batches.

CS_RETCODE ct_send_params(
  CS_COMMAND *cmd, 
  CS_INT reserved)

• cmd

  A pointer to a CS_COMMAND structure.

• reserved

  Set to CS_UNUSED. This is a placeholder reserved for possible future use.

ct_send_params returns:

A call to this function sends the parameters indicated earlier using ct_param() or ct_setparam(). To stop sending parameters, use a ct_send() call after the last ct_send_params() call. This signals the end of the parameters and completes the current command.

• The first ct_send_params() call sends the actual command, the parameter formats for all parameters, and the first set of parameters to the server. Subsequent calls only send more parameters without format.

• The network buffer containing the parameters gets flushed during every call to ct_send_params() so that the server can start processing the command.

• Unlike ct_send(), ct_send_params() does not end the current command. You can call ct_send_params() repeatedly to send multiple sets of parameters.

• The handling of the results starts only after a ct_send() call to complete the command. If ct_results() is called before ct_send(), an error results.

When sending multiple sets of parameters, an application may need to point CT-Library to other locations in memory than for the previous set of parameters. To rebind the parameters, use ct_setparam() to provide a different location for the data. Here is the existing ct_setparam() declaration:

ct_setparam(cmd, datafmt, data, datalenp, indp)

  CS_COMMAND *cmd; 
  CS_DATAFMT *datafmt; 
  CS_VOID *data;
  CS_INT *datalenp; 
  CS_SMALLINT *indp;

Provide new values for data, datalenp and indp parameters in ct_setparam() call to bind to different memory locations.

After a ct_send_params() call, the format of the parameters cannot be changed. Any calls to ct_setparam() made after a call to ct_send_params() must therefore pass a NULL value for datafmt.

Only parameters initially bound with ct_setparam() can be rebound.

To enable batched parameter support in Open Server Server-Library, set the SRV_S_PARAM_BATCHING server property to CS_TRUE. For example, before srv_run():

if (srv_props(ctos_ctx->cx_context, CS_SET,
SRV_S_PARAM_BATCHING, (CS_VOID *)&cs_true, sizeof(cs_true), NULL) != CS_SUCCEED)
{...}

Then, srv_xferdata() has two new return codes when a command contains multiple sets of command parameters.

• CS_PARAMS_MORE - indicates parameters have been successfully copied and there are more parameters in the batch.

• CS_PARAMS_END - indicates parameters have been successfully copied. This is the last set of parameters in the batch.

Two new CT-Library sample programs are available:

• batch_lang.c - demonstrates how ct_send_params() can be used with a language statement. This sample uses ct_send_params() repeatedly to insert lines read from a file into a table. Since it uses the same location for the parameters for every line read, it does not need to call ct_param() or ct_setparam() in between calls to ct_send_params().

• batch_dynamic.c - uses dynamic SQL and sends parameters to the server for which the data resides at different memory locations. Therefore, this sample also demonstrates how ct_setparam() can be used to rebind to different variables before calling ct_send_params() again.

The ctos sample program has been updated to include:

• Turn on the SRV_S_PARAM_BATCHING server property.

• Use ct_setparams() to bind CT-Lib to the location of the data.

• Handle the new return values from srv_xferdata()

• Call ct_send_params() for each set of command parameters.