Next/Previous Next/Previous

CONNECT statement

Establishes a connection to one or more databases from within an ABL procedure or class.

Note: OpenEdge identifies all connected databases for access within an external procedure or class at the start of execution for each compilation unit. Therefore, you cannot directly connect a database using this statement and directly access tables in the database from within the same external procedure or class. Instead, you can directly connect the database in one procedure or class, and from this one call another external subprocedure, or instantiate another class, that accesses the database tables.

Syntax

CONNECT
  {
    { physical-name | VALUE ( expression ) } [ options ] |options
  }
  [ NO-ERROR ]
physical-name
The actual name of the database on disk. It can be a simple filename, relative pathname, or a fully qualified pathname, represented as an unquoted string, or a quoted string. If you do not give a fully qualified pathname, the AVM searches for the database relative to your current working directory. The database name is restricted to alphanumeric characters. Diacritical marks and the symbols \ " ' * ; | ? [ ] ( ) ! { } < > @ + = : ~ are not permitted.
VALUE ( expression )
A character expression (a quoted string, field name, variable name, or similar expression) whose value starts with the Physical Database Name (-db) connection parameter followed by zero or more of the same client connection parameters that you can specify in options.
options
One or more client connection parameters (unquoted), similar to those used to start OpenEdge. Valid options are a subset of OpenEdge startup parameters that include all client database connection parameters. If you specify options without physical-name or VALUE (expression), the first database connection parameter must be the Physical Database Name (-db) parameter. The specification of the User ID (-U) parameter (and Password (-P) parameter, if required), determines the user identity for the connection, and its tenancy (if the database is multi-tenant). Note that these (and all connection) parameters are case sensitive.
If you need to use an argument with the special characters (diacritical marks and the symbols \ " ' * ; | ? [ ] ( ) ! { } < > @ + = : ~), the argument must be quoted for the AVM to handle it properly. The following code shows one way to apply this for a password, vpasswd, that may contain special characters:
connString = "-db test -U " + vUser + " -P " + QUOTER(vpasswd).

CONNECT VALUE(connString)
Caution:
If you do not specify -U and -P, for backward compatibility, OpenEdge attempts to connect the database with a default connection identity. This default connection identity can be set using either the blank ("") user ID or the user ID of the operating system process in which the AVM is running. The user ID set for the default connection identity depends on the domain configuration in the database. For more information on connecting with a default identity, see the User ID (-U) parameter description in Startup Command and Parameter Reference. For more information on the effects of connecting a database with a default identity, see the Notes of this statement entry.

For more information on all database client connection parameters, see Startup Command and Parameter Reference.

NO-ERROR
The NO-ERROR option is used to prevent the statement from raising ERROR and displaying error messages.

For the CONNECT statement with NO-ERROR, the option does not suppress all errors produced by the server; only errors caused by the CONNECT statement itself. For example, if the server to which you are connecting runs out of resources, its error message will not be suppressed. If a CONNECT error occurs (for example, the database does not exist or is in use in single-user mode), error information is written to the ERROR-STATUS system handle.

Examples

This procedure attempts to connect to databases mydb1 and mydb2 in single-user mode, with error suppression. You must connect to a database before you run a procedure that references it.

r-connct.p 

CONNECT mydb1 -1 -db mydb2 -1 NO-ERROR.

The following four code fragments attempt exactly the same database connection to the Sports2020 database:

CONNECT C:\OpenEdge\WRK\db\Sports2020 -H dbserver -S 1900 NO-ERROR.
 
CONNECT -db C:\OpenEdge\WRK\db\Sports2020 -H dbserver -S 1900
 NO-ERROR.
 
CONNECT VALUE("-db C:\OpenEdge\WRK\db\Sports2020 -H dbserver
   -S 1900")
 NO-ERROR.
 
CONNECT VALUE("-db C:\OpenEdge\WRK\db\Sports2020 -H dbserver")
   -S 1900
  NO-ERROR.

The following procedure fragment shows how you can use the VALUE option to specify a user ID (cUserID) and password (cPasswd) that a user might enter in response to a prompt to authenticate the same database connection:

DEFINE INPUT PARAMETER cUserID AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER cPasswd AS CHARACTER NO-UNDO.

CONNECT C:\OpenEdge\WRK\db\Sports2020 
  VALUE( "-U " + cUserID +
        " -P " + "oech1::" + AUDIT-POLICY:ENCRYPT-AUDIT-MAC-KEY(cPasswd))
  -H dbserver -S 1900 NO-ERROR.

Note also that this fragment encrypts the password value (cPasswd) and concatenates it with a prefix in a form that OpenEdge expects for encrypted passwords. For more information, see the ENCRYPT-AUDIT-MAC-KEY( ) method reference entry.

In the next example, assume database Sports2020 has not been previously connected, so the following r-cnct1.p procedure fails. At the start of execution, r-cnct1.p checks whether Sports2020 is connected. If Sports2020 is not connected, a run-time error occurs. As shown in the example, attempting to connect to Sports2020 within the procedure does not solve the problem:

r-cnct1.p 

/* NOTE: this code does NOT work */

CONNECT Sports2020 -1.
FOR EACH Sports2020.Customer NO-LOCK:
  DISPLAY Customer.
END.

Instead, split r-cnct1.p into two procedures, as shown in r-dispcu.p and r-cnct2.p:

r-dispcu.p 

FOR EACH Sports2020.Customer NO-LOCK:
  DISPLAY Customer.
END.

r-cnct2.p 

CONNECT Sports2020 -1.
RUN r-dispcu.p.

This time, database Sports2020 is connected before r-dispcu.p is invoked, so r-dispcu.p runs successfully.

The next example shows how to use the alternate database connection set parameters (-dbalt1, -dbalt2, -retryConnect, and -retryConnectPause) to specify alternate databases to try connect to, in the event that the connection to the primary database fails. Notice how outer double quotes are used to enclose the entire string and inner single quotes are used around the -dbalt1 and -dbalt2 arguments. You may also reverse them and use single quotes for the outer connection string and double quotes for the inner parameter values. 

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

Notes

See also

ALIAS function, CONNECTED function, CREATE ALIAS statement, CREATE CALL statement, DATASERVERS function, DBCODEPAGE function, DBCOLLATION function, DBRESTRICTIONS function, DBTYPE function, DBVERSION function, DELETE ALIAS statement, DISCONNECT statement, FRAME-DB function, LDBNAME function, NO-ERROR option, NUM-DBS function, PDBNAME function, SDBNAME function, SET-DB-CLIENT function, SETUSERID function

Next/Previous Next/Previous
Footer_Beta
© 2019 Progress Software Corporation and/or one of its subsidiaries or affiliates. All rights reserved.