GdaServerOperation

GdaServerOperation — Handles any DDL query in an abstract way

Stability Level

Stable, unless otherwise indicated

Properties

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

Signals

void sequence-item-added Run First
void sequence-item-remove Run First

Object Hierarchy

    GObject
    ╰── GdaServerOperation

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.

Functions

gda_server_operation_get_op_type ()

GdaServerOperationType
gda_server_operation_get_op_type (GdaServerOperation *op);

Get the type of operation op is for

Parameters

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

Parameters

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()

Parameters

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())

Parameters

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

Parameters

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][allow-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).

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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


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().

Parameters

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().

Parameters

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().

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

op

a GdaServerOperation object

 

error

a place to store errors, or NULL

 

Returns

TRUE if the table was dropped

Since 4.2.3

Types and Values

GdaServerOperation

typedef struct _GdaServerOperation GdaServerOperation;

enum GdaServerOperationType

Members

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

   

enum GdaServerOperationError

Members

GDA_SERVER_OPERATION_OBJECT_NAME_ERROR

   

GDA_SERVER_OPERATION_INCORRECT_VALUE_ERROR

   

GDA_SERVER_OPERATION_XML_ERROR

   

enum GdaServerOperationCreateTableFlag

Members

GDA_SERVER_OPERATION_CREATE_TABLE_NOTHING_FLAG

   

GDA_SERVER_OPERATION_CREATE_TABLE_PKEY_FLAG

   

GDA_SERVER_OPERATION_CREATE_TABLE_NOT_NULL_FLAG

   

GDA_SERVER_OPERATION_CREATE_TABLE_UNIQUE_FLAG

   

GDA_SERVER_OPERATION_CREATE_TABLE_AUTOINC_FLAG

   

GDA_SERVER_OPERATION_CREATE_TABLE_FKEY_FLAG

   

GDA_SERVER_OPERATION_CREATE_TABLE_PKEY_AUTOINC_FLAG

   

Property Details

The “connection” property

  “connection”               GdaConnection *

Connection to use.

Flags: Read / Write / Construct Only


The “op-type” property

  “op-type”                  gint

Type of operation to be done.

Flags: Read / Write / Construct Only

Allowed values: [0,15]

Default value: 0


The “provider” property

  “provider”                 GdaServerProvider *

Database provider which created the object.

Flags: Read / Write / Construct Only


The “spec-filename” property

  “spec-filename”            gchar *

XML file which contains the object's data structure.

Flags: Write / Construct Only

Default value: NULL

Signal Details

The “sequence-item-added” signal

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

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

Parameters

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.

 

Flags: Run First


The “sequence-item-remove” signal

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

Gets emitted whenever a sequence item is about to be removed

Parameters

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.

 

Flags: Run First