Chapter 29 Database Connection Related Statements - FWD - Golden Code Redmine

Database Connection Related Statements

Before explaining the various database related statements, it is important to understand how FWD manages the physical databases. In 4GL, the physical database name is a location on disk, where the database files reside. In FWD, the physical database name is the name of a permanent database configured in the directory of a FWD server. To understand the configuration settings of a permanent database, please see the FWD Runtime Installation, Configuration and Administration Guide.

If the converted 4GL programs use this statement to connect to a database with a different name than the default schema name, hints may be used to register this new database name, so that the preprocessor part of the conversion will not fail. Please see the Code Preparation chapter and the Conversion Hints chapter of the FWD Conversion Handbook for details on how these hints may be used.

Finally, note that all database related statements are converted to API calls in the src.com.goldencode.p2j.persist.ConnectionManager class.

CONNECT¶

The CONNECT statement is used to create a logical connection to a database using the specified parameters. In FWD terms, the parameters will specify a FWD server which is authoritative for the database you want to use. The syntax of this statement is:

CONNECT { { pdb-name | VALUE ( expression ) } [ options ] | options } [ NO-ERROR ]

where pdb-name or VALUE(expression) represents the name of o a physical database, in 4GL terms. The options parameter represent a connection string in 4GL terms which can be used to specify the logical database name or details about the host on which the FWD server authoritative for the physical database is running. The options parameter can be either a list of the following options or a character expression which gets evaluated to a string with the following syntax:

[ -db ] pdb-name { [ -ld ] ldb-name [ [ -H ] host [ -S ] { port-number | service-name } ] }

Although 4GL provides a larger set of parameters than the above, note that FWD supports only the these optional parameters. See the following table for details about them:

Value	Details
`-db pdb-name`	Specifies the physical database name in 4GL terms. The `-db` key is not required, but the `pdb-name` value is required. If no host and port number/service name is provided, then the physical database name is the name of a permanent database registered with the current FWD server.
`-ld ldb-name`	Specifies an optional logical database name. The `-ld` key is required only if the host is provided too.
`-H host`	Specifies an optional host name or IP address. If the host is specified, the `-H` key is required.
`-S { port-number \| service-name }`	Specifies the port number or service name used to connect to a FWD server running on the specified host. If the host is specified, then it is required to specify either the port or service name; the `-S` key is optional in this case.

When converting this statement, it will always result in a call to the ConnectionManager.connect(...) API. This API takes a variable number of parameters, depending on which and how the above options are used. Following are examples which demonstrate how the CONNECT statement is converted:

Example 1:

...
connect p2j_test.
...

Converted code:

...
ConnectionManager.connect(“p2j_test”);
...

Details:

This is the simples version of the CONNECT statement. It creates a connection to the p2j_test database on the local FWD server. Note that the database name is passed as a string constant. In this example, the logical database name will be the same as the physical database name.

Example 2:

...
connect p2j_test -ld test.
...

Converted code:

...
ConnectionManager.connect(“p2j_test”, “-ld”, “test”);
...

Details:

This examples creates a connection to the local p2j_test database, using the test logical database name. Note how the options are passed as string constants to the ConnectionManager.connect call.

Example 3:

def var ldb-name as char init “test”.
...
connect p2j_test -ld value(ldb-name).
...

Converted code:

...
ConnectionManager.connect(“p2j_test”, “-ld”, (ldbName).toStringMessage());
...

Details:

Here the logical database name is passed using the ldb-name variable. When an option is provided in this format, both the key and its value are converted to distinct parameters. Note that the toStringMessage() is used to retrieve the content of the ldbName variable using the MESSAGE compatible format.

Example 4:

def var ldb-name as char init “test”.
...
connect p2j_test -ld value(ldb-name) -H localhost -S 3333.
...

Converted code:

...
ConnectionManager.connect(“p2j_test”, “-ld”, (ldbName).toStringMessage(), “-H”, “localhost”, “-S”, 3333);
...

Details:

When the database is on a different FWD server, the -H and -S options are used to specify the address of the FWD server. All options except the logical database name are converted as string constants passed to the ConnectionManager.connect call. Note that the key and the value for a certain option are converted as separate parameters.

Example 5:

...
connect “-db p2j_test -ld test -H localhost -S 3333” no-error.
...

Converted code:

...
ErrorManager.silentErrorEnable();
ConnectionManager.connect(“-db p2j_test -ld test -H localhost -S 3333”);
ErrorManager.silentErrorDisable();
...

Details:

In this example, the options are given as a “connection string”. This will result in a single parameter passed to the ConnectionManager.connect call, which will parse it and identify the given options. Also, as the NO-ERROR clause was specified, the ConnectionManager.connect call is bracketed by calls so that the silent error mode is enabled during execution.

DISCONNECT¶

This statement requests a disconnect from a logical database previously connected using the CONNECT statement. This does not actually perform the disconnect immediately, but registers ldb-name for disconnect at the appropriate time: once no buffers reference the database, and at the end of the current transaction (if any). Its syntax is:

DISCONNECT { ldb-name | VALUE ( expression ) } [ NO-ERROR ]

where ldb-name represents the logical name of a database, connected or not; the logical database name can also be passed using the VALUE(expression) clause. In case the specified database has not bee opened, it will generated an ERROR event, unless the NO-ERROR clause is used. Following are some examples which show how this statement gets converted:

Example 1:

...
disconnect p2j_test.
...

Converted code:

...
ConnectionManager.disconnect(“p2j_test”);
...

Details:

Here, logical database name is passed as a string constant to the ConnectionManager.disconnect call.

Example 2:

def var ldb-name as char init “p2j_test”.
...
disconnect value(ldb-name) no-error.
...

Converted code:

...
ErrorManager.silentErrorEnable();
ConnectionManager.disconnect((ldbName).toStringMessage());
ErrorManager.silentErrorDisable();
...

Details:

This example introduces the NO-ERROR clause, which brackets the ConnectionManager.disconnect call with calls that enabled the silent error mode. The db variable uses the toStringMessage call to format its internal value using the MESSAGE compatible format.

CREATE ALIAS¶

In 4GL, this statement is used to create an alias for a logical database name. The created alias may not conflict with an existing logical database name (except for that of the database which it aliases). The alias will be created regardless of whether the target database currently is connected; however, an error will be raised (or silently registered) in the event it is not, after the alias has been created. The alias persists until explicitly deleted, or until the current session ends. The syntax of this statement is:

CREATE ALIAS alias | VALUE ( expression )
   FOR DATABASE ldb-name | VALUE ( expression )
   [ NO-ERROR ]

where the alias is a character constant (quoted or not) or an expression, using the VALUE(expression) clause. The ldb-name represents the logical name of a database, connected or not; the logical database name can also be passed using the VALUE(expression) clause after the FOR DATABASE clause.

When converting this statement, it will result in a call to the ConnectionManager.createAlias(String, String) method. The first parameter will hold the alias name and the second parameter will hold the logical database name. Please see the following examples to understand how this statement gets converted:

Example 1:

...
create alias test for database p2j_test.
...

Converted code:

...
ConnectionManager.createAlias(“test”, “p2j_test”);
...

Details:

Here, the two parameter - the alias and the logical database name - are passed as string constants to the ConnectionManager.createAlias call.

Example 2:

def var l as char init “test”.
def var ldb-name as char init “p2j_test”.
...
create alias value(l) for database value(ldb-name) no-error.
...

Converted code:

...
ErrorManager.silentErrorEnable();
ConnectionManager.createAlias((l).toStringMessage(), (ldbName).toStringMessage());
ErrorManager.silentErrorDisable();
...

Details:

This example introduces the NO-ERROR clause, which brackets the ConnectionManager.createAlias call with calls that enable the silent error mode. The l and db variables use the toStringMessage call to format their internal value using the MESSAGE compatible format.

DELETE ALIAS¶

This statement is used to delete an alias previously created with the CREATE ALIAS statement; if the alias doesn't exist, no error is generated. Its syntax is:

DELETE ALIAS { alias | VALUE ( expression ) }

where alias can be a quoted or unquoted string and VALUE(expression) is any expression which will be evaluated to an alias.

On conversion, this statement will be converted to a ConnectionManager.deleteAlias(String) call. Following are some examples which show how this statement gets converted:

Example 1:

...
delete alias test.
...

Converted code:

...
ConnectionManager.deleteAlias(“test”);
...

Details:

In this example, the alias is passed as a string constant to the ConnectionManager.deleteAlias call.

Example 2:

def var l as char init “test”.
...
delete alias value(l).
...

Converted code:

...
ConnectionManager.deleteAlias((l).toStringMessage());
...

Details:

Here, a variable is used to pass the alias to the statement; note that the toStringMessage call creates a string representation of the data in a form that is compatible with the MESSAGE language statement.

Project

General

Profile

FWD

Wiki

CONNECT¶

DISCONNECT¶

CREATE ALIAS¶

DELETE ALIAS¶

Project

General

Profile

FWD

Wiki

Database Connection Related Statements¶

CONNECT¶

DISCONNECT¶

CREATE ALIAS¶

DELETE ALIAS¶