## GdaServerOperation

GdaServerOperation — Handles any DDL query in an abstract way

## Stability Level

Stable, unless otherwise indicated

## 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,
                                                             ...);
    const GValue *      gda_server_operation_get_value_at_path
                                                            (GdaServerOperation *op,
                                                             const gchar *path);
    gchar *             gda_server_operation_get_sql_identifier_at
                                                            (GdaServerOperation *op,
                                                             GdaConnection *cnc,
                                                             GdaServerProvider *prov,
                                                             const gchar *path_format,
                                                             ...);
    gchar *             gda_server_operation_get_sql_identifier_at_path
                                                            (GdaServerOperation *op,
                                                             GdaConnection *cnc,
                                                             GdaServerProvider *prov,
                                                             const gchar *path);
    gboolean            gda_server_operation_set_value_at   (GdaServerOperation *op,
                                                             const gchar *value,
                                                             GError **error,
                                                             const gchar *path_format,
                                                             ...);
    gboolean            gda_server_operation_set_value_at_path
                                                            (GdaServerOperation *op,
                                                             const gchar *value,
                                                             const gchar *path,
                                                             GError **error);
    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_value_at_path ()

    const GValue *      gda_server_operation_get_value_at_path
                                                            (GdaServerOperation *op,
                                                             const gchar *path);

Get the value for the node at the `path` path

`op` : | a GdaServerOperation object
`path` : | a complete path to a node (starting with "/")
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]

Since 4.2.6

### 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`. [allow-none]
`prov` : | a GdaServerProvider, or `NULL`. [allow-none]
`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_get_sql_identifier_at_path ()

    gchar *             gda_server_operation_get_sql_identifier_at_path
                                                            (GdaServerOperation *op,
                                                             GdaConnection *cnc,
                                                             GdaServerProvider *prov,
                                                             const gchar *path);

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`. [allow-none]
`prov` : | a GdaServerProvider, or `NULL`. [allow-none]
`path` : | a complete path to a node (starting with "/")
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.2.6

### 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. [allow-none]
`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_set_value_at_path ()

    gboolean            gda_server_operation_set_value_at_path
                                                            (GdaServerOperation *op,
                                                             const gchar *value,
                                                             const gchar *path,
                                                             GError **error);

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. [allow-none]
`path` : | a complete path to a node (starting with "/")
`error` : | a place to store errors or `NULL`
Returns : | `TRUE` if no error occurred

Since 4.2.6

### gda_server_operation_save_data_to_xml ()

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

Creates a new xmlNodePtr tree which can be used to save the op object. This XML structure can then be saved to disk if necessary. Use xmlFreeNode to free the associated memory when not needed anymore.

`op` : | a GdaServerOperation object
`error` : | a place to store errors or `NULL`. [allow-none]
Returns : | a new xmlNodePtr structure, or `NULL`. [transfer full]

### 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()`) or `NULL`. [allow-none]
`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,
    	GDA_SERVER_OPERATION_XML_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`. [allow-none]
`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()`.

`provider` : | the database provider to use, or `NULL` if `op` has been created using `gda_server_operation_prepare_create_database()`. [allow-none]
`op` : | a GdaServerOperation object obtained 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`. [allow-none]
`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()`.

`provider` : | the database provider to use, or `NULL` if `op` has been created using `gda_server_operation_prepare_drop_database()`. [allow-none]
`op` : | a GdaServerOperation object obtained 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 GdaServerOperationCreateTableFlag 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 GdaServerOperationCreateTableFlag 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.