Installing Z Data Tools Service Provider on z/OS

The Z Data Tools Service Provider feature is extracted to USS, then installed into z/OS Connect within WLP, and then configured in ZCC server.

Before you begin

The installation procedure is conducted in the UNIX System Services (USS) environment and has the following environmental prerequisites:
  • The shell environment must have a z/OS® Connect EE-compatible version of Java™ available on the environment PATH variable. You can check the PATH variable by using the UNIX System Services (USS) echo $PATH command.
  • The z/OS Connect installation directory <ZCON_INST_DIR>/v3r0/wlp/bin must be in the PATH environment variable.

About this task

The Z Data Tools Service Provider for z/OS Connect feature is shipped as a binary archive in the SHFMSAM1 data set as member HFMZCEE. The archive contains the following files:

com.hcl.zosconnect.zdt.provider.feature_n.n.n.n.esa Feature archive
zdtService.sar Base service archive
zdtIMSService.sar IMS™ service archive
zdtDB2Service.sar Db2® service archive
zdatatools.properties Properties file
com.hcl.zosconnect.buildtoolkit.zdatatools.jar Build Toolkit plug-in

Procedure

  1. Extract the Z Data Tools Service Provider for z/OS Connect archive from the SHFMSAM1 data set using the USS pax command.
    pax -rf "//'<hlq>.SHFMSAM1(HFMZCEE)'"
    This command extracts the HFMZCEE archive into the current working directory.
  2. (Optional) Edit the productInstall option in the properties file if you want to change the installation directory.
    com.ibm.websphere.productInstall=</your/preferred/directory>
    This is the location where the Z Data Tools Service Provider will be installed. The directory must be fully qualified. That is, it must begin with a forward slash (/). The default installation directory is /var/zdatatools.
  3. Copy the properties file to the z/OS Connect <WLP_USER_DIR>/v3r0/extensions directory using the USS cp command. For example:
    cp zdatatools.properties /var/zosconnect/v3r0/extensions
  4. Copy the service archive files to the z/OS Connect service directory. For example:
    cp zdt*.sar 
       /var/zosconnect/servers/<yourWLPServer>/resources/zosconnect/services
    Ensure that the service archive files are readable by the z/OS Connect WLP started task user.
  5. Install the Z Data Tools Service Provider feature into z/OS Connect using the installUtility command. For example:
    installUtility install 
    com.hcl.zosconnect.zdt.provider.feature_2.0.0.0.esa --to=zdatatools
    Ensure that the ESA file version number matches the file name in the archive.
  6. Edit the z/OS Connect WLP server.xml configuration.

    The server.xml requires the following changes:

    1. Add the Z Data Tools feature to the featureManager stanza:
      <featureManager>
      	<feature>zdatatools:zdtProvider-2.0</feature>
      </featureManager>
    2. Add the runport and maximum timeout configuration for the feature:
      <ZDataTools_Connection id="default" runport="2800" max_timeout="1800" />
      where runport represents the ZCC server port that will be used to establish Z Data Tools sessions, and max_timeout represents the maximum number of seconds for which a client can hold a Z Data Tools session open without activity.
  7. Change the ZCC server JCL to support z/OS Connect REST requests. In the HFISRV CONFIG DD statement, add REST=YES after the CONFIG=ZDT stanza. For example:
    //CONFIG DD *
    	CONFIG=ZDT
    	REST=YES
    	…
    /*
  8. Restart or refresh the z/OS Connect WLP task and ZCC server task.

What to do next

To verify a successful installation of the Z Data Tools Service Provider, do the following steps.

  1. Check the JOBLOG of the z/OS Connect WLP started task and verify that the CWWKF0012I message lists zdtProvider-2.0 as one of the installed features. For example:
    CWWKF0012I: The server installed the following features: ssl-1.0, 
    jdbc-4.1, zdatatools:zdtProvider-2.0, …
  2. Invoke the Z Data Tools Service Provider manually, using an HTTP PUT request to https://zceehost:zceeport/zosConnect/services/zdtService?action=invoke with the following payload:
    {
        "action" : "verify"
    }

    This can be done from a browser or a REST API tool such as POSTMAN. The HTTP verb must be PUT or POST, and a Content-Type: application/json header is required. A HTTP status code of 200 indicates that the Z Data Tools Service Provider has been installed correctly.

If installation verification fails, check that all installation steps have been completed in the designated order. The Z Data Tools User’s Guide and Reference also provides a troubleshooting topic for the Z Data Tools Service Provider for z/OS Connect.