ct_command

Description

Initiate a language, package, RPC, message, or send-data command.

Syntax

CS_RETCODE ct_command(cmd, type, buffer, buflen,
                option)
 
 CS_COMMAND     *cmd;
 CS_INT                  type;
 CS_VOID               *buffer;
 CS_INT                  buflen;
 CS_INT                  option;

Parameters

cmd

A pointer to the CS_COMMAND structure managing a client/server operation.

type

The type of command to initiate. Table 3-9 lists the symbolic values for type.

buffer

A pointer to data space. Table 3-9 lists the datatypes and meanings for *buffer values.

buflen

The length, in bytes, of the *buffer data, or CS_UNUSED if *buffer represents a fixed-length or symbolic value.

option

The option associated with this command.

Language, RPC (remote procedure call), send-data, and send-bulk-data commands take options. For all other types of commands, pass option as CS_UNUSED.

The following table lists the symbolic values for option:

Table 3-8: Values for ct_command option parameter

type is

Value of option

Meaning

CS_LANG_CMD

CS_MORE

The text in buffer is only part of the language command to be executed.

CS_END

The text in buffer is the last part of the language command to be executed.

CS_UNUSED

Equivalent to CS_END.

CS_RPC_CMD

CS_RECOMPILE

Recompile the stored procedure before executing it.

CS_NO_RECOMPILE

Do not recompile the stored procedure before executing it.

CS_UNUSED

Equivalent to CS_NO_RECOMPILE.

CS_SEND_DATA_CMD

CS_COLUMN_DATA

The data will be used for a text or image column update.

CS_BULK_DATA

For internal Sybase use only. The data will be used for a bulk copy operation.

CS_SEND_BULK_CMD

CS_BULK_INIT

For internal Sybase use only. Initialize a bulk copy operation.

CS_BULK_CONT

For internal Sybase use only. Continue a bulk copy operation.

Returns

ct_command returns the following values:

Returns

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

CS_BUSY

An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Examples

Example 1

/*
 ** ex_execute_cmd()
 **
 ** Type of function:   
 **      example program utility api
 **
 ** Purpose:
 ** Sends a language command to the server. 
 */
 CS_RETCODE CS_PUBLIC
 ex_execute_cmd(connection, cmdbuf)
 CS_CONNECTION   *connection;
 CS_CHAR         *cmdbuf;
 {
 CS_RETCODE      retcode;
 CS_INT          restype;
 CS_COMMAND      *cmd;
 CS_RETCODE      query_code;
   /*
    ** Get a command structure,store the command string in it, 
    ** and send it to the server.
    */
    if ((retcode = ct_cmd_alloc(connection, &cmd)) !=
         CS_SUCCEED)
    {
        ex_error("ex_execute_cmd: ct_cmd_alloc() failed");
        return retcode;
    }

   if ((retcode = ct_command(cmd, CS_LANG_CMD, cmdbuf,
         CS_NULLTERM, CS_UNUSED)) != CS_SUCCEED)
    {
        ex_error("ex_execute_cmd: ct_command() failed");
        (void)ct_cmd_drop(cmd);
        return retcode;
    }
   /* Now send the command and process the results */
    ... ct_send, ct_results, and so forth deleted ...
   return CS_SUCCEED;
 }

This code excerpt is from the exutils.c example program.

Usage

Table 3-9 summarizes ct_command usage.

Table 3-9: Summary of ct_command parameters

Value of type

Command initiated

buffer is

buflen is

CS_LANG_CMD

A language command

A pointer to a CS_CHAR array that contains all or part of the language command text.

Use the CS_MORE and CS_END options to build the command text in pieces. See Table 3-8 for details.

The length of the *buffer data or CS_NULLTERM.

CS_MSG_CMD

A message command

A pointer to a CS_INT variable that contains the message ID.

CS_UNUSED

CS_PACKAGE_CMD

A package command

A pointer to a CS_CHAR array that contains the name of the package.

The length of the *buffer data or CS_NULLTERM.

CS_RPC_CMD

A remote procedure call command

A pointer to a CS_CHAR array that contains the name of the remote procedure.

The length of the *buffer data or CS_NULLTERM.

CS_SEND_DATA_CMD

A send-data command

NULL.

CS_UNUSED.

CS_SEND_BULK_CMD

A Sybase internal send-bulk-data command

A pointer to a CS_CHAR array that contains the database table name.

The length of the *buffer data or CS_NULLTERM.


Language commands


Message commands


Package commands


RPC commands


Send-data commands


Send-bulk-data commands

See also

ct_cmd_alloc, ct_cursor, ct_dynamic, ct_param, ct_send, ct_setparam