Enabling tracing for the z/OS jobs REST interface

For diagnostic purposes, your installation might be asked by IBM® Support to enable tracing for the z/OS® jobs REST interface. This topic provides instructions for enabling several commonly-used traces.

Your installation can trace the use of the z/OS jobs REST interface on the z/OSMF system. Also, you can trace a variety of JES related activities, which can result from the use of the z/OS jobs REST interface services.

Understand that tracing carries a performance cost. Do not activate tracing for z/OSMF unless directed to do so by IBM Support.

Tracing the z/OS jobs REST interface services

To trace the use of z/OS jobs REST interface services on the z/OSMF system, use the MODIFY command with the LOGGING option. Your user ID must be permitted to enter this operator command.

The command has the following format: 
f server-name,logging='com.ibm.zoszmf.restjobs.*=all'
where:
server-name
Is the server for your z/OSMF configuration. Set this value to the job name of the z/OSMF server, which is IZUSVR1, by default.
com.ibm.zoszmf.restjobs.*=all
Is the trace specification for the z/OS jobs REST interface.

Enter the command from the operator console. The command output is displayed in the operator console and in the z/OS system log.

Your changes take effect immediately and remain in effect while the server is running. Your changes are discarded when the server is restarted, and the previous settings are used.

To end this level of tracing and revert to the previous setting, enter the command again, and specify "reset" as the trace specification, for example:

f izusvr1,logging='reset'

Tracing the JES related activities for your programs

For callers of the z/OS jobs REST interface, your installation can trace the JES related activities that can occur on behalf of program requests.

Specifically, you can trace the following JES related activities:
  • Usage of the following subsystem interface (SSI) function codes:
    • Extended status function call (SSI function code 80), which allows a user-supplied program to obtain detailed status information about jobs and SYSOUT in the JES queue
    • Modify job function call (SSI function code 85), which allows a user-supplied program to modify job properties and to manage memory associated with the request.
  • VSAM related activities.
  • JES symbolic parameter substitutions.
  • HSM recall activities.

To capture this type of information, you must add the appropriate trace specifications to the z/OSMF bootstrap.template file, which ensures that the server is started with the proper traces enabled. z/OSMF writes the trace output to files in the z/OSMF logs directory.

To start this type of tracing, do the following:
  1. Locate the z/OSMF bootstrap.template file. By default, the location is: /etc/zosmf/servers/zosmfServers/bootstrap.template
  2. Save a copy of the existing bootstrap.template file as a back-up.
  3. Edit the bootstrap.template file, as needed:
    • Add the property zosjes.logging=t to capture information about the following activities:
      • Usage of the extended status function call (SSI function code 80)
      • VSAM related activities.
    • Add the property izurestjobs.logging=t to capture information about the following activities:
      • Usage of the modify job function call (SSI function code 85)
      • JES symbolic parameter substitutions
      • HSM recall activities.
    A portion of the file is shown in Figure 1.
    Figure 1. Bootstrap properties for z/OSMF

    # Licensed Materials - Property of IBM
    #
    # "Restricted Materials of IBM"
    #
    # Copyright IBM Corp. 2013 All Rights Reserved.
    #
    # US Government Users Restricted Rights - Use, duplication or
    # disclosure restricted by GSA ADP Schedule Contract with
    # IBM Corp.
    #
    # -----------------------------------------------------------
    #

    izu.hostname=*
    izu.https.port=443

    # Trace options follow...
    zosjes.logging=t
    izurestjobs.logging=t

  4. Save the bootstrap.template file.
  5. Restart the z/OSMF server and resume z/OSMF operations.

Your changes will take effect immediately and are maintained across z/OSMF server restarts.

To work with the z/OSMF log files, you require a user ID with z/OSMF administrator authority (that is, a user ID defined to the z/OSMF administrator security group).

For information about how to enable other trace options for z/OSMF, and how to work with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.