CONNECT statement

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

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 " + SECURITY-POLICY:ENCODE-PASSWORD(cPasswd,"ae2h6")
  -H dbserver -S 1900 NO-ERROR.

Note also that this fragment encodes the password value (cPasswd) using an Encoding prefix. For more information, see the ENCODE-PASSWORD( ) method.

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

• The user identity set for a database connection determines:
  • If and how the user has permission to access tables and fields in the connected database
  • The tenant organization through which the user access a multi-tenant database
  • The audit identity used to record audit policy events during the connection process
• OpenEdge authenticates any user identity that you specify for the CONNECT statement using the local database domain registry, even if the database option is set to use the application (session) domain registry.
• To authenticate the user identity specified for a database connection:
  • The user's security domain must be defined in the OpenEdge database.
  • The domain must be authentication-enabled:
    1. The user's domain must be enabled in the database.
    2. The user's domain must be configured with an authentication system that supports OpenEdge-performed user authentication. For the CONNECT statement (but not the startup command line), this can include a domain configured with a user-defined authentication system that has an ABL authentication plugin enabled.
    3. The configured authentication system must have access to a source of valid user accounts.
  • The user credentials specified by the -U and -P parameters must match a user account accessible through the authentication system configured for the user's domain.

  For information on OpenEdge support for domains and domain configuration, see Introduction to Identity Management.

• The user authentication operation of the CONNECT statement can fail for any one of the following reasons, among others:
  • The User ID (-U) connection parameter includes an invalid format.
  • The user ID's account is not found in the domain.
  • The domain is not defined.
  • The domain is not enabled.
  • The Password (-P) value specified for the user account is invalid.
  • The domain is configured for single sign-on (SSO) operations only.
  • The authentication system returns an error for any other reason.
• For the connection identity set with the CONNECT statement, OpenEdge creates a sealed security token containing the user credentials for the database connection, which you can return as a client-principal object using the GET-DB-CLIENT function. This client-principal is created even if OpenEdge connects the database with a default connection identity (that is, you do not specify -U and -P). However, for a default connection identity, OpenEdge does not seal the client-principal using the access code configured for a registered domain. Instead, OpenEdge creates a unique internal access code to seal the object. As a result, you cannot use the sealed client-principal object to assign the default user identity it represents to any OpenEdge database connection or ABL session.
• Each connected database is assigned a logical name for the current session, and is referred to by this logical name during the session. Use the Logical Database Name (-ld) parameter to specify a logical name. If the logical name is not specified using the -ld parameter, then the physical database filename, without the .db suffix, is the default logical name. For example, if the physical name is /users/eastcoast/proapp/mydb.db, then the default logical name is mydb. Logical names are not case sensitive.
• Databases can have aliases (see also ALIAS function). A database can have more than one alias, but each alias refers to only one database. The first database connected during a given session automatically receives the alias DICTDB. The first database connected that has a _menu file automatically receives the alias FTDB. You can reassign the FTDB alias to any other FAST TRACK database.
• When you try to connect the same database twice using the same logical name, the AVM returns a warning, which you can suppress with NO-ERROR.
• When you try to connect different databases using the same logical name, the AVM returns an error message and an error condition. You can suppress the error condition with NO-ERROR, and test with the CONNECTED function.
• When you try to connect to multiple databases and a connection fails, a run-time error occurs. The successfully connected databases remain connected and program execution continues. Use the CONNECTED function to find out which databases are successfully connected.
• If you run a procedure that requires a database and that database is not connected, the AVM searches for the database in the auto-connect lists in all connected databases. If the AVM finds the required database there, it automatically attempts to connect to the database with the parameters set for it in the auto-connect list. You can edit the auto-connect list using the database utilities in the OpenEdge Data Dictionary. If the AVM does not find it, the connection attempt fails.
• Connection information found in an OpenEdge auto-connect list is merged with connection information in a CONNECT statement that connects the database. So, if you connect a database with a CONNECT statement, and that database already has an entry in the OpenEdge auto-connect list of a connected database, the connection information in the auto-connect list and the CONNECT statement is merged. However, the connection information in the CONNECT statement takes precedence.
• Permission issues limit the use of the CONNECT statement for raw I/O connections to databases in single-user and multi-user direct-access mode on UNIX machines that do not support O_SYNC and SWRITE.

  The ABL client executable might require use of a privileged account that allows it to open raw disk devices or large databases. Thus, you can open any databases specified on the startup command line with raw I/O. Note that after startup on Unix, the client executable relinquishes the privileges that allow it to open raw disk devices. As a result, you cannot use the CONNECT statement to establish a raw I/O connection to a database in single-user or multi-user direct-access mode.

  When you try to use a CONNECT statement to open a raw I/O connection to a database in single-user mode, the AVM establishes a buffered (non-raw) I/O connection to the database and displays a non-raw warning message.

• When you try to use a CONNECT statement to open a raw I/O connection to a database in multi-user direct-access mode, one of the following events occur:
  • If you started a server (PROSERVE) for the database with the Buffered I/O (-r) parameter, the AVM establishes a non-raw I/O connection to the database.
  • If you started a server (PROSERVE) for the database with the Raw I/O (-R) parameter, the CONNECT statement fails.

  There are several ways to avoid these problems:

  • Establish raw I/O database connections in the single-user and multi-user direct-access modes at ABL startup.
  • If you must use the CONNECT statement to establish a raw I/O database connection, establish the connection with the Client Multi-user (-cl) parameter. Be sure to start the database server (PROSERVE) with the Raw I/O (-R) parameter before you do this.
  • If you must use the CONNECT statement to establish a raw I/O database connection in single-user or multi-user direct access mode on UNIX, follow these steps carefully:
    1. Change the permissions of the ABL client executable to rwsrwsr-x by typing chmod 6775 _progres.
    2. Change the group of the client executable to match the group of the raw device (for example, /dev/rsd0d) and block special device (for example, /dev/sd0d).
    3. Change the permissions of the raw and block special devices to "rw-rw----".

    The disadvantage of this procedure is that all files produced within OpenEdge have the same group as the disk device. Consider the following:

  • If you want to run a multi-user direct-access session in non-raw mode, you must start the database server with the Buffered I/O (-r) parameter.
  • If a database and accompanying before-image file have read-only permissions (r--r--r--) and you try to connect to that database in single-user or multi-user mode using the CONNECT statement, the connection will fail with the following error:

    errno=13

    This connection failure results because the _progres module relinquishes superuser privileges after startup and no longer possesses the privileges required to connect to the database using the CONNECT statement.

• This statement does not attempt set the connection identity for the foreign data source of a DataServer connection. However, it does attempt to set the connection identity for the OpenEdge schema holder database.
• For more information on connecting to databases from ABL, see OpenEdge Programming Interfaces.

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