Troubleshooting

Use this information to troubleshoot File Manager API request failures.

Check the API response

APIs where possible return an error text in the HTTP response body. This is often the best place to begin when diagnosing an API failure. APIs also generate an HTTP status code, which may provide additional information.

Check that the z/OS Connect WLP server is running

An inability to connect to the z/OS Connect WLP server may indicate that the server is not running. Check that the server is running on your target z/OS system.

Check the port numbers in z/OS Connect WLP server.xml

If you are unable to connect to your z/OS Connect WLP server when it is running, you can verify that you are using the correct port number by viewing the server.xml.

By default, z/OS Connect creates the WLP server in /var/zosconnect and the server.xml can be found in the subdirectory with the name of your server. For example: 

/var/zosconnect/servers/<yourServer>/server.xml

The port numbers are found in the <httpEndpoint> stanza. For example:

<httpEndpoint id="defaultHttpEndpoint"
                  host="*"
                  httpPort="9099"
                  httpsPort="9043" />

Check that the API URL matches the deployed z/OS Connect API

When creating an API using the z/OS Connect API Editor, the API creator chooses the base path and API path. The URL of the resulting API should have the following structure:
https://<your.server>:<port><base.path><API.path>
Figure 1. Specifying a base path and API path in the z/OS Connect API Editor
Specifying a base path and API path

In this example shown in Figure 1, the URL should look similar to the following:

https://<your.server>:<port>/fmapi/data/MY.FILENAME/MY.TEMPLATE(TMPL)

Check that the URL you are using is correct.

Check that the z/OS Connect API has been deployed

When an API has been created using the z/OS Connect API Editor, it must be deployed to the z/OS Connect host system before it is available. APIs can be deployed directly from the z/OS Connect Eclipse environment. Available APIs are listed in the z/OS Connect WLP JOBLOG when an API is deployed, or when the server is started.

Check that your API is listed as installed by looking for either of the following messages in the z/OS Connect WLP JOBLOG:

BAQR7000I: z/OS Connect API package API.name installed successfully.

BAQR7034I: z/OS Connect API package API.name updated successfully.

Check that the File Manager Service Provider is installed

Installation involves running the WLP installUtility command to install the File Manager Service Provider as a WLP feature. Verify that the feature has been installed by confirming that the following message appears in the z/OS Connect WLP server JOBLOG:

CWWKF0012I: The server installed the following features: 
[…filemanager:fmProvider-2.0…]

Installation of the File Manager Service Provider for z/OS Connect is documented in the File Manager Customization Guide.

Check the HTTP API request headers

All File Manager Service Provider requests require an HTTP Content-Type header in the following form:

Content-Type: application/json

For single or initial requests to read a data resource, the caller must also provide an HTTP Basic Authorization header in the following form:

Authorization : Basic credentials_string

where credentials_string represents a Base64 encoding of userid:password for the target z/OS system.

Check that the z/OS Connect WLP server is accessible

Issue the following z/OS Connect REST API command:

https://<your.server>:<port>/zosConnect/services

This API will return a list all the services available on the server. If the File Manager service fmService is listed, your z/OS Connect WLP server is accessible.

Check that the ADFzCC server is running

The ADFz Common Components (ADFz Common Components) server is used to start or connect to File Manager sessions when an API request is issued. Therefore, the ADFzCC server must be running for the File Manager Service Provider to do its work. In addition, the ADFzCC server must be configured to run on the port specified in the <FileManager_Connection> stanza in the z/OS Connect WLP server.xml. For example:

<FileManager_Connection id="default" runport="2800" max_timeout="1800" />

Look for the following message in the ADFzCC server JOBLOG to confirm that the server’s port number matches the port number specified in the server.xml:

IPV0015I ADFzCC server
Running on port <port_number>.

Check the z/OS Connect WLP JOBLOG for messages

Error messages related to a problem with an API or service provider might be logged in the z/OS Connect WLP JOBLOG. Check for messages related to your problem.

Check the z/OS Connect WLP trace and message logs

By default, WLP writes log and trace messages to the server’s logs directory, for example:

/var/zosconnect/servers/<yourserver>/logs

Check the trace.log and messages.log files in this directory for messages related to your problem.