Home

	Expand Search

Chapter 3: The Database Tools Interface

DBTools functions

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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