Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## CONNECT statement

> Allows access to one or more databases from within a Progress 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, a quoted string, or a VALUE ( `expression` ). If you do not give a fully qualified pathname, Progress searches for the database relative to your current directory.

> `VALUE ( `expression` )`

> An expression (a constant, field name, variable name, or expression) whose value is a string representing the physical name of a database to connect.

> ``options``

> One or more options, similar to those used to start Progress. Valid options are a subset of OpenEdge startup parameters. Note that parameters are case sensitive.

> See OpenEdge Deployment: Startup Command and Parameter Reference for more information on OpenEdge startup parameters.

> `NO-ERROR`

> Suppresses errors in the act of connecting. This does not mean that all errors produced by the server are suppressed; 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.

> You also can use the CONNECTED function to determine whether the CONNECT succeeded and then retrieve error messages from the ERROR-STATUS 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.

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

>     /* NOTE: this code does NOT work */

>     CONNECT sports -1.
>     FOR EACH sports.customer:
>       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 sports.customer:
>         DISPLAY customer.
>     END.

> r-cnct2.p
>     CONNECT sports -1.
>     RUN "r-dispcu.p".

> This time, database `sports` 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, Progress returns a warning, which you can suppress with NO-ERROR.

> - When you try to connect different databases using the same logical name, Progress 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, OpenEdge searches for the database in the auto-connect lists in all connected databases. If OpenEdge 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 OpenEdge 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 OpenEdge 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, OpenEdge 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, OpenEdge 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 OpenEdge 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 OpenEdge 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 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 .

> #### 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, NUM-DBS function, PDBNAME function, SDBNAME function

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095