Programming Interfaces Guide
   CHAPTER 3. The Database Tools Interface     

DBTools functions

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 ( const backup_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 ( const change_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 ( const writefile * );

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 ( const db_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 ( const compress_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 ( const create_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 ( const writefile * );

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 ( const erase_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 ( const expand_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 ( const db_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 ( const db_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 ( const db_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 ( const writefile * );

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 when an application is finished with the DBTools library.

Prototype 

short DBToolsFini ( const dbtools_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( const dbtools_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 Adaptive Server Anywhere language DLL. The language DLL contains localized versions of 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 integer 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 ( const translate_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 ( const truncate_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 and also by the dbxtract utility for SQL Remote.

Prototype 

short DBUnload ( const unload_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 ( const validate_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