CONNECT statement

Allows access to one or more databases from within an ABL procedure.

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.

VALUE ( expression )

An expression (a constant, field name, variable name, or other expression) whose value is a character string starting with the Physical Database Name (-db) startup parameter and followed by zero or more of the same client startup parameters that you can specify in options.

options

One or more client startup parameters, 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) startup parameter. Note that these parameters are case sensitive.

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

NO-ERROR

Suppresses ABL errors or error messages that would otherwise occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement is not done and execution continues with the next statement. If the statement fails, any persistent side-effects of the statement are backed out. If the statement includes an expression that contains other executable elements, like methods, the work performed by these elements may or may not be done, depending on the order the AVM resolves the expression elements and the occurrence of the error.

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.

To check for errors after a statement that uses the NO-ERROR option:

Check the ERROR-STATUS:ERROR attribute to see if the AVM raised the ERROR condition.

Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than zero to see if the AVM generated error messages. ABL handle methods used in a block without a CATCH end block treat errors as warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR attribute, but do add messages to the ERROR-STATUS system handle. Therefore, this test is the better test for code using handle methods without CATCH end blocks. ABL handle methods used in a block with a CATCH end block raise ERROR and add messages to the error object generated by the AVM. In this case, the AVM does not update the ERROR-STATUS system handle.

Use ERROR-STATUS:GET-MESSAGE( message-num ) to retrieve a particular message, where message-num is 1 for the first message.

If the statement does not include the NO-ERROR option, you can use a CATCH end block to handle errors raised by the statement.

Some other important usage notes on the NO-ERROR option:

NO-ERROR does not suppress errors that raise the STOP or QUIT condition.

A CATCH statement, which introduces a CATCH end block, is analogous to a NO-ERROR option in that it also suppresses errors, but it does so for an entire block of code. It is different in that the error messages are contained in a class-based error object (generated by the AVM or explicitly thrown), as opposed to the ERROR-STATUS system handle. Also, if errors raised in the block are not handled by a compatible CATCH block, ON ERROR phrase, or UNDO statement, then the error is not suppressed, but handled with the default error processing for that block type.

When a statement contains the NO-ERROR option and resides in a block with a CATCH end block, the NO-ERROR option takes precedence over the CATCH block. That is, an error raised on the statement with the NO-ERROR option will not be handled by a compatible CATCH end block. The error is redirected to the ERROR-STATUS system handle as normal.

If an error object is thrown to a statement that includes the NO-ERROR option, then the information and messages in the error object will be used to set the ERROR-STATUS system handle. This interoperability feature is important for those integrating code that uses the traditional NO-ERROR technique with the newer, structured error handling that features error objects and CATCH end blocks.

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 Sports2000 database:


CONNECT C:\OpenEdge\WRK\db\Sports2000 -H dbserver -S 1900 NO-ERROR.


CONNECT -db C:\OpenEdge\WRK\db\Sports2000 -H dbserver -S 1900 NO-ERROR.


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


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

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


/* NOTE: this code does NOT work */ CONNECT sports2000 -1. FOR EACH sports2000.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 sports2000.Customer NO-LOCK: DISPLAY Customer. END.

r-cnct2.p
CONNECT sports2000 -1. RUN r-dispcu.p.

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

Notes

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.

At startup, the ABL client executable has superuser privileges that allow it to open raw disk devices. Thus, you can open any databases specified on the startup command line with raw I/O. After startup, the client executable relinquishes the superuser 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:

Change the permissions of the ABL client executable to rwsrwsr-x by typing chmod 6775 _progres.

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).

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 start-up and no longer possesses the privileges required to connect to the database using the CONNECT statement.

For more information on connecting to databases, see OpenEdge Development: Programming Interfaces.