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

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

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.

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

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

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

Returns :

a new xmlNodePtr structure, or NULL

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

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,12]

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.