## GdaServerOperation

GdaServerOperation — Handles any DDL query in an abstract way

## Synopsis

                        GdaServerOperation;
    enum                GdaServerOperationType;
    GdaServerOperationType  gda_server_operation_get_op_type
                                                            (GdaServerOperation *op);
    const gchar *       gda_server_operation_op_type_to_string
                                                            (GdaServerOperationType type);
    GdaServerOperationType  gda_server_operation_string_to_op_type
                                                            (const gchar *str);

    const GValue *      gda_server_operation_get_value_at   (GdaServerOperation *op,
                                                             const gchar *path_format,
                                                             ...);
    gchar *             gda_server_operation_get_sql_identifier_at
                                                            (GdaServerOperation *op,
                                                             GdaConnection *cnc,
                                                             GdaServerProvider *prov,
                                                             const gchar *path_format,
                                                             ...);
    gboolean            gda_server_operation_set_value_at   (GdaServerOperation *op,
                                                             const gchar *value,
                                                             GError **error,
                                                             const gchar *path_format,
                                                             ...);
    xmlNodePtr          gda_server_operation_save_data_to_xml
                                                            (GdaServerOperation *op,
                                                             GError **error);
    gboolean            gda_server_operation_load_data_from_xml
                                                            (GdaServerOperation *op,
                                                             xmlNodePtr node,
                                                             GError **error);
    gboolean            gda_server_operation_is_valid       (GdaServerOperation *op,
                                                             const gchar *xml_file,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GdaServerOperation

## Properties

      "connection"               GdaConnection*        : Read / Write / Construct Only
      "op-type"                  gint                  : Read / Write / Construct Only
      "provider"                 GdaServerProvider*    : Read / Write / Construct Only
      "spec-filename"            gchar*                : Write / Construct Only

## Signals

      "sequence-item-added"                            : Run First
      "sequence-item-remove"                           : Run First

## Description

This object is basically just a data store: it can store named values, the values being organized hierarchically by their name which are similar to a Unix file path. For example a value can be read from its path using the `gda_server_operation_get_value_at()` method, or set using the `gda_server_operation_set_value_at()` method.

Each GdaServerOperation contains some structure which is usually defined by a database provider to implement a specific operation. The structure is composed of the following building blocks:

- Named values (internally represented as a GdaHolder object)

- Named values in a vector (internally represented as a GdaSet object)

- Values in an array (internally represented as a GdaDataModel object)

- Sequences of one or more of the previous blocks. A sequence can contain any number of instances of the template block (there may be lower and upper boundaries to the number of instances)

Important note: GdaServerOperation objects are usually not created manually using `gda_server_operation_new()`, but using a GdaServerProvider object with `gda_server_provider_create_operation()`. See the global introduction about DDL for more information. Alternatively one can use the Convenience functions which internally manipulate GdaServerOperation objects.

## Details

### GdaServerOperation

    typedef struct _GdaServerOperation GdaServerOperation;

### enum GdaServerOperationType

    typedef enum {
    	GDA_SERVER_OPERATION_CREATE_DB,
    	GDA_SERVER_OPERATION_DROP_DB,

    	GDA_SERVER_OPERATION_CREATE_TABLE,
    	GDA_SERVER_OPERATION_DROP_TABLE,
    	GDA_SERVER_OPERATION_RENAME_TABLE,

    	GDA_SERVER_OPERATION_ADD_COLUMN,
    	GDA_SERVER_OPERATION_DROP_COLUMN,

    	GDA_SERVER_OPERATION_CREATE_INDEX,
    	GDA_SERVER_OPERATION_DROP_INDEX,

    	GDA_SERVER_OPERATION_CREATE_VIEW,
    	GDA_SERVER_OPERATION_DROP_VIEW,

    	GDA_SERVER_OPERATION_COMMENT_TABLE,
    	GDA_SERVER_OPERATION_COMMENT_COLUMN,

    	GDA_SERVER_OPERATION_CREATE_USER,
    	GDA_SERVER_OPERATION_ALTER_USER,
    	GDA_SERVER_OPERATION_DROP_USER,

    	GDA_SERVER_OPERATION_LAST
    } GdaServerOperationType;

### gda_server_operation_get_op_type ()

    GdaServerOperationType  gda_server_operation_get_op_type
                                                            (GdaServerOperation *op);

Get the type of operation `op` is for

`op` : | a GdaServerOperation object
Returns : | a GdaServerOperationType enum

### gda_server_operation_op_type_to_string ()

    const gchar *       gda_server_operation_op_type_to_string
                                                            (GdaServerOperationType type);

Get a string version of `type`

`type` : | a GdaServerOperationType value
Returns : | a non `NULL` string (do not free or modify). [transfer none]

### gda_server_operation_string_to_op_type ()

    GdaServerOperationType  gda_server_operation_string_to_op_type
                                                            (const gchar *str);

Performs the reverse of `gda_server_operation_op_type_to_string()`

`str` : | a string
Returns : | the GdaServerOperationType represented by `str`, or G_MAXINT if `str` is not a valid representation of a GdaServerOperationType

Since 4.2

### gda_server_operation_get_value_at ()

    const GValue *      gda_server_operation_get_value_at   (GdaServerOperation *op,
                                                             const gchar *path_format,
                                                             ...);

Get the value for the node at the path formed using `path_format` and ... (the rules are the same as for `g_strdup_printf()`)

`op` : | a GdaServerOperation object
`path_format` : | a complete path to a node (starting with "/")
`...` : | arguments to use with `path_format` to make a complete path
Returns : | a constant GValue if a value has been defined, or `NULL` if the value is undefined or if the `path` is not defined or `path` does not hold any value. [transfer none]

### gda_server_operation_get_sql_identifier_at ()

    gchar *             gda_server_operation_get_sql_identifier_at
                                                            (GdaServerOperation *op,
                                                             GdaConnection *cnc,
                                                             GdaServerProvider *prov,
                                                             const gchar *path_format,
                                                             ...);

This method is similar to `gda_server_operation_get_value_at()`, but for SQL identifiers: a new string is returned instead of a GValue. Also the returned string is assumed to represents an SQL identifier and will correctly be quoted to be used with `cnc`, or `prov` if `cnc` is `NULL` (a generic quoting rule will be applied if both are `NULL`).

`op` : | a GdaServerOperation object
`cnc` : | a GdaConnection, or `NULL`
`prov` : | a GdaServerProvider, or `NULL`
`path_format` : | a complete path to a node (starting with "/")
`...` : | arguments to use with `path_format` to make a complete path
Returns : | a new string, or `NULL` if the value is undefined or if the `path` is not defined or `path` does not hold any value, or if the value held is not a string (in that last case a warning is shown). [transfer full]

Since 4.0.3

### gda_server_operation_set_value_at ()

    gboolean            gda_server_operation_set_value_at   (GdaServerOperation *op,
                                                             const gchar *value,
                                                             GError **error,
                                                             const gchar *path_format,
                                                             ...);

Set the value for the node at the path formed using `path_format` and the ... ellipse (the rules are the same as for `g_strdup_printf()`).

Note that trying to set a value for a path which is not used by the current provider, such as "/TABLE_OPTIONS_P/TABLE_ENGINE" for a PostgreSQL connection (this option is only supported for MySQL), will not generate any error; this allows one to give values to a superset of the parameters and thus use the same code for several providers.

Here are the possible formats of `path_format`:

- If the path corresponds to a GdaHolder, then the parameter is set to "@value"

- If the path corresponds to a sequence item like for example "/SEQUENCE_NAME/5/NAME" for the "NAME" value of the 6th item of the "SEQUENCE_NAME" sequence then:

  - if the sequence already has 6 or more items, then the value is just set to the corresponding value in the 6th item of the sequence

  - if the sequence has less then 6 items, then items are added up to the 6th one before setting the value to the corresponding in the 6th item of the sequence

- If the path corresponds to a GdaDataModel, like for example "/ARRAY/@`COLUMN`/5" for the value at the 6th row of the "COLUMN" column of the "ARRAY" data model, then:

  - if the data model already contains 6 or more rows, then the value is just set

  - if the data model has less than 6 rows, then rows are added up to the 6th one before setting the value

`op` : | a GdaServerOperation object
`value` : | a string
`error` : | a place to store errors or `NULL`
`path_format` : | a complete path to a node (starting with "/")
`...` : | arguments to use with `path_format` to make a complete path
Returns : | `TRUE` if no error occurred

### gda_server_operation_save_data_to_xml ()

    xmlNodePtr          gda_server_operation_save_data_to_xml
                                                            (GdaServerOperation *op,
                                                             GError **error);

`op` : |
`error` : |
Returns : |

### gda_server_operation_load_data_from_xml ()

    gboolean            gda_server_operation_load_data_from_xml
                                                            (GdaServerOperation *op,
                                                             xmlNodePtr node,
                                                             GError **error);

Loads the contents of `node` into `op`. The XML tree passed through the `node` argument must correspond to an XML tree saved using `gda_server_operation_save_data_to_xml()`.

`op` : | a GdaServerOperation object
`node` : | a xmlNodePtr
`error` : | a place to store errors or `NULL`. [allow-none]
Returns : | `TRUE` if no error occurred

### gda_server_operation_is_valid ()

    gboolean            gda_server_operation_is_valid       (GdaServerOperation *op,
                                                             const gchar *xml_file,
                                                             GError **error);

Tells if all the required values in `op` have been defined.

if `xml_file` is not `NULL`, the validity of `op` is tested against that specification, and not against the current `op`'s specification.

`op` : | a GdaServerOperation widget
`xml_file` : | an XML specification file (see `gda_server_operation_new()`)
`error` : | a place to store an error, or `NULL`
Returns : | `TRUE` if `op` is valid

## Property Details

### The `"connection"` property

      "connection"               GdaConnection*        : Read / Write / Construct Only

Connection to use.

### The `"op-type"` property

      "op-type"                  gint                  : Read / Write / Construct Only

Type of operation to be done.

Allowed values: [0,15]

Default value: 0

### The `"provider"` property

      "provider"                 GdaServerProvider*    : Read / Write / Construct Only

Database provider which created the object.

### The `"spec-filename"` property

      "spec-filename"            gchar*                : Write / Construct Only

XML file which contains the object's data structure.

Default value: NULL

## Signal Details

### The `"sequence-item-added"` signal

    void                user_function                      (GdaServerOperation *op,
                                                            gchar              *seq_path,
                                                            gint                item_index,
                                                            gpointer            user_data)       : Run First

Gets emitted whenever a new sequence item (from a sequence template) has been added

`op` : | the GdaServerOperation
`seq_path` : | the path to the new sequence item
`item_index` : | the index (starting from 0) of the new sequence item in the sequence
`user_data` : | user data set when the signal handler was connected.

### The `"sequence-item-remove"` signal

    void                user_function                      (GdaServerOperation *op,
                                                            gchar              *seq_path,
                                                            gint                item_index,
                                                            gpointer            user_data)       : Run First

Gets emitted whenever a sequence item is about to be removed

`op` : | the GdaServerOperation
`seq_path` : | the path to the sequence item to be removed
`item_index` : | the index (starting from 0) of the sequence item in the sequence
`user_data` : | user data set when the signal handler was connected.