User's Guide Part V. The SQL Anywhere Programming Interfaces Chapter 35. Using the Database Tools InterfaceThis section lists the structures that are used to exchange information with the DBTools library. The structures are listed alphabetically.
Many of the structure elements correspond to command-line switches on the corresponding utility. For example, several structures have a member named quiet, which can take on values of 0 or 1,. This member corresponds to the quiet operation (-q) command-line option used by many of the utilities.
Holds the information needed to carry out backup tasks using the DBTools library.
typedef struct a_backup_db {unsigned short version;const char * output_dir;const char * connectparms;const char * startline;MSG_CALLBACK confirmrtn;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;MSG_CALLBACK statusrtn;char backup_database : 1;char backup_logfile : 1;char backup_writefile: 1;char no_confirm : 1;char quiet : 1;char rename_log : 1;char truncate_log : 1;char rename_local_log: 1;const char * hotlog_filename;} a_backup_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| output_dir | Path to the output directory. For example: |
| connectparms | Parameters needed to connect to the database. They take the form of connection strings, such as the following: For the full range of connection string options, see "Database connection parameters" |
| startline | Command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| confirmrtn | Callback routine for confirming an action. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| statusrtn | Callback routine for handling a status message. |
| backup_database | Backup the database file (1) or not (0). |
| backup_logfile | Backup the transaction log file (1) or not (0). |
| backup_writefile | Backup the database write file (1) or not (0), if a write file is being used. |
| no_confirm | Operate with (0) or without (1) confirmation |
| quiet | Operate without printing messages (1), or print messages (0). |
| rename_log | rename the transaction log |
| truncate_log | delete the transaction log |
| rename_local_log | rename the local backup of the transaction log |
| hotlog_filename | file name for the live backup file |
Holds the information needed to carry out DBLOG tasks using the DBTools library.
typedef struct a_change_log {unsigned short version;const char * dbname;const char * logname;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;char query_only : 1;char quiet : 1;char mirrorname_present : 1;char change_mirrorname : 1;char change_logname : 1;char ignore_ltm_trunc : 1;char ignore_remote_trunc : 1;char set_generation_number : 1;const char * mirrorname;unsigned short generation_number;} a_change_log;
| Member | Description |
|---|---|
| version | DBTools version number. |
| dbname | Database file name |
| logname | The name of the transaction log. If set to NULL, there is no log. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| query_only | If 1, just display the name of the transaction log. If 0, permit changing of the log name.. |
| quiet | Operate without printing messages (1), or print messages (0). |
| mirrorname_present | Set to 1. Indicates that the version of DBTools is recent enough to support the mirrorname field. |
| change_mirrorname | If 1, permit changing of the log mirror name. |
| change_logname | If 1, permit changing of the transaction log name. |
| ignore_ltm_trunc | When using the SQL Anywhere Log Transfer Manager, performs the same function as the dbcc settrunc( 'ltm', 'gen_id', n ) Replication Server function:For information on dbcc, see your Replication Server documentation. |
| ignore_remote_trunc | For SQL Remote. Resets the offset kept for the purposes of the DELETE_OLD_LOGS option, allowing transaction logs to be deleted when they are no longer needed. |
| set_generation_number | When using the SQL Anywhere Log Transfer Manager, used after a backup is restored to set the generation number. |
| mirrorname | The new name of the transaction log mirror file. |
| generation_number | The new generation number. Used together with set_generation_number. |
Holds the information needed to carry out database compression tasks using the DBTools library.
typedef struct a_compress_db {unsigned short version;const char * dbname;const char * compress_name;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;MSG_CALLBACK statusrtn;char display_free_pages : 1;char quiet : 1;char record_unchanged : 1;a_compress_stats * stats;MSG_CALLBACK confirmrtn;char noconfirm : 1;} a_compress_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| dbname | The filename of the database to compress. |
| compress_name | The filename of the compressed database |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| statusrtn | Callback routine for handling a status message. |
| display_free_pages | Show the free page information. |
| quiet | Operate without printing messages (1), or print messages (0). |
| record_unchanged | Set to 1. Indicates that the a_compress_stats structure is recent enough to have an unchanged member. |
| a_compress_stats | Pointer to a structure of type a_compress_stats. This is filled in if the member is not NULL and display_free_pages is not zero. |
| confirmrtn | Callback routine for confirming an action. |
| noconfirm | Operate with (0) or without (1) confirmation. |
Holds information describing compressed database file statistics using the DBTools library.
typedef struct a_compress_stats {a_stats_line tables;a_stats_line indices;a_stats_line other;a_stats_line free;a_stats_line total;long free_pages;long unchanged;} a_compress_stats;
| Member | Description |
|---|---|
| tables | Holds compression information regarding tables. |
| indices | Holds compression information regarding indexes |
| other | Holds other compression information |
| free | Holds information regarding free space. |
| total | Holds overall compression information. |
| free_pages | Holds information regarding free pages. |
| unchanged | The number of pages that the compression algorithm was unable to shrink. |
Holds the information needed to create a database using the DBTools library.
typedef struct a_create_db {unsigned short version;const char * dbname;const char * logname;const char * startline;short page_size;const char * default_collation;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;short database_version;char verbose;char blank_pad : 2;char respect_case : 1;char encrypt : 1;char debug : 1;char dbo_avail : 1;char mirrorname_present : 1;char avoid_view_collisions : 1;short collation_id;const char * dbo_username;const char * mirrorname;} a_create_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| dbname | Database file name |
| logname | New transaction log name |
| startline | The command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| page_size | The page size of the database. |
| default_collation | The collation for the database. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| database_version | The version number of the database. |
| verbose | Run in verbose mode. |
| blank_pad | Treat blanks as significant in string comparisons, and hold index information to reflect this. |
| respect_case | Make string comparisons case sensitive, and hold index information to reflect this. |
| encrypt | Enrypt the database. |
| debug | Reserved. |
| dbo_avail | Set to 1. The dbo user is available in this database. |
| mirrorname_present | Set to 1. Indicates that the version of DBTools is recent enough to support the mirrorname field. |
| avoid_view_collisions | Omit the generation of Watcom SQL compatibility views sys.syscolumns and sys.sysindexes. |
| collation_id | Collation identifier. |
| dbo_username | User name for the "dbo" user. |
| mirrorname | Transaction log mirror name. |
Holds the information needed to extract a collation sequence from a database using the DBTools library.
typedef struct a_db_collation {unsigned short version;const char * connectparms;const char * startline;const char * collation_label;const char * filename;MSG_CALLBACK confirmrtn;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;char include_empty : 1;char hex_for_extended : 1;char replace : 1;char quiet : 1;} a_db_collation;
| Member | Description |
|---|---|
| version | DBTools version number. |
| connectparms | The parameters needed to connect to the database. They take the form of connection strings, such as the following: For the full range of connection string options, see "Database connection parameters" |
| startline | The command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| confirmrtn | Callback routine for confirming an action. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| include_empty | Write empty mappings for gaps in the collations sequence. |
| hex_for_extended | Use two-digit hexadecimal numbers to represent high value characters. |
| replace | Operate without confirming actions. |
| quiet | Operate without messages. |
Holds the information needed to return DBINFO information using the DBTools library.
typedef struct a_db_info {unsigned short version;MSG_CALLBACK errorrtn;const char * dbname;unsigned short dbbufsize;char * dbnamebuffer;unsigned short logbufsize;char * lognamebuffer;unsigned short wrtbufsize;char * wrtnamebuffer;char quiet : 1;char mirrorname_present : 1;a_sysinfo sysinfo;unsigned long free_pages;unsigned char compressed : 1;const char * connectparms;const char * startline;MSG_CALLBACK msgrtn;MSG_CALLBACK statusrtn;unsigned char page_usage : 1;a_table_info * totals;unsigned long file_size;unsigned long unused_pages;unsigned long other_pages;unsigned short mirrorbufsize;char * mirrornamebuffer;} a_db_info;
| Member | Description |
|---|---|
| version | DBTools version number. |
| errortrn | Callback routine for handling an error message. |
| dbname | Database file name. |
| dbbufsize | The length of the dbnamebuffer member. |
| dbnamebuffer | Database file name. |
| logbufsize | The length of the lognamebuffer member. |
| lognamebuffer | Transaction log file name. |
| wrtbufsize | The length of the wrtnamebuffer member. |
| wrtnamebuffer | The write file name. |
| quiet | Operate without confirming messages. |
| mirrorname_present | Set to 1. Indicates that the version of DBTools is recent enough to support the mirrorname field. |
| sysinfo | Pointer to a_sysinfo structure. |
| free_pages | Number of free pages. |
| compressed | 1 if compresses, otherwise 0. |
| connectparms | The parameters needed to connect to the database. They take the form of connection strings, such as the following: For the full range of connection string options, see "Database connection parameters". |
| startline | The command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| msgrtn | Callback routine for handling an information message. |
| statusrtn | Callback routine for handling a status message. |
| page_usage | 1 to report page usage statistics, otherwise 0. |
| totals | Pointer to a_table_info structure. |
| file_size | Size of database file. |
| unused_pages | Number of unused pages. |
| other_pages | Number of pages that are neither table nor index pages. |
| mirrorbufsize | The length of the mirrornamebuffer member. |
| mirrornamebuffer | The transaction log mirror name. |
Holds the information needed to start and finish working with the DBTools library.
typedef struct a_dbtools_info {MSG_CALLBACK errorrtn;} a_dbtools_info;
| Member | Description |
|---|---|
| errorrtn | Callback routine for handling an error message. |
Holds information needed to erase a database using the DBTools library.
typedef struct an_erase_db {unsigned short version;const char * dbname;MSG_CALLBACK confirmrtn;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;char quiet : 1;char erase : 1;} an_erase_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| dbname | Database file name to erase. |
| confirmrtn | Callback routine for confirming an action. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| quiet | Operate without printing messages (1), or print messages (0). |
| erase | Erase without confirmation (1) or with confirmation (0). |
Holds information needed for database expansion using the DBTools library.
typedef struct an_expand_db {unsigned short version;const char * compress_name;const char * dbname;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;MSG_CALLBACK statusrtn;char quiet : 1;MSG_CALLBACK confirmrtn;char noconfirm : 1;} an_expand_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| compress_name | Name of compressed database file |
| dbname | Database file name |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| statusrtn | Callback routine for handling a status message. |
| quiet | Operate without printing messages (1), or print messages (0). |
| confirmrtn | Callback routine for confirming an action. |
| noconfirm | Operate with (0) or without (1) confirmation. |
To hold a linked list of names. This is used by other structures requiring lists of names.
typedef struct a_name {struct a_name * next;char name[1];} a_name, * p_name;
| Member | Description |
|---|---|
| next | Pointer to the next a_name structure in the list |
| name | The name. |
| p_name | Pointer to the a_name structure |
Holds information needed for database compression and expansion using the DBTools library.
typedef struct a_stats_line {long pages;long bytes;long compressed_bytes;} a_stats_line;
| Member | Description |
|---|---|
| pages | Number of pages. |
| bytes | Number of bytes for uncompressed database. |
| compressed_bytes | Number of bytes for compressed database. |
Holds information needed for DBINFO and DBUNLOAD utilities using the DBTools library.
typedef struct a_sysinfo {char valid_data : 1;char blank_padding : 1;char case_sensitivity : 1;char encryption : 1;char default_collation[11];unsigned short page_size;} a_sysinfo;
| Member | Description |
|---|---|
| valid_date | Bit-field indicating whether following values are set. |
| blank_padding | 1 if blank padding is used in this database. 0 otherwise. |
| case_sensitivity | 1 if the database is case-sensitive, 0 otherwise. |
| encryption | 1 if the database is encrypted, 0 otherwise. |
| default_collation | The collation sequence for the database. |
| page_size | The page size for the database. |
Holds information about a table needed as part of the a_db_info structure.
typedef struct a_table_info {struct a_table_info * next;unsigned short table_id;unsigned long table_pages;unsigned long index_pages;unsigned long table_used;unsigned long index_used;char * table_name;} a_table_info;
| Member | Description |
|---|---|
| next | Next table in the list |
| table_id | ID number for this table |
| table_pages | Number of table pages |
| index_pages | Number of index pages |
| table_used | Number of bytes used in table pages |
| index_used | Number of bytes used in index pages |
| table_name | Name of the table |
Holds information needed for transaction log translation using the DBTools library.
typedef struct a_translate_log {unsigned short version;const char * logname;const char * sqlname;p_name userlist;MSG_CALLBACK confirmrtn;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;char userlisttype;char remove_rollback : 1;char ansi_sql : 1;char since_checkpoint: 1;char omit_comments : 1;char replace : 1;char debug : 1;char include_trigger_trans : 1;char comment_trigger_trans : 1;unsigned long since_time;} a_translate_log;
| Member | Description |
|---|---|
| version | DBTools version number. |
| logname | The name of the transaction log file. |
| sqlname | The name of the SQL command file. |
| userlist | Pointer to a linked list of users. |
| confirmrtn | Callback routine for confirming an action. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| userlisttype | A member of the dbtran_userlist_type enumeration. |
| remove_rollback | 1 to remove changes that have been rolled back. 0 otherwise. |
| ansi_sql | If set to 0, for cases where there is no primary key or unique index on a table, UPDATE statements with a non-standard FIRST keyword are generated, in case of duplicate rows. If set to 1, do not output this keyword. |
| since_checkpoint | If 1, translate entries since the last checkpoint only. |
| omit_comments | If 1, omit comments. |
| replace | Replace files without prompting for confirmation. |
| debug | Reserved. |
| include_trigger_trans | If 1, include trigger actions. |
| comment_trigger_trans | If 1, include trigger actions as comments in the SQL file. |
| since_time | Translate entries only since the specified time. |
Holds information needed for transaction log truncation using the DBTools library.
typedef struct a_truncate_log {unsigned short version;const char * connectparms;const char * startline;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;char quiet : 1;} a_truncate_log;
| Member | Description |
|---|---|
| version | DBTools version number. |
| connectparms | The parameters needed to connect to the database. They take the form of connection strings, such as the following: For the full range of connection string options, see "Database connection parameters" |
| startline | The command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| quiet | Operate without printing messages (1), or print messages (0). |
Holds information needed to unload a database using the DBTools library.
typedef struct an_unload_db {unsigned short version;const char * connectparms;const char * startline;const char * temp_dir;const char * reload_filename;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;MSG_CALLBACK statusrtn;MSG_CALLBACK confirmrtn;char unload_type;char verbose;char unordered : 1;char no_confirm : 1;char use_internal_unload : 1;char dbo_avail : 1;char extract : 1;char table_list_provided : 1;char exclude_tables : 1;char more_flag_bits_present : 1;a_sysinfo sysinfo;const char * remote_dir;const char * dbo_username;const char * subscriber_username;const char * publisher_address_type;const char * publisher_address;unsigned short isolation_level;char start_subscriptions : 1;char exclude_foreign_keys : 1;char exclude_procedures : 1;char exclude_triggers : 1;char exclude_views : 1;char isolation_set : 1;char include_where_subscribe : 1;p_name table_list;unsigned short escape_char_present : 1;unsigned short view_iterations_present : 1;unsigned short view_iterations;char escape_char;} an_unload_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| connectparms | The parameters needed to connect to the database. They take the form of connection strings, such as the following: For the full range of connection string options, see "Database connection parameters". |
| startline | The command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| confirmrtn | Callback routine for confirming an action. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| statusrtn | Callback routine for handling a status message. |
| unload_type | A member of the dbunload type enumeration |
| verbose | Operate in verbose mode. |
| unordered | If 1, output the data unordered. |
| no_confirm | If 1, operate without confirming actions. |
| use_internal_unload | If 1, use the UNLOAD TABLE unloading. Of 0, use the ISQL OUTPUT statement. |
| dbo_avail | Set to 1. Indicates that the version of DBTools is recent enough to support the dbo_username field. |
| extract | If 1 carry out a SQL Remote extraction. Otherwise carry out an unload. |
| table_list_provided | If 1, a table list is provided. Unload data for those tables only. |
| exclude_tables | If 1, exclude data for the listed tables. |
| more_flag_bits_present | Set to 1. Indicates that the version of DBTools is recent enough to support the dbo_username field. |
| sysinfo | Pointer to a_sysinfo structure. |
| remote_dir | If extracting a database, the directory for remote users. |
| dbo_username | Username for the dbo user. |
| subscriber_username | If extracting a database, the user name of the subscriber. |
| publisher_address_type | If extracting a database, the message type for the publisher. |
| publisher_address | If extracting a database, the address for the publisher. |
| isolation_level | If extracting a database, perform the extraction at the specified isolation level. |
| start_subscriptions | If extracting a database, start the subscription. |
| exclude_foreign_keys | If extracting a database, exclude foreign key definitions. |
| exclude_procedures | If extracting a database, exclude procedures. |
| exclude_triggers | If extracting a database, exclude triggers. |
| exclude_views | If extracting a database, exclude views. |
| isolation_set | Set to 1 if the isolation level is set value. |
| include_where_subscribe | If extracting a database, extract fully qualified publications and subscriptions. |
| table_list | Pointer to a linked list of table names. |
| escape__present | Set to 1 if a non-default escape character is being specified. |
| view_iterations_present | Set to 1. Indicates that the version of DBTools is recent enough to support the view iterations option. |
| view_iterations | If your database contains view definitions that are dependent on each other, use this option to avoid failure in reloading the views into a database. The option causes view creation statements to be unloaded multiple times, as specified by the count entered. |
| escape | Escape character. |
Holds information needed to upgrade a database using the DBTools library.
typedef struct an_upgrade_db {unsigned short version;const char * connectparms;const char * startline;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;MSG_CALLBACK statusrtn;char quiet : 1;char dbo_avail : 1;const char * dbo_username;} an_upgrade_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| connectparms | The parameters needed to connect to the database. They take the form of connection strings, such as the following: For the full range of connection string options, see "Database connection parameters". |
| startline | The command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| statusrtn | Callback routine for handling a status message. |
| quiet | Operate without printing messages (1), or print messages (0). |
| dbo_avail | Set to 1. Indicates that the version of DBTools is recent enough to support the dbo_username field. |
| dbo_username | The name to use for the dbo. |
Holds information needed for database validation using the DBTools library.
typedef struct a_validate_db {unsigned short version;const char * connectparms;const char * startline;p_name tables;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;MSG_CALLBACK statusrtn;char quiet : 1;} a_validate_db;
| Member | Description |
|---|---|
| version | DBTools version number. |
| connectparms | The parameters needed to connect to the database. They take the form of connection strings, such as the following: For the full range of connection string options, see "Database connection parameters". |
| startline | The command line used to start the database engine. The following is an example start line: The default start line is used if this member is NULL. |
| tables | Pointer to a linked list of table names. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| statusrtn | Callback routine for handling a status message. |
| quiet | Operate without printing messages (1), or print messages (0). |
For more information on callback functions, see "Using callback functions".
Holds information needed for database write file management using the DBTools library.
typedef struct a_writefile {unsigned short version;const char * writename;const char * wlogname;const char * dbname;const char * forcename;MSG_CALLBACK confirmrtn;MSG_CALLBACK errorrtn;MSG_CALLBACK msgrtn;char action;char quiet : 1;char erase : 1;char force : 1;char mirrorname_present : 1;const char * wlogmirrorname;} a_writefile;
| Member | Description |
|---|---|
| version | DBTools version number. |
| writename | Write file name. |
| wlogname | Used only when creating write files. |
| dbname | Used when changing and creating write files. |
| forcename | Forced filename reference. |
| confirmrtn | Callback routine for confirming an action. Only used when creating a write file. |
| errorrtn | Callback routine for handling an error message. |
| msgrtn | Callback routine for handling an information message. |
| action | Reserved for use by Sybase. |
| quiet | Operate without printing messages (1), or print messages (0). |
| erase | Used for creating write files only. Erase without confirmation (1) or with confirmation (1). |
| force | If 1, force the write file to point to a named file. |
| mirrorname_present | Used when creating only. Set to 1. Indicates that the version of DBTools is recent enough to support the mirrorname field. |
| wlogmirrorname | Name of the transaction log mirror. |