OpenEdge provides a mechanism for automatically connecting to an alternate database, if the connection to the primary database fails. This high-availability feature uses database connection parameters to specify alternates and can be used anywhere database connection parameters are allowed. The collection of primary and alternate databases, along with an optional retry count and pause interval, is known as a connection set. An alternate database is typically a replication target database, but it could also be a backup, or some other database. This feature is only available when using a client-server connection. It is not available for a single-user or a self-service (shared-memory) connection.

Note: If using this feature with OpenEdge replication, see Automatic database reconnection with OpenEdge replication for additional information.

To use this feature, you define a connection set consisting of the primary database and up to two alternate databases. You can also specify the number of times to retry the connection set and a pause interval for waiting in between. These connection options are implemented using parameters. The parameters can be defined as session startup parameters, in the CONNECT statement, or in a parameter file ( .pf ).

For a demo of this feature, see Automatic database reconnect demo and code.

Use database connection parameters to enable feature

The database connection parameters that can be used to enable this feature are: -dbalt1, -dbalt2, -retryConnect, -retryConnectPause and -autoReconnect. -dbalt1 and -dbalt2 are parameters that specify connection information (database name, host, and port) about the alternate databases. If you only have one alternate you need only use one of these parameters. -retryConnect specifies the number of retry attempts allowed for the connection set as a whole, before giving up. -retryConnectPause specifies the time to wait, in seconds, before retrying the connection set. -autoReconnect applies to GUI or character-mode clients and indicates that if an unhandled STOP condition occurs, you want to try reconnecting databases connected using startup parameters before rerunning the -p procedure. -autoReconnect is also used with OpenEdge replication, to automatically include the OpenEdge replication primary target database in the connection set. The syntax for each parameter is described below.

  • -dbalt1 — The first alternate database to attempt to connect to.

    -dbalt1 "dbname [-H hostname] -S port"

    If hostname is not specified, localhost is used. All arguments for -dbalt1 must be enclosed in quotes. -H and -S are the only arguments allowed.

  • -dbalt2 — The second alternate database to attempt to connect to.

    -dbalt2 "dbname [-H hostname] -S port"

    If hostname is not specified, localhost is used. All arguments for -dbalt2 must be enclosed in quotes. -H and -S are the only arguments allowed.

  • -retryConnect — The number of times to retry the connection set before giving up.

    -retryConnect retry-count

    All connections in the set (primary, -dbalt1, -dbalt2) are tried in turn before retrying the set. The default value for retry-count is 0. The maximum value is 100.

  • -retryConnectPause — The pause interval (in seconds) to wait before retrying the connection set.

    -retryConnectPause pause-interval

    All connections in the set (primary, -dbalt1, -dbalt2) are tried in turn before the pause occurs. The default pause-interval is 5 seconds. The maximum value you can set is 300 seconds.

  • -autoReconnect — For GUI or character-mode clients, indicates that if an unhandled STOP condition occurs, you want to try reconnecting databases connected using startup parameters before rerunning the startup procedure.

    -autoReconnect

    When running without -autoReconnect, the ABL session is reset and and the startup procedure is run, without attempting to reconnect to any databases that were specified at startup using startup parameters.

    -autoReconnect is also used with OpenEdge replication, to automatically include the OpenEdge replication primary target database in the connection set.

-ct (Connection Retry Attempts) is an independent, but related, startup parameter, which controls the number of connection retries for an individual database connection. The connection attempts are done in succession on the same database connection and have a default value of 50 attempts. This differs from -retryConnect, which applies to the connection set as a whole. If using both -ct and -retryConnect, you may want to set -ct to 0, or to a value lower than the default.

Database connection parameter considerations

  • Like other database startup parameters, -dbalt1, -dbalt2, -retryConnect, and -retryConnectPause apply only to the last database parameter (-db) encountered in the parameter list thus far.
  • You must specify the primary database first, before listing an alternate, otherwise the AVM issues an error.
  • If both -dbalt1 and -dbalt2 are specified and the connection to the primary database fails, -dbalt1 is tried first and -dbalt2 is tried second.
  • If you only specify -dbalt2, it becomes the first alternate.
  • If the AVM is unable to connect to any database the CONNECT statement goes through the usual error handling.
  • Any database parameters from the primary database, except for -H and -S, are also applied to the alternate databases, such as -ld, -U and -P.
  • The logical name of the alternate database is always taken from the primary database, even if not explicitly set with -ld.
  • If the same parameter is encountered more than once within the argument list for -dbalt1 or -dbalt2, the last one is used. This is consistent with the parsing rules for parameters in general.
  • If multiple -dbalt1 or -dbalt2 parameters are encountered within the parameter list for a particular primary database, the last one is used.

Example configurations

Example: Specify a primary database with one alternate:

-db mainDb -H PrimarySrvr -S 6999
-dbalt1 'altDb -H AltSrvr1 -S 7999' 
-retryConnect 3
In this example the AVM would:
  1. Try to connect to mainDb.
  2. If that fails, it would try to connect to altDb.
  3. If that fails, it would pause 5 seconds (default for -retryConnectPause) and repeat from step 1, three more times (because -retryConnect is 3).

Example: Specify a primary database with two alternates:

-db myDb -H PrimarySrvr -S 6999
-dbalt1 'myDbTarget1 -H AltSrvr1 -S 7999' 
-dbalt2 'myDbTarget2 -H AltSrvr2 -S 8999'
-retryConnect 10 -retryConnectPause 4

Example: Specify multiple primary databases with alternates:

-db myDb -H PrimarySrvr -S 6999
-dbalt1 'myDbTarget1 -H AltSrvr1 -S 7999' 
-dbalt2 'myDbTarget2 -H AltSrvr2 -S 8999'
-retryConnect 10 -retryConnectPause 4
-db otherDb -H OtherDbSrvr -S 3999
-dbalt1 'otherDbTarget1 -H AltOtherSrvr1 -S 4999' 
-dbalt2 'otherDbTarget2 -H AltOtherSrvr2 -S 5999'
-retryConnect 8 -retryConnectPause 3

Usage of parameters in the CONNECT statement

You may also use these database connection parameters in a CONNECT statement. For -dbalt1 and -dbalt2 each alternate database name, along with its host and port parameters, must be enclosed in quotes. In the following example, the arguments to -dbalt1 and -dbalt2 are surrounded by single quotes and the connection string is surrounded by double quotes. You can reverse this and use double quotes to surround the inner arguments and use single quotes for the outer connection string.

In the following example code, one alternate database is specified:

CONNECT -db myDb -H PrimarySrvr -S 6999 -dbalt1 'myDbBackup -H AltSrvr1 -S 7999'.

The following example code assigns the connection string to a CHARACTER variable. It uses single quotes to enclose the inner -dbalt1 parameters and double quotes for the outer string:

conn = "-db myDb -H PrimarySrvr -S 6999 -dbalt1 'myDbBackup -H AltSrvr1 -S 7999'".
CONNECT VALUE(conn).

The following example code specifies two alternate databases:

conn = "-db myDb -H PrimarySrvr -S 6999
  -dbalt1 'myDbBackup -H AltSrvr1 -S 7999' 
  -dbalt2 'myDbBackup -H AltSrvr2 -S 8999'
  -retryConnect 10 -retryConnectPause 4".
CONNECT VALUE(conn).

Automatic Database Reconnect with Progress Application Server (PAS) for OpenEdge sessions

The automatic restart behavior controlled by the -autoReconnect parameter does not apply to PAS for OpenEdge sessions. To achieve this behavior with a PAS for OpenEdge session, create a PAS for OpenEdge instance Activate procedure for connecting to the database. The following example code is an Activate procedure called dbconnect.p:

/* dbconnect.p */

IF NOT CONNECTED("sports2020") THEN
    CONNECT "-pf my.pf".

You set the Activate procedure in the openedge.properties file. For example:

sessionActivateProc=dbconnect.p

Enable logging for troubleshooting

The DB.Connects log entry type (-logentrytypes DB.Connects) turns on logging for database connections. (For information on configuring and enabling logging, see Logging infrastructure overview in Troubleshoot ABL Applications.) Normally, connect and disconnect messages are logged at the basic level (2 or higher). With this feature, additional messages are logged if the initial attempt to connect to the primary database fails. Consider the following connection string:

-db prim -H PrimarySrvr -S 1234 
-dbalt1 "alt1 -H AltSrvr1 -S 2345" 
-dbalt2 "alt2 -H AltSrvr2 -S 3456" 
-retryConnect 2 
-retryConnectPause 3
At logging level 2 or higher, when there is a successful connection to an alternate database, a message is logged indicating the connection is to an alternate:
CONN           Connected to alternate database alt2
At logging level 3 or higher, additional messages are logged showing the connection attempts:
CONN           Attempting to connect to database prim (primary)
CONN           Failed to connect to database prim
CONN           Failover: attempting to connect to database alt1 (-dbalt1)
CONN           Failed to connect to database alt1
CONN           Failover: attempting to connect to database alt2 (-dbalt2)
At logging level 3 or higher, an additional message showing the pause between connection attempts, is logged before the connection set as a whole is tried again. The pause length is controlled by the value set for -retryConnectPause.
CONN           Pausing 3 seconds between connection attempts
At logging level 3 or higher, if the session is restarted due to an unhandled STOP condition, for a GUI or character-mode client, and -autoReconnect is enabled, a message is logged:
CONN           Session restart: attempting to reconnect any disconnected databases

See also

Alternate Database 1 (-dbalt1)

Alternate Database 2 (-dbalt2)

Auto Reconnect (-autoReconnect)

Automatic database reconnection with OpenEdge replication

CONNECT statement

Connection Retry Attempts (-ct)

Database connection logging

Retry Connect Set (-retryConnect)

Retry Connect Set Pause (-retryConnectPause)