Start of change

Installing JDBC Gateway

The JDBC Gateway is a IBM Data Virtualization Manager for z/OS distributed application server that allows direct connectivity to JDBC data sources. Install the JDBC Gateway to connect directly to JDBC data sources.

Before you begin

Before installing the JDBC Gateway, review the following points:
  • For an overview of the JDBC Gateway solution, see Using JDBC Gateway.
  • The following terminology is used in the installation procedure:
    • JDBC Gateway server. The server is the backend component that allows communication with the IBM Data Virtualization Manager for z/OS server.
    • JDBC Gateway administrative console. The administrative console is the front-end web component that you use to configure your data sources. Only a single user (web client) can access the JDBC Gateway administrative console at a time. When installing the JDBC Gateway, you must specify a specific user ID for this purpose. This user ID is an internal application ID that allows access to the web user interface.
    • Port for the Web UI. This port will be used to access the Web-based administrative console and is specified during the installation procedure.
      Note: The JDBC Gateway also uses another port to listen for incoming DRDA requests. This DRDA listener port is set later when configuring the JDBC Gateway.
  • Before installing the JDBC Gateway, verify that all installation requirements are met, as follows:
    System component Requirement
    Permissions You have appropriate user logon credentials and user privileges on your client system to install the JDBC Gateway. For example, to install and deploy the JDBC Gateway on Windows, you may need to run with administrator privileges depending on the target location.
    Supported platforms The JDBC Gateway is a pure Java application and therefore can be deployed on any platform that supports Java 8 or higher.
    System memory Minimum of 1 GB
    Hard disk space Minimum of 500 MB
    Software
    • Java 8 is required to install and deploy JDBC Gateway.
    • One of the following web browsers (with JavaScript support enabled) must be used to access the JDBC Gateway administrative console:
      • Google Chrome browser V50.0.2661.102 or later
      • Mozilla Firefox V47.0.1 or later
      • Microsoft Edge V25.10586.0.0 or later
      • Microsoft Internet Explorer V10 or later
      • Apple Safari browser V9.0.3 or later
    • Database connectivity requires an appropriate JDBC driver for each type of data source that is accessed.

About this task

Use the following procedure to install the JDBC Gateway. This installation installs the JDBC Gateway server and administrative console.

During the installation, you must specify a user ID to be used for the JDBC Gateway administrative console. When using the JDBC Gateway administrative console, only a single user can access the administrative console at a time.

As part of the installation, the following actions occur:
  • The jgate.properties file is created, which contains the site-specific settings.
  • Start and stop scripts appropriate to the platform are created. The installer creates cmd scripts if you are running on Windows and sh scripts if you are running on Unix or Linux.
Considerations for USS installation: For installation in USS, it is recommended that you define the following environment variables:
export IBM_JAVA_OPTIONS="-Dfile.encoding=ISO8859-1"
export _BPXK_AUTOCVT=ON
When the installer generates start and stop scripts, the following actions occur depending on these variables:
  • If you have not set the recommended environment variables, the scripts will be generated in EBCDIC. You can run the gateway as normal for Unix using the following command: sh startServer.sh
  • If you set the IBM_JAVA_OPTIONS variable, the scripts will be generated in ASCII, and you will need to use the following command: chtag -tc ISO8859-1 <file>. (Tagging in USS basically means _BPXK_AUTOCVT must be ON if you want to edit or execute the script in the shell.)

Files generated by the JDBC Gateway, such as log files and the jgate.properties file, will be generated in ASCII regardless of the aforementioned environment variable settings (except for jetty.out, which is in EBCDIC). In order to browse these files natively in USS, you must use the chtag command and set _BPXK_AUTOCVT=ON.

Procedure

  1. Go to IBM Fix Central page - https://www.ibm.com/support/fixcentral/.
  2. Under Find Product section, in the Product Selector list, select IBM Data Virtualization Manager for z/OS, and then press Enter.
  3. In the Installed Version list, select a required version number.
  4. In the Platform list, select All and then click Continue.
    The Identify fixes page is displayed.
  5. Click Browse for Fixes option, enter the value for the selected option and then click Continue.
  6. Select JDBC Gateway and then click dvm-jdbc-gateway-<version>.zip file to download.
  7. On your host machine, create a directory to host the JDBC Gateway, and then extract the contents of the installation file into that directory.
    The extracted contents will include the JDBCGatewaySetup11.jar file.
    Note: If your host machine does not have an unzip utility, extract the contents of the installation file on a Windows workstation and copy the JDBCGatewaySetup11.jar file to the host machine.
  8. At a command prompt in the directory, run the following command: 
    java -jar JDBCGatewaySetup11.jar
    The installer launches.
  9. Enter the following information at the prompts:
    Prompt Description
    You are about to install JDBC Gateway. Do you want to proceed? (Y/n) Enter Y to continue with the installation, or enter n to cancel the installation.
    Specify the application data directory: Enter the path of the directory for Application Data, or press Enter to use the default value as indicated. The default value-

    for windows: C:\Users\abcuser

    for USS: /u/abcuser
    Specify the installation directory (local directory\JDBCGateway): Enter the path of the directory where to install the application, or press Enter to use the default value as indicated.
    Set login for JDBC Gateway admin Web page (admin): Enter the user ID to be used for the JDBC Gateway administrative console, or press Enter to use the default value admin.
    Set password for JDBC Gateway admin Web page: Enter the password for the administrative console user ID. The password must be at least five characters in length.
    Confirm your password: Re-enter the password for the administrative console user ID.
    Set port for the Web UI (8080): Enter the number of an available TCP/IP port for the application, or press Enter to use the default value 8080. This port number will be used when launching the JDBC Gateway administrative console.
    Installation completed. Do you want to start the JDBC Gateway now? (Y/n) Enter Y to start the server, or enter n to exit the installation.
    Note: If you enter Y, the server starts within the same shell.

Results

The JDBC Gateway has been installed and is ready for use. Information about the activity of the JDBC Gateway is available in the Java Console and in the log files.

If you specified to start the server, information about the startup process is displayed.

What to do next

See Using JDBC Gateway.
End of change