## 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);

    enum                GdaServerOperationError;
    enum                GdaServerOperationCreateTableFlag;
    GdaServerOperation * gda_server_operation_prepare_create_database
                                                            (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);
    gboolean            gda_server_operation_perform_create_database
                                                            (GdaServerOperation *op,
                                                             const gchar *provider,
                                                             GError **error);
    GdaServerOperation * gda_server_operation_prepare_drop_database
                                                            (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);
    gboolean            gda_server_operation_perform_drop_database
                                                            (GdaServerOperation *op,
                                                             const gchar *provider,
                                                             GError **error);
    GdaServerOperation * gda_server_operation_prepare_create_table
                                                            (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error,
                                                             ...);
    gboolean            gda_server_operation_perform_create_table
                                                            (GdaServerOperation *op,
                                                             GError **error);
    GdaServerOperation * gda_server_operation_prepare_drop_table
                                                            (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error);
    gboolean            gda_server_operation_perform_drop_table
                                                            (GdaServerOperation *op,
                                                             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

### enum GdaServerOperationError

    typedef enum {
    	GDA_SERVER_OPERATION_OBJECT_NAME_ERROR,
    	GDA_SERVER_OPERATION_INCORRECT_VALUE_ERROR
    } GdaServerOperationError;

### enum GdaServerOperationCreateTableFlag

    typedef enum
    {
    	GDA_SERVER_OPERATION_CREATE_TABLE_NOTHING_FLAG   = 1 << 0,
    	GDA_SERVER_OPERATION_CREATE_TABLE_PKEY_FLAG      = 1 << 1,
    	GDA_SERVER_OPERATION_CREATE_TABLE_NOT_NULL_FLAG  = 1 << 2,
    	GDA_SERVER_OPERATION_CREATE_TABLE_UNIQUE_FLAG    = 1 << 3,
    	GDA_SERVER_OPERATION_CREATE_TABLE_AUTOINC_FLAG   = 1 << 4,
    	GDA_SERVER_OPERATION_CREATE_TABLE_FKEY_FLAG      = 1 << 5,
    	/* Flags combinations */
    	GDA_SERVER_OPERATION_CREATE_TABLE_PKEY_AUTOINC_FLAG = GDA_SERVER_OPERATION_CREATE_TABLE_PKEY_FLAG | GDA_SERVER_OPERATION_CREATE_TABLE_AUTOINC_FLAG
    } GdaServerOperationCreateTableFlag;

### gda_server_operation_prepare_create_database ()

    GdaServerOperation * gda_server_operation_prepare_create_database
                                                            (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);

Creates a new GdaServerOperation object which contains the specifications required to create a database. Once these specifications provided, use `gda_server_operation_perform_create_database()` to perform the database creation.

If `db_name` is left `NULL`, then the name of the database to create will have to be set in the returned GdaServerOperation using `gda_server_operation_set_value_at()`.

`provider` : | the database provider to use
`db_name` : | the name of the database to create, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | new GdaServerOperation object, or `NULL` if the provider does not support database creation. [transfer full][allow-none]

Since 4.2.3

### gda_server_operation_perform_create_database ()

    gboolean            gda_server_operation_perform_create_database
                                                            (GdaServerOperation *op,
                                                             const gchar *provider,
                                                             GError **error);

Creates a new database using the specifications in `op`. `op` can be obtained using `gda_server_provider_create_operation()`, or `gda_server_operation_prepare_create_database()`.

`op` : | a GdaServerOperation object obtained using `gda_server_operation_prepare_create_database()`
`provider` : | the database provider to use, or `NULL` if `op` has been created using `gda_server_operation_prepare_create_database()`
`error` : | a place to store en error, or `NULL`
Returns : | TRUE if no error occurred and the database has been created, FALSE otherwise

Since 4.2.3

### gda_server_operation_prepare_drop_database ()

    GdaServerOperation * gda_server_operation_prepare_drop_database
                                                            (const gchar *provider,
                                                             const gchar *db_name,
                                                             GError **error);

Creates a new GdaServerOperation object which contains the specifications required to drop a database. Once these specifications provided, use `gda_server_operation_perform_drop_database()` to perform the database creation.

If `db_name` is left `NULL`, then the name of the database to drop will have to be set in the returned GdaServerOperation using `gda_server_operation_set_value_at()`.

`provider` : | the database provider to use
`db_name` : | the name of the database to drop, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | new GdaServerOperation object, or `NULL` if the provider does not support database destruction. [transfer full][allow-none]

Since 4.2.3

### gda_server_operation_perform_drop_database ()

    gboolean            gda_server_operation_perform_drop_database
                                                            (GdaServerOperation *op,
                                                             const gchar *provider,
                                                             GError **error);

Destroys an existing database using the specifications in `op`. `op` can be obtained using `gda_server_provider_create_operation()`, or `gda_server_operation_prepare_drop_database()`.

`op` : | a GdaServerOperation object obtained using `gda_prepare_drop_database()`
`provider` : | the database provider to use, or `NULL` if `op` has been created using `gda_server_operation_prepare_drop_database()`
`error` : | a place to store en error, or `NULL`
Returns : | TRUE if no error occurred and the database has been destroyed

Since 4.2.3

### gda_server_operation_prepare_create_table ()

    GdaServerOperation * gda_server_operation_prepare_create_table
                                                            (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error,
                                                             ...);

Add more arguments if the flag needs them:

GDA_SERVER_OPERATION_CREATE_TABLE_FKEY_FLAG:

- string with the table's name referenced

- an integer with the number pairs "local_field", "referenced_field" used in the reference

- Pairs of "local_field", "referenced_field" to use, must match the number specified above.

- a string with the action for ON DELETE; can be: "RESTRICT", "CASCADE", "NO ACTION", "SET NULL" and "SET DEFAULT". Example: "ON UPDATE CASCADE".

- a string with the action for ON UPDATE (see above).

Create a GdaServerOperation object using an opened connection, taking three arguments, a column's name the column's GType and GdaEasyCreateTableFlag flag, you need to finish the list using `NULL`.

You'll be able to modify the GdaServerOperation object to add custom options * to the operation. When finished call gda_server_operation_perform_create_table or gda_server_provider_perform_operation in order to execute the operation.

`cnc` : | an opened connection
`table_name` : | name of the table to create
`error` : | a place to store errors, or `NULL`
`...` : | group of three arguments for column's name, column's GType and a GdaEasyCreateTableFlag flag, finished with `NULL`
Returns : | a GdaServerOperation if no errors; NULL and set `error` otherwise. [transfer full][allow-none]

Since 4.2.3

### gda_server_operation_perform_create_table ()

    gboolean            gda_server_operation_perform_create_table
                                                            (GdaServerOperation *op,
                                                             GError **error);

Performs a prepared GdaServerOperation to create a table. This could perform an operation created by gda_server_operation_prepare_create_table or any other using the the GdaServerOperation API.

`op` : | a valid GdaServerOperation
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if the table was created; FALSE and set `error` otherwise

Since 4.2.3

### gda_server_operation_prepare_drop_table ()

    GdaServerOperation * gda_server_operation_prepare_drop_table
                                                            (GdaConnection *cnc,
                                                             const gchar *table_name,
                                                             GError **error);

This is just a convenient function to create a GdaServerOperation to drop a table in an opened connection.

`cnc` : | an opened connection
`table_name` : | name of the table to drop
`error` : | a place to store errors, or `NULL`
Returns : | a new GdaServerOperation or `NULL` if couldn't create the opereration. [transfer full][allow-none]

Since 4.2.3

### gda_server_operation_perform_drop_table ()

    gboolean            gda_server_operation_perform_drop_table
                                                            (GdaServerOperation *op,
                                                             GError **error);

This is just a convenient function to perform a drop a table operation.

`op` : | a GdaServerOperation object
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if the table was dropped

Since 4.2.3

## 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.