defineDatabaseAlias()

The sqlLib.defineDatabaseAlias() system function creates an alias that can be used to establish a new connection to a database to which your code is already connected. After you have established the alias, you can use it in any of these functions:

sqlLib.connect()
sqlLib.disconnect()
sqlLib.beginDatabaseTransaction()
sqlLib.setCurrentDatabase()

The function is valid only for Java™ generation.

Syntax

  sqlLib.defineDatabaseAlias(
    alias STRING in,
    database STRING in)

alias: A string literal or variable that acts as an alias of the connection identified in the second parameter. The alias is not case-sensitive.
database: A database name that was specified in sqlLib.connect(). Use a character literal or variable.

Examples

The following example shows how you can maintain two separate database connections by using the sqlLib.defineDatabaseAlias() function.

  // Connect to a database with alias "alias", 
  // which becomes the current connection.
  defineDatabaseAlias( "alias", "database" );
  connect( "alias", "user", "pwd" );

  // Make two connections to the same database.
  String db = "database";
  defineDatabaseAlias( "alias1", db );
  defineDatabaseAlias( "alias2", db );
  connect( "alias1", "user", "pwd" );
  connect( "alias2", "user", "pwd" );

  // Another way to make two connections 
  // to the same database.
  defineDatabaseAlias( "alias", "database" );
  connect( "alias", "user", "pwd" );
  connect( "database", "user", "pwd" );

  // An alias is defined but not used. The second 
  // connect() does not create a new connection.
  defineDatabaseAlias( "alias", "database" );
  connect( "database", "user", "pwd" );
  connect( "database", "user", "pwd" );

  // Use of an alias (which is case-insensitive)
  // when disconnecting.   
  defineDatabaseAlias( "alias", "database" );
  connect( "aLiAs", "user", "pwd" );
  disconnect( "ALIAS" );

  // The next disconnect call fails because the 
  // connection is named "alias" not "database".
  defineDatabaseAlias( "alias", "database" );
  connect( "alias", "user", "pwd" );
  disconnect( "database" );

  // An alias can change. After the next call, 
  // "alias" refers to "firstDatabase" 
  defineDatabaseAlias( "alias", "firstDatabase" );

  // After  the next call, 
  // "alias" refers to "secondDatabase".  
  defineDatabaseAlias( "alias", "secondDatabase" );

  // The last call would have failed 
  // if a connection were in place with "alias".

Compatibility

Table 1. Compatibility considerations for defineDatabaseAlias()
Platform	Issue
VisualAge® Generator compatibility	You can use the database alias in a vgLib.connectionService() call.