Commands

## Commands Commands — Issuing commands to the provider |

## Synopsis

    enum        GdaCommandOptions;
    enum        GdaCommandType;
                GdaCommand;
    GdaCommand* gda_command_new                 (const gchar *text,
                                                 GdaCommandType type,
                                                 GdaCommandOptions options);
    void        gda_command_free                (GdaCommand *cmd);
    GdaCommand* gda_command_copy                (GdaCommand *cmd);
    const gchar* gda_command_get_text           (GdaCommand *cmd);
    void        gda_command_set_text            (GdaCommand *cmd,
                                                 const gchar *text);
    GdaCommandType gda_command_get_command_type (GdaCommand *cmd);
    void        gda_command_set_command_type    (GdaCommand *cmd,
                                                 GdaCommandType type);
    GdaCommandOptions gda_command_get_options   (GdaCommand *cmd);
    void        gda_command_set_options         (GdaCommand *cmd,
                                                 GdaCommandOptions options);
    GdaTransaction* gda_command_get_transaction (GdaCommand *cmd);
    void        gda_command_set_transaction     (GdaCommand *cmd,
                                                 GdaTransaction *xaction);

## Description

The GdaCommand structure holds data needed to issue a command to the providers. Applications usually create a GdaCommand (via gda_command_new), set its properties (via the gda_command_set_* functions) and pass it over to the database using the GdaConnection functions.

One interesting thing about GdaCommand's is that they can be reused over and over. That is, applications don't need to create a command every time they want to run something on the connected database. Moreover, the ability to create command strings with placeholders allows the use of parameters to specify the values for those placeholders. Thus, an application can create a command of the form:

        INSERT INTO employees VALUES (id, name, address, salary)

and reuse the same command over and over, just using different values for the placeholders.

The value for the placeholders is specified when sending the GdaCommand to a database connection, which is done via the gda_connection_execute function.

## Details

### enum GdaCommandOptions

    typedef enum {
    	GDA_COMMAND_OPTION_IGNORE_ERRORS  = 1,
    	GDA_COMMAND_OPTION_STOP_ON_ERRORS = 1 << 1,
    	GDA_COMMAND_OPTION_BAD_OPTION     = 1 << 2
    } GdaCommandOptions;

And OR'ed combination of GDA_COMMAND_OPTIONS_* values.

### enum GdaCommandType

    typedef enum {
    	GDA_COMMAND_TYPE_SQL,
    	GDA_COMMAND_TYPE_XML,
    	GDA_COMMAND_TYPE_PROCEDURE,
    	GDA_COMMAND_TYPE_TABLE,
    	GDA_COMMAND_TYPE_SCHEMA,
    	GDA_COMMAND_TYPE_INVALID
    } GdaCommandType;

`GDA_COMMAND_TYPE_SQL` | the text of the command is composed of zero or more SQL sentences.
`GDA_COMMAND_TYPE_XML` |
`GDA_COMMAND_TYPE_PROCEDURE` |
`GDA_COMMAND_TYPE_TABLE` | the text of the command is composed of zero or more table names.
`GDA_COMMAND_TYPE_SCHEMA` |
`GDA_COMMAND_TYPE_INVALID` |

### GdaCommand

    typedef struct {
    	gchar *text;
    	GdaCommandType type;
    	GdaCommandOptions options;
    	GdaTransaction *xaction;
    } GdaCommand;

### gda_command_new ()

    GdaCommand* gda_command_new                 (const gchar *text,
                                                 GdaCommandType type,
                                                 GdaCommandOptions options);

Creates a new GdaCommand from the parameters that should be freed by calling gda_command_free.

If there are conflicting options, this will set `options` to GDA_COMMAND_OPTION_DEFAULT.

`text` : | the text of the command.
`type` : | a GdaCommandType value.
`options` : | a GdaCommandOptions value.
Returns : | a newly allocated GdaCommand.

### gda_command_free ()

    void        gda_command_free                (GdaCommand *cmd);

Frees the resources allocated by gda_command_new.

`cmd` : | a GdaCommand.

### gda_command_copy ()

    GdaCommand* gda_command_copy                (GdaCommand *cmd);

Creates a new GdaCommand from an existing one.

`cmd` : | command to get a copy from.
Returns : | a newly allocated GdaCommand with a copy of the data in `cmd`.

### gda_command_get_text ()

    const gchar* gda_command_get_text           (GdaCommand *cmd);

Gets the command text held by `cmd`.

`cmd` : | a GdaCommand.
Returns : | the command string of `cmd`.

### gda_command_set_text ()

    void        gda_command_set_text            (GdaCommand *cmd,
                                                 const gchar *text);

Sets the command text of `cmd`.

`cmd` : | a GdaCommand
`text` : | the command text.

### gda_command_get_command_type ()

    GdaCommandType gda_command_get_command_type (GdaCommand *cmd);

Gets the command type of `cmd`.

`cmd` : | a GdaCommand.
Returns : | the command type of `cmd`.

### gda_command_set_command_type ()

    void        gda_command_set_command_type    (GdaCommand *cmd,
                                                 GdaCommandType type);

Sets the command type of `cmd`.

`cmd` : | a GdaCommand
`type` : | the command type.

### gda_command_get_options ()

    GdaCommandOptions gda_command_get_options   (GdaCommand *cmd);

Gets the command options of `cmd`.

`cmd` : | a GdaCommand.
Returns : | the command options of `cmd`.

### gda_command_set_options ()

    void        gda_command_set_options         (GdaCommand *cmd,
                                                 GdaCommandOptions options);

Sets the command options of `cmd`. If there conflicting options, it will just leave the value as before.

`cmd` : | a GdaCommand
`options` : | the command options.

### gda_command_get_transaction ()

    GdaTransaction* gda_command_get_transaction (GdaCommand *cmd);

Gets the GdaTransaction associated with the given GdaCommand.

`cmd` : | a GdaCommand.
Returns : | the transaction for the command.

### gda_command_set_transaction ()

    void        gda_command_set_transaction     (GdaCommand *cmd,
                                                 GdaTransaction *xaction);

Sets the GdaTransaction associated with the given GdaCommand.

`cmd` : | a GdaCommand.
`xaction` : | a GdaTransaction object.