Installing Z Data Tools Service Provider on z/OS®

The Service Provider feature is extracted to UNIX System Services, 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 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 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	Z Data Tools Base component 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

Extract the Z Data Tools Service Provider for z/OS® Connect archive from the SHFMSAM1 data set using the UNIX System Services pax command.
```
pax -rf "//'<hlq>.SHFMSAM1(HFMZCEE)'"
```
This command extracts the HFMZCEE archive into the current working directory.
(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 is installed. The directory must be fully qualified. That is, it must begin with a forward slash (/). The default installation directory is /var/zdatatools. If you elect to change the default directory, it is recommended that you choose one that does not already contain existing files or sub-directories. The productInstall directory is created if it does not already exist.
Copy the properties file to the z/OS® Connect <WLP_USER_DIR>/v3r0/extensions directory using the UNIX System Services cp command.
For example:
```
cp zdatatools.properties /var/zosconnect/v3r0/extensions
```
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.
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.
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 is 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.
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
	…
/*
```
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.

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, …
```
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.