![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
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
);
"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
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.
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;
GdaServerOperationType gda_server_operation_get_op_type
(GdaServerOperation *op
);
Get the type of operation op
is for
|
a GdaServerOperation object |
Returns : |
a GdaServerOperationType enum |
const gchar * gda_server_operation_op_type_to_string
(GdaServerOperationType type
);
Get a string version of type
|
a GdaServerOperationType value |
Returns : |
a non NULL string (do not free or modify). [transfer none]
|
GdaServerOperationType gda_server_operation_string_to_op_type
(const gchar *str
);
Performs the reverse of gda_server_operation_op_type_to_string()
|
a string |
Returns : |
the GdaServerOperationType represented by str , or G_MAXINT if str is not a valid representation
of a GdaServerOperationType
|
Since 4.2
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()
)
|
a GdaServerOperation object |
|
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]
|
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
).
|
a GdaServerOperation object |
|
a GdaConnection, or NULL
|
|
a GdaServerProvider, or NULL
|
|
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
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
|
a GdaServerOperation object |
|
a string |
|
a place to store errors or NULL
|
|
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
|
xmlNodePtr gda_server_operation_save_data_to_xml (GdaServerOperation *op
,GError **error
);
|
|
|
|
Returns : |
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()
.
|
a GdaServerOperation object |
|
a xmlNodePtr |
|
a place to store errors or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred
|
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.
|
a GdaServerOperation widget |
|
an XML specification file (see gda_server_operation_new() )
|
|
a place to store an error, or NULL
|
Returns : |
TRUE if op is valid
|
typedef enum { GDA_SERVER_OPERATION_OBJECT_NAME_ERROR, GDA_SERVER_OPERATION_INCORRECT_VALUE_ERROR } GdaServerOperationError;
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;
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()
.
|
the database provider to use |
|
the name of the database to create, or NULL
|
|
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
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()
.
|
a GdaServerOperation object obtained using gda_server_operation_prepare_create_database()
|
|
the database provider to use, or NULL if op has been created using gda_server_operation_prepare_create_database()
|
|
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
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()
.
|
the database provider to use |
|
the name of the database to drop, or NULL
|
|
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
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()
.
|
a GdaServerOperation object obtained using gda_prepare_drop_database()
|
|
the database provider to use, or NULL if op has been created using gda_server_operation_prepare_drop_database()
|
|
a place to store en error, or NULL
|
Returns : |
TRUE if no error occurred and the database has been destroyed |
Since 4.2.3
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.
|
an opened connection |
|
name of the table to create |
|
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
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.
|
a valid GdaServerOperation |
|
a place to store errors, or NULL
|
Returns : |
TRUE if the table was created; FALSE and set error otherwise
|
Since 4.2.3
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.
|
an opened connection |
|
name of the table to drop |
|
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
gboolean gda_server_operation_perform_drop_table (GdaServerOperation *op
,GError **error
);
This is just a convenient function to perform a drop a table operation.
|
a GdaServerOperation object |
|
a place to store errors, or NULL
|
Returns : |
TRUE if the table was dropped |
Since 4.2.3
"connection"
property"connection" GdaConnection* : Read / Write / Construct Only
Connection to use.
"op-type"
property"op-type" gint : Read / Write / Construct Only
Type of operation to be done.
Allowed values: [0,15]
Default value: 0
"provider"
property"provider" GdaServerProvider* : Read / Write / Construct Only
Database provider which created the object.
"spec-filename"
property"spec-filename" gchar* : Write / Construct Only
XML file which contains the object's data structure.
Default value: NULL
"sequence-item-added"
signalvoid 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
|
the GdaServerOperation |
|
the path to the new sequence item |
|
the index (starting from 0) of the new sequence item in the sequence |
|
user data set when the signal handler was connected. |
"sequence-item-remove"
signalvoid 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
|
the GdaServerOperation |
|
the path to the sequence item to be removed |
|
the index (starting from 0) of the sequence item in the sequence |
|
user data set when the signal handler was connected. |