User's Guide

Part V. The SQL Anywhere Programming Interfaces

Chapter 35. Using the Database Tools Interface

This section describes the functions available in the DBTools library. The functions are listed alphabetically.

DBBackup function

Function

Database backup function. This function is used by the DBBACKUP command-line utility.

Prototype

     short DBBackup ( constbackup_db* );

Parameters

Parameter	Description
backup_db	Pointer to a_backup_db structure

Return value

A return code as listed in "Software component return codes".

Usage

The DBBackup function manages all database backup tasks. For descriptions of these tasks, see "The Backup utility".

See Also

• a_backup_db structure

DBChangeLogName function

Function

Changes the name of the transaction log file. This function is used by the DBLOG command-line utility.

Prototype

     short DBChangeLogName( constchange_log*);

Parameters

Parameter	Description
change_log	Pointer to a_change_log structure

Return value

A return code as listed in "Software component return codes".

Usage

The -t option of the DBLOG command line utility changes the name of the transaction log. DBChangeLogName provides a programmatic interface to this function.

For descriptions of the DBLOG utility, see "The Transaction Log utility".

See Also

• a_change_log structure

DBChangeWriteFile function

Function

Changes a write file to refer to another database file. This function is used by the DBWRITE command-line utility when the -d option is applied.

Prototype

     short DBChangeWriteFile( constwritefile*);

Parameters

Parameter	Description
writefile	Pointer to a_writefile structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Write File utility and its features, see "The Write File utility".

See Also

• DBCreateWriteFile function
• DBStatusWriteFile function
• a_writefile structure

DBCollate function

Function

Extracts a collation sequence from a database.

Prototype

     short DBCollate( constdb_collation*);

Parameters

Parameter	Description
db_collation	Pointer to a_db_collation structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the collation utility and its features, see "The Collation utility"

See Also

• a_db_collation structure

DBCompress function

Function

Compresses a database file. This function is used by the DBSHRINK command-line utility.

Prototype

     short DBCompress( constcompress_db*);

Parameters

Parameter	Description
compress_db	Pointer to a_compress_db structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Compression utility and its features, see "The Compression utility".

See Also

• a_compress_db structure

DBCreate function

Function

Creates a database. This function is used by the DBINIT command-line utility.

Prototype

     short DBCreate( constcreate_db*);

Parameters

Parameter	Description
create_db	Pointer to a_create_db structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the initialization utility, see "The Initialization utility"

See Also

• a_create_db structure

DBCreateWriteFile function

Function

Creates a write file. This function is used by the DBWRITE command-line utility when the -c option is applied.

Prototype

     short DBCreateWriteFile( constwritefile*);

Parameters

Parameter	Description
writefile	Pointer to a_writefile structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Write File utility and its features, see "The Write File utility".

See Also

• DBChangeWriteFile function
• DBStatusWriteFile function
• a_writefile structure

DBErase function

Function

Erases a database file and/or transaction log file. This function is used by the DBERASE command-line utility.

Prototype

     short DBErase( consterase_db*);

Parameters

Parameter	Description
erase_db	Pointer to an_erase_db structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Erase utility and its features, see "The Erase utility".

See Also

• an_erase_db structure

DBExpand function

Function

Uncompresses a database file. This function is used by the DBEXPAND command-line utility.

Prototype

     short DBExpand( constexpand_db*);

Parameters

Parameter	Description
&an_expand_db	Pointer to an_expand_db structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Uncompression utility and its features, see "The Uncompression utility".

See Also

• an_expand_db structure

DBInfo function

Function

Returns information about a database file. This function is used by the DBINFO command-line utility.

Prototype

     short DBInfo( constdb_info*);

Parameters

Parameter	Description
db_info	Pointer to a_db_info structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Information utility and its features, see "The Information utility".

See Also

• DBInfoDump function
• DBInfoFree function
• a_db_info structure

DBInfoDump function

Function

Returns information about a database file. This function is used by the DBINFO command-line utility when the -u option is used.

Prototype

     short DBInfoDump( constdb_info*);

Parameters

Parameter	Description
db_info	Pointer to a_db_info structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Information utility and its features, see "The Information utility".

See Also

• DBInfo function
• DBInfoFree function
• a_db_info structure

DBInfoFree function

Function

Called to free resources after the DBInfoDump function is called.

Prototype

     short DBInfoFree( constdb_info*);

Parameters

Parameter	Description
db_info	Pointer to a_db_info structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Information utility and its features, see "The Information utility".

See Also

• DBInfo function
• DBInfoDump function
• a_db_info structure

DBStatusWriteFile function

Function

Gets the status of a write file. This function is used by the DBWRITE command-line utility when the -s option is applied.

Prototype

     short DBStatusWriteFile( constwritefile*);

Parameters

Parameter	Description
writefile	Pointer to a_writefile structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Write File utility and its features, see "The Write File utility".

See Also

• DBChangeWriteFile function
• DBCreateWriteFile function
• a_writefile structure

DBToolsFini function

Function

Decrements the counter and frees resources after DBTools library is finished with.

Prototype

     short DBToolsFini ( constdbtools_info*);

Parameters

Parameter	Description
dbtools_info	Pointer to a_dbtools_info structure

Return value

A return code as listed in "Software component return codes".

Usage

The DBToolsFini function must be called at the end of any application that uses the DBTools interface. Failure to do so can lead to lost memory resources.

See Also

• DBToolsInit function
• a_dbtools_info structure

DBToolsInit function

Function

Prepares the DBTools library for use.

Prototype

     short DBToolsInit t( constdbtools_info*);

Parameters

Parameter	Description
dbtools_info	Pointer to a_dbtools_info structure

Return value

A return code as listed in "Software component return codes".

Usage

The primary purpose of the DBToolsInit function is to load the SQL Anywhere language DLL. The language DLL contains localized versions of all the error messages and prompts that DBTools uses internally.

The DBToolsInit function must be called at the start of any application that uses the DBTools interface, before any other DBTools functions.

Example

• The following code sample illustrates how to initialize and clean up DBTools:

       a_dbtools_info    info;
       short            ret;
       
       memset( &info, 0, sizeof( a_dbtools_info) );
       info.errorrtn = (MSG_CALLBACK)MakeProcInstance(                 (FARPROC)MyErrorRtn, hInst );
       
       // initialize DBTools
       ret = DBToolsInit( &info );
       if( ret != EXIT_OKAY ) {
               // DLL initialization failed
               ...
           }
           // call some DBTools routines . . .
           ...
           // cleanup the DBTools dll
           DBToolsFini( &info );
  

See Also

• DBToolsFini function
• a_dbtools_info structure

DBToolsVersion function

Function

Returns the version number of the DBTools library.

Prototype

     short DBToolsVersion ( void );

Return value

A short indicating the version number of the DBTools library.

Usage

Use the DBToolsVersion function to check that the DBTools library is not older than one against which your application is developed. While applications can run against newer versions of DBTools, they cannot run against older versions.

See Also

• Version numbers and compatibility

DBTranslateLog function

Function

Translates a transaction log file to SQL. This function is used by the DBTRAN command-line utility.

Prototype

     short DBTranslateLog( consttranslate_log*);

Parameters

Parameter	Description
translate_log	Pointer to a_translate_log structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the log translation utility, see "The Log Translation utility".

See Also

• a_translate_log structure

DBTruncateLog function

Function

Truncates a transaction log file. This function is used by the DBBACKUP command-line utility.

Prototype

     short DBTruncateLog( consttruncate_log*);

Parameters

Parameter	Description
truncate_log	Pointer to a_truncate_log structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the backup utility, see "The Backup utility"

See Also

• a_truncate_log structure

DBUnload function

Function

Unloads a database. This function is used by the DBUNLOAD command-line utility.

Prototype

     short DBUnload( constunload_db*);

Parameters

Parameter	Description
an_unload_db	Pointer to an_unload_db structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the Unload utility, see "The Unload utility".

See Also

• an_unload_db structure

DBUpgrade function

Function

Upgrades a database file. This function is used by the DBUPGRADE command-line utility.

Prototype

     short DBUpgrade( const upgrade_db*);

Parameters

Parameter	Description
upgrade_db	Pointer to an_upgrade_db structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the upgrade utility, see "The Upgrade utility".

See Also

• an_upgrade_db structure

DBValidate function

Function

Validates all or part of a database. This function is used by the DBVALID command-line utility.

Prototype

     short DBValidate( constvalidate_db* );

Parameters

Parameter	Description
validate_db	Pointer to a_validate_db structure

Return value

A return code as listed in "Software component return codes".

Usage

For information about the upgrade utility, see "The Validation utility".

See Also

• a_validate_db structure