Syntax

SQLReturn
ExportTableToFile  (HDBC      hdbc, 
                   SQLCHAR*   TableName, 
                   SQLCHAR*   FileName, 
                   SQLLEN     IANAAppCodePage, 
                   SQLLEN     ErrorTolerance, 
                   SQLLEN     WarningTolerance, 
                   SQLCHAR*   LogFile)
ExportTableToFileW (HDBC      hdbc, 
                   SQLWCHAR*  TableName, 
                   SQLWCHAR*  FileName, 
                   SQLLEN     IANAAppCodePage, 
                   SQLLEN     ErrorTolerance, 
                   SQLLEN     WarningTolerance, 
                   SQLWCHAR*  LogFile)

The standard ODBC return codes are returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE, and SQL_ERROR.

Purpose

ExportTableToFile (ANSI application) and ExportTableToFileW (Unicode application) bulk export a table to a physical file. Both a bulk data file and a bulk configuration file are produced by this operation. The configuration file has the same name as the data file, but with an XML extension. The bulk export operation can create a log file and can also export to external files. Refer to "External overflow files" in the user's guide for your driver for more information. The export operation can be configured such that if any errors or warnings occur:

  • The operation always completes
  • The operation always terminates
  • The operation terminates after a certain threshold of warnings or errors is exceeded.

Parameters

hdbc
is the driver’s connection handle, which is not the handle returned by SQLAllocHandle or SQLAllocConnect. To obtain the driver's connection handle, the application must then use the standard ODBC function SQLGetInfo (ODBC Conn Handle, SQL_DRIVER_HDBC).
TableName
is a null-terminated string that specifies the name of the source database table that contains the data to be exported.
FileName
is a null-terminated string that specifies the path (relative or absolute) and file name of the bulk load data file to which the data is to be exported. It also specifies the file name of the bulk configuration file. The file name must be the fully qualified path to the bulk data file. This file must not already exist. If the file already exists, an error is returned.
IANAAppCodePage
specifies the code page value to which the driver must convert all data for storage in the bulk data file. See "Code page values" for details about IANAAppCodePage. Refer to "Character Set Conversions" in the user's guide for your driver for more information.

The default value on Windows is the current code page of the machine. On UNIX and Linux the default value is 4.

ErrorTolerance
specifies the number of errors to tolerate before an operation terminates. A value of 0 indicates that no errors are tolerated; the operation fails when the first error is encountered. The default of -1 means that an infinite number of errors is tolerated. WarningTolerance specifies the number of warnings to tolerate before an operation terminates. A value of 0 indicates that no warnings are tolerated; the operation fails when the first warning is encountered.
The default of -1 means that an infinite number of warnings is tolerated.
LogFile
is a null-terminated character string that specifies the path (relative or absolute) and file name of the bulk log file. Events logged to this file are:
  • Total number of rows fetched
  • A message for each row that failed to export
  • Total number of rows that failed to export
  • Total number of rows successfully exported

Information about the load is written to this file, preceded by a header. Information about the next load is appended to the end of the file.

If LogFile is NULL, no log file is created.

Example

HDBC      hdbc;
HENV      henv;
void      *driverHandle;
HMODULE      hmod;
PExportTableToFile exportTableToFile;

char      tableName[128];
char      fileName[512];
char      logFile[512];
int       errorTolerance;
int       warningTolerance;
int       codePage;

/* Get the driver's connection handle from the DM. This handle must be used when calling directly into the driver. */

rc = SQLGetInfo (hdbc, SQL_DRIVER_HDBC, &driverHandle, 0, NULL);
if (rc != SQL_SUCCESS) {
    ODBC_error (henv, hdbc, SQL_NULL_HSTMT);
    EnvClose (henv, hdbc);
    exit (255);
}

/* Get the DM's shared library or DLL handle to the driver. */

rc = SQLGetInfo (hdbc, SQL_DRIVER_HLIB, &hmod, 0, NULL);
if (rc != SQL_SUCCESS) {
    ODBC_error (henv, hdbc, SQL_NULL_HSTMT);
    EnvClose (henv, hdbc);
    exit (255);
}

exportTableToFile = (PExportTableToFile)
    resolveName (hmod, "ExportTableToFile");
if (! exportTableToFile) {
    printf ("Cannot find ExportTableToFile!\n");
    exit (255);
}

rc = (*exportTableToFile) (
      driverHandle,
      (const SQLCHAR *) tableName,
      (const SQLCHAR *) fileName,
      codePage,
      errorTolerance, warningTolerance,
      (const SQLCHAR *) logFile);
if (rc == SQL_SUCCESS) {
      printf ("Export succeeded.\n");
}else {
      driverError (driverHandle, hmod);
}