SQLCreateDb function (CLI) - Create a database

The SQLCreateDb() function creates a database by using the specified database name, code set, and mode.

Specification:

  • CLI V9.7
  • ODBC
  • ISO CLI

An active connection to the server must exist before you issue the SQLCreateDb API.

Unicode equivalent: The corresponding Unicode function is the SQLCreateDbW() function. For information about ANSI to Unicode function mappings, refer to Unicode functions (CLI).

Syntax

SQLRETURN   SQL_API_FN SQLCreateDb ( SQLHDBC                hDbc,
                                     SQLCHAR                *szDbName,
                                     SQLINTEGER             cbDbName,
                                     SQLCHAR                *szCodeSet,
                                     SQLINTEGER             cbCodeSet,
                                     SQLCHAR                *szMode,
                                     SQLINTEGER             cbMode);

Function arguments

Table 1. SQLCreateDb arguments
Data type Argument Use Description
SQLHDBC hDbc input Connection handle.
SQLCHAR * szDbName input Name of the database that is to be created.
SQLINTEGER cbDbName input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of the function) that is needed to store the szDbName argument or to store SQL_NTS if the szDbName argument is null terminated.
SQLCHAR * szCodeSet input Database code set information.
Note: If the value of the szCodeSetargument is NULL, the database is created in the Unicode code page for a Db2® data server and in the UTF-8 code page for an Informix database server.
SQLINTEGER cbCodeSet input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of the function) that is needed to store the szCodeSet argument or to store SQL_NTS if szCodeSet argument is null terminated.
SQLCHAR * szMode input Database logging mode.
Note: This value is applicable only to an Informix database server.
SQLINTEGER cbMode input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of the function) that is needed to store the szMode argument or to store SQL_NTS if szMode argument is null terminated.

Usage

When creating a Db2 database, CLI application must first connect to the server instance by specifying the ATTACH keyword. The valid APIs, after connecting to the server instance using ATTACH keyword are SQLCreateDb(), SQLDropDb(), and SQLDisconnect(). Before performing other CLI operations on the new database, you must disconnect from the server instance and then connect to the new database.

Return codes

  • SQL_SUCCESS
  • SQL_ERROR

Diagnostics

Table 2. SQLCreateDb SQLSTATEs
SQLSTATE Description Explanation
08003 Connection is closed. The connection that was specified for the SQLCreateDb argument was not open.
HY090 Invalid string or buffer length. The cbDbName, cbCodeSet, and cbMode arguments have a maximum length of 128. If you specify an invalid value, CLI generates an error.

Restrictions

  • A connection representing an instance attachment is required.
  • The SQLCreateDb() function is not supported for Db2 for IBM i and Db2 for z/OS servers.
.

Examples

The following example creates Db2 databases on a local server:
  sqldriverconnect 1 0 "attach=true" -3 50 SQL_DRIVER_NOPROMPT
  sqlcreatedb 1 sample1 8 null 0 null 0
  sqlcreatedb 1 sample2 8 null 0 null 0
The following example creates Db2 databases on a remote server:
  sqldriverconnect 1 0  "attach=true;hostname=myhostname;port=9999;
   uid=myuid;pwd=mypwd;protocol=tcpip" -3 50 SQL_DRIVER_NOPROMPT
  sqlcreatedb 1 sample1 8 null 0 null 0
  sqlcreatedb 1 sample2 8 null 0 null 0

Version information

Last update
This topic was last updated for IBM® Db2 Version 9.7, Fix Pack 3.
IBM Data Server Client
Supported in IBM Db2