Configure and Deploy the
JCLCheck
REST API

How to Configure and Deploy the
JCLCheck
REST API Service
cjwa12
After all prerequisite software is installed and running on the
JCLCheck
Server and Security Administrators configure the security application that is running on the
JCLCheck
server, Systems Administrators can configure and deploy the
JCLCheck
REST API. Optionally, you can configure the API to integrate with the Zowe™ API Mediation Layer.
Follow these steps:
  1. Address the prerequisite software that is described in
    Prerequisite Software for Configuring and Deploying the
    JCLCheck
    REST API
    .
  2. Ensure that a Security Administrator configured the security application that is running on the
    JCLCheck
    server where you want to deploy the
    JCLCheck
    REST API service. For more information, search
    Configure Security for the
    JCLCheck
    Server
    .
  3. From the location where you applied the maintenance PTF, copy the following members from the CAZ2JCL SMP/E target library to a library where you can customize them for your implementation:
    • AJ6ZJCKD:
      The procedure (PROC) contains the JCL that lets you deploy the
      JCLCheck
      REST API service to a desired location.
    • AJ6ZJCKR:
      The PROC contains the JCL that lets you run the service.
  4. Create and run a job for
    AJ6ZJCKD
    .
    When constructing a job to run this PROC, specify
    JOBRC=LASTRC
    in the job card. This specification indicates to use the return code of the last executed step as the completion code for the job.
    After you run the job, it performs the following actions:
    • Allocates and formats the zFS (
      CAI.JCLCHECK.ZFS
      or the value of ZFSDSN) when the zFS does not already exist.
    • Creates a directory named
      /cai/CASoftware/JCKR1
      .
      The name of the directory is determined by the value of the
      USSDIR
      variable in the
      AJ6ZJCKD
      PROC.
    • Mounts the zFS to that directory, if it is not already mounted.
    • Creates the directories named
      config
      and
      lib
      in the
      /cai/CASoftware/JCKR1
      directory that the PROC created.
    • Unpacks the
      JCLCheck
      JAR file and binaries into the
      /cai/CASoftware/JCKR1/lib
      directory.
    • Unpacks the file named
      jclcheck.yml
      into the
      /cai/CASoftware/JCKR1/config/jclcheck-samp.yml
      file.
    • Runs the command
      extattr +p
      on the SOs and on the binary
      caz1zsvr
      to grant Program Control to the objects.
    • Runs the command
      extattr +a
       on the binary
      caz1zsvr
      to grant APF Authorization.
    • Unpacks the members named
      AJ6ZCEE
      and
      AJ6ZENV
      into the data set named
      CAI.SAMP.CAZ2OPTN
      (or the value of the
      OPTDSN
      parm).
  5. Copy the file named
    /cai/CASoftware/JCKR1/config/jclcheck-samp.yml
    and rename it to
    jclcheck.yml
    .
  6. Edit the
    host
    and
    port
    number in the
    jclcheck.yml
    file as required for your environment. The host must be the IP address of the z/OS system on which the
    JCLCheck
    service will run. The port must be available on the system.
    The file is an ASCII format that is stored in USS and must be edited in ASCII mode.
  7. Enable a secure TLS/HTTPS connection. You must
    either
    manually configure HTTPS or choose to integrate the service with Zowe™ API Mediation Layer.
    The service will fail to start if you do not configure HTTPS using one of these methods.
    1. To manually configure HTTPS, perform the following steps:
      This process generates a KeyStore with self-signed certificates. You might have your own process for generating certificates at your site.
      1. From a USS command line, issue the following command to navigate to the
        JCLCheck
        REST API configuration directory:
        cd /cai/CASoftware/JCKR1/config
      2. Issue the following command and follow the prompts to generate the KeyStore in
        pkcs12
        format:
        $JAVA_HOME/bin/keytool -genkey -alias jclcheck -keyalg RSA -keystore keystore.p12 -storetype pkcs12
      3. Update the following properties in the
        /cai/CASoftware/JCKR1/config/jclcheck.yml
        configuration file:
        server: ssl: enabled: true keyAlias: jclcheck keyPassword: password keyStore: config/keystore.p12 keyStorePassword: password keyStoreType: PKCS12 jclcheck: maxPoolSize: 4 queueCapacity: 100
        • keyAlias
          The same value that you entered for the -alias option on the keytool command when you created the KeyStore in the previous step.
        • keyPassword
          The password that you entered when you created the KeyStore in the previous step.
        • keyStorePassword
          The password that you entered when you created the KeyStore in the previous step.
        • maxPoolSize
          (Optional) Lets you define how many jobs the service can run concurrently, which helps limit load on the system. The value can be any integer starting at 1. If you omit this option, the default value of 4 is used.
        • queueCapacity
          (Optional) Lets you configure how many jobs the API can store in the queue (pending execution) before jobs are dropped. The value of this option can be any integer, starting at the value that you define for
          maxPoolSize
          . If you omit this option, the default value of 100 is used. Jobs submissions that exceed the limit will be dropped.
    2. To optionally integrate the service with Zowe API Mediation Layer, refer to
      Integrate REST API with the API Mediation Layer
      .
  8. Copy the data set named
    HLQ.SAMP.CAZ2OPTN
    and rename it to
    HLQ.CAZ2OPTN
    .
  9. Edit the variables that are defined in the
    AJ6ZENV
    member of the
    HLQ.CAZ2OPTN
    data set as required and necessary for your environment.
  10. Create and run a job for
    AJ6ZJCKR
    .
    1. Edit the variables that are defined in the PROC (
      AJ6ZJCKR
      ) as required and necessary for your environment.
    2. Start the
      AJ6ZJCKR
      PROC.
    The job launches the
    JCLCheck
    REST API service on the host and port that you specified in the file named
    jclcheck.yml
    . The service might take a few minutes to start. The job must continue to run to maintain the REST service. If the job is terminated, the service stops running.
  11. (Optional)
    Verify that the REST service is running. You can access the endpoint in a web browser at the URL
    <host>:<port>/api/v1/status
    . The host and port to use is the same z/OS system host and port that you configured in Step 6. If the service does not start, analyze the output logs and correct any errors that display.