SQL Relay Version X1.9-3G for VSI OpenVMS IA-64 and x86-64 (Field Test)

Thank you for your interest in this port of the SQL Relay client API to VSI OpenVMS IA-64 and x86-64. The current release of the SQL Relay client API for OpenVMS is based on the SQL Relay 1.9.3 open-source distribution.

SQL Relay is an open-source database connection management solution that resides between your application and the database, providing functionality not typically provided by the database directly, including persistent database connection pooling, proxying, throttling, high availability, query routing, query filtering, query translation, and connection scheduling. Of particular interest from an OpenVMS perspective are the proxying capabilities of SQL Relay, which can be used to facilitate access to databases from unsupported platforms. Databases that can be accessed via SQL Relay using the client API include Oracle, Sybase, Microsoft SQL Server, IBM DB2, MySQL, MariaDB, PostgreSQL, Firebird, and SQLite, as well as ODBC data sources. For more information see http://sqlrelay.sourceforge.net/index.html.

This OpenVMS port of the SQL Relay client API includes all functionality provided by the open-source release, including SSL/TLS support (based on OpenSSL 3.0.5). Also included is a wrapper API that makes it easier to use the SQL Relay client API with OpenVMS programming languages other than C/C++, such as COBOL, FORTRAN, Pascal, and BASIC. Additionally, the kit provides several SQL Relay command line tools, including sqlrsh (an interactive tool similar to Oracle SQL*Plus), and sqlr-export and sqlr-import, which can be used to export and import data from XML files on a per-table basis. Additionally, this release includes a beta version of an embedded SQL pre-processor (PRESQLR.EXE) that can be used to port existing Oracle C and COBOL applications that use embedded SQL code to SQL Relay, in place of using the Oracle pre-processor tools and client API.?

VMS Software Inc. would like to acknowledge the work of David Muse and the Firstworks SQL Relay development team (http://www.firstworks.com/index.html) for their ongoing efforts in developing and supporting this open source software.

The X1.9-3G release of SQL Relay includes the following improvements and bug fixes to the ESQL2 component:

For a detailed description of the features and bug fixes included in this release, please refer to the ChangeLog file in the source repository (git://git.code.sf.net/p/sqlrelay/sqlrelay) and the version 1.9.3 release announcement (http://software.firstworks.com/2022/08/sql-relay-193-release-announcement.html).

The kit you are receiving has been compiled and built using the operating system and compiler versions listed below. While it is highly likely that you will have no problems installing and using the kit on systems running higher versions of the operating system or products listed, we cannot guarantee functionality if your system is running older versions.

Note that if you wish to statically link application code with the supplied SQL Relay object libraries and require SSL/TLS support, it will be necessary to link with a comparable OpenSSL distribution.

In addition to the above requirements, it is assumed that the reader has a good knowledge of OpenVMS and of software development in the OpenVMS environment.

It is recommended that developers and administrators read the extensive documentation provided on the SQL Relay web site (http://sqlrelay.sourceforge.net/documentation.html) and that developers carefully examine the provided sample programs before using the software.

The kit can be installed by a suitably privileged user via the following command:

$ PRODUCT INSTALL SQLRELAY

The installation will then proceed as follows (output may differ slightly from that shown, depending on platform and other factors):

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA80:[DEV.KITS]VSI-I64VMS-SQLRELAY-X0109-3G-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
    VSI I64VMS SQLRELAY X1.9-3G            Layered Product

Do you want to continue? [YES]

Configuration phase starting ...

You will be asked to choose options, if any, for each selected product and for
any products that may be installed to satisfy software dependency requirements.

Configuring VSI I64VMS SQLRELAY X1.9-3G

    VMS Software Inc.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
    VSI I64VMS SQLRELAY X1.9-3G            DISK$I64V842L1SYS:[VMS$COMMON.]

Portion done: 0%...10%...20%...30%...40%...50%...60%...70%...90%...100%

The following product has been installed:
    VSI I64VMS SQLRELAY X1.9-3G            Layered Product

VSI I64VMS SQLRELAY X1.9-3G

    Post-installation tasks are required.


    To enable SQLRelay at system boot time, add the following lines to
    SYS$MANAGER:SYSTARTUP_VMS.COM:

        $ file := SYS$STARTUP:SQLRELAY$STARTUP.COM
        $ if f$search("''file'") .nes. "" then @'file'

    To disable SQLRelay at system shutdown, add the following lines to
    SYS$MANAGER:SYSHUTDWN.COM:

        $ file := SYS$STARTUP:SQLRELAY$SHUTDOWN.COM
        $ if f$search("''file'") .nes. "" then @'file'
$

After the installation has successfully completed, include the commands displayed at the end of the installation procedure into SYSTARTUP_VMS.COM to ensure that the logical names required in order for developers to use the software are defined system-wide at start-up.

In addition to the logical name SQLR$ROOT (which points to the root directory of the SQL Relay client software installation), the logical names SQLR$SHR and SQLR$LIBESQL_SHR are also defined. The logical name SQLR$SHR points to the shareable image SQLR$SHR.EXE, located in SQLR$ROOT:[LIB], which can be linked with application code that uses the SQL Relay client API. Alternatively, it is possible to statically link application code with the object libraries found in the SQLR$ROOT:[LIB] directory. The logical name SQLR$LIBESQL_SHR points to the shareable image SQLR$ROOT:[LIB]SQLR$LIBESQL_SHR.EXE, which must be linked with application code containing embedded SQL statements that is built using the PRESQLR.EXE embedded SQL pre-processor.

Other logical names defined by the SQL Relay start-up script are as follows:

From a development perspective, for C/C++ programs it should be noted that symbols in the shareable image and object libraries are mixed-case, and developers should therefore use the C and C++ compiler option /NAMES=(AS_IS,SHORTENED) or include in their code appropriate #pragma directives (C only) to ensure that symbols are correctly resolved when linking. Developers will also need to include in their code the appropriate language header file, from SQLR$ROOT:[INCLUDE]. Symbols for the wrapper API that can be used with other OpenVMS programming languages are all upper-case.

Note that the C header file SQLR$ROOT:[INCLUDE.SQLRELAY]SQLR_WRAP_LIB.H must be included by C source code modules containing embedded SQL code that is pre-processed by the PRESQLR.EXE embedded SQL pre-processor.

Generally speaking there are no special quota or privilege requirements for applications developed using the SQL Relay client API, although a high BYTLM is recommended, and SYSPRV, BYPASS, or OPER privilege will be required if applications developed using the library need to utilise privileged ports (ports below 1024).

The following quotas should be more than adequate for most purposes:

Maxjobs:          0   Fillm:        256   Bytlm:      128000
Maxacctjobs:      0   Shrfillm:       0   Pbytlm:          0
Maxdetach:        0   BIOlm:        150   JTquota:      4096
Prclm:           50   DIOlm:        150   WSdef:        4096
Prio:             4   ASTlm:        300   WSquo:        8192
Queprio:          4   TQElm:        100   WSextent:    16384
CPU:         (none)   Enqlm:       4000   Pgflquo:    256000

The directory SQLR$ROOT:[EXAMPLES] contains several simple example programs written in C, COBOL, FORTRAN, BASIC, and Pascal that serve to illustrate the usage of the API. The command procedure SQLR$ROOT:[EXAMPLES]BUILD_EXAMPLES.COM can be used to build all of the example programs, and assumes that you have all of the relevant language compilers installed on the system in question. If this is not the case, it will be necessary to modify the command procedure to remove or comment out any language examples that you do not wish to build.

These simple example programs are intended to provide an introduction to the SQL Relay API and to hopefully serve as a basis for the development of more sophisticated applications. Note that it will be necessary to have available an appropriately configured SQL Relay server environment in order to run the example programs, and the example programs will need to be modified to specify the correct username, password, network address, and database connection details for your environment.

The directory SQLR$ROOT:[EXAMPLES.ESQL] contains a simple example build procedure that illustrates how to build applications using the PRESQLR.EXE embedded SQL pre-processor. The example build procedure illustrates some of the command line options that may be used with PRESQLR.EXE; in order to see the full list of parameters and options, run the pre-processor without specifying any parameters.

Note that it is mandatory to specify an input file using the /INAME qualifier. All other qualifiers are optional, and will default to the values shown, where appropriate.

The supplied kit for VSI OpenVMS includes all functionality supported by the open-source SQL Relay client API. In addition, the port includes a language-agnostic API that makes it straightforward to write applications using 3GL languages such as COBOL, FORTRAN, Pascal, and BASIC. This release of SQL Relay for VSI OpenVMS also includes a beta version of the PRESQLR.EXE embedded SQL pre-processor tool for COBOL and C.

The following list identifies any known issues and limitations associated with this release of SQL Relay for VSI OpenVMS:

Subsequent releases of the SQL Relay client for OpenVMS will include additional development tools and utilities, including embedded SQL processors for other programming languages and an enhanced interactive query tool. It is anticipated that the inclusion of these facilities and the scope of the functionality they provide will evolve over the course of several product releases.