Configuring IIBM AD Connect for Mainframe to interface with CA-Endevor by using the Batch Interface

IBM® AD Connect for Mainframe uses the CA-Endevor API program ENA$NDVR to interface with CA-Endevor source management systems. When you retrieve a source with IBM AD Connect for Mainframe, some errors might be reported.

+BSTPOPSV: E001 MACRO $BGETSTG RC=008
+ENAPI000: F000 ABEND CODE=MACR NUMBER=3009
+CCSR010E C1SSESTA U3009 at 0094EF30 LMOD BSTPMOPS CSECT BSTPMPGM +000C80 ADDILIST N/A ADDILIST

To solve this problem, configure IBM AD Connect for Mainframe to interface with Endevor by a series of one or more batch jobs that are submitted to the internal reader rather than use a direct program call to the Endevor API.

Complete the SMP/E tasks

These tasks are not necessary if you run IBM AD 5.1.0 or later versions.

  1. Apply APAR PI99768 to your HALT503 SMP/E CSI. You can follow the installation instruction html file that is included in the .zip package for this APAR.
  2. Copy the changed load modules to the working authorized AD load library if the load modules are different from the SMP/E SIAYAUTH load library. The affected modules are IAYCONN and IAYNDVBT (new module).

Customize the Endevor Batch Job

To customize the Endevor batch job, complete the following steps:
  1. Allocate a PDS(E) data set with fixed block and LRECL=80 to contain the skeleton JCL member, or select an existing JCL library.
  2. Copy the sample job IAYENDVB from the AD Connect for Mainframe SIAYSAMP installation library to the JCL library. You might change the job name and member to conform to the naming conventions of your site. The copy of the member in SIAYSAMP for AD v6.1.2 is shown as follow.
    The sample job SIAYSAMP
  3. Set up the JOB card information to conform to the site standards.
  4. This job must run on the same LPAR as the IBM AD Connect for Mainframe started task. Adjust the job card as necessary by following your site standards to ensure that this requirement is met. Set the job class to automatically delete the job from the spool after the job completes. It is because numerous Endevor requests can correspondingly generate many job submissions. Ensure that your operations personnel are aware of the potential for an increased batch workload.
    Note: It is recommended to delay the automatic deletion of job output after the process is running smoothly and all bugs are resolved.
  5. Modify the PARM string on the NDVR job step only to enable or disable the debug flag as needed. The debug flag is the second character in the string PARM='YN0050000500'. In this case, the debug flag is set to N. To enable the debug flag, change it to Y.
  6. Set STEPLIB in the JCL to reference the AD Connect working load library that is originally SIAYAUTH, and the Endevor installation load libraries (unless they are link-listed).
  7. Set the Endevor Request Input Datasets. Allocate the MAXTASK number of identical input data sets for PARMDCB. MAXTASK is a keyword parameter in the AD Connect started task JCL that sets the maximum number of the parallel worker subtasks. These data sets will hold the Endevor request data that is sent by the AD started task. The data set name can be set to any valid name but must follow the convention that the last two bytes of the name ranges from digits 01 to MAXTASK. For example, if MAXTASK is set to 5, and the wanted data set name is EZLQA1.NDVRIN, the five data set names should be as follow.
    Endevor Request Input Datasets

    The data sets should be set to FB with LRECL=120. Since these data sets will hold the ENDEVOR requests, allocate one cylinder for the primary extent will provide enough space.

    Finally, set the PARMDCB data set name in the customized sample job (IAYENDVB) to the common part of the data set name, but replace the digits with %TK. This symbol will be replaced with the correct task number when AD Connect submits the job.
    Note: %TK must be the last nonspace character on the line.
    PARMDCB data set
  8. Set Endevor Reply Output Datasets. Allocate the MAXTASK identical data sets for CPEIMAGE. The data set name can be set to any valid name but must follow the convention that the last 2 bytes of the name ranges from digits 01 to MAXTASK. For example, if MAXTASK is set to 5, and the wanted data set name is EZLQA1.NDVROT, the five data set names should be as follow.
    Endevor Reply Output Datasets

    The data sets should be set to PS ORG, Variable (not blocked) with LRECL=32692. Since these data sets will hold the ENDEVOR reply data, the data sets need to be sized based on the expected amount of data to be returned. It is recommended to allocate 50 cylinders for primary storage. If you run into any B37 abends, you need to increase the size.

    Finally, set the CPEIMAGE data set name in the sample job to the data set name, but replace the digits with %TK. This symbol will be replaced with the task number when the agent task submits the job.
    Note: %TK must be the last nonspace character on the line.
    CPEIMAGE data set
  9. The APIEX001 and APIMS001 data sets are used by the Endevor API. An example of data set definition is shown as follow. If the job abends on B37 FOR APIEX001, increase space allocation as needed.
    APIEX and APIMS data sets
  10. In the POST step, set STEPLIB to reference to your AD Connect load library.
    Important: Make sure that the blank in-stream job card remains in place after the INDCB DD name. The agent will write the ECB address on this line, which allows the job to notify the AD started task when it is completed.
  11. Add comments where are needed, but make sure that the total job size does not exceed 64 lines.

Modify IBM AD Connect for Mainframe started task JCL.C

To modify IBM AD Connect for Mainframe started task JCL.C, complete the following steps:
  1. Add the following DDNAMES to the IBM AD Connect for Mainframe started task procedure as follows.
    1. Point NDVRJCL to the JCL PDS member that was set up in the previous section. Make sure that the DD name references the correct PDS and member name. And the AD started task must have READ access.
    2. Add the following pairs of DDNAMES, NDVRINxx and NDVROTxx.

      Where xx ranges from 01 to MAXTASK, and the MAXTASK is set to 5 at most sites. The NDVRINxx and NDVROTxx will reference the data sets that are allocated in steps 6 and 7 of the Customize the Endevor Batch Job.

      For example, When MAXTASK is set to 5, the JCL procedure is shown as follow after the modification.
      NDVRINxx and NDVROTxx data sets
  2. Add the following IAYINTxx DD names to reference the internal reader, one for each subtask is up to MAXTASK.
    For example, if MAXTASK is set to 5, the DD names are shown as follow.
    IAYINTxx data sets

Restart the IBM AD Connect for Mainframe started task

After modifying the IBM AD Connect for Mainframe started task JCL.C, restart the IBM AD Connect for Mainframe started task by completing the following steps:
  1. Make sure that the task starts normally, and no JCL errors that are related to the new data set allocations occur.
  2. Optionally turn on debug trace in case there are errors with the new configuration by using this modify command. Replace EZLQA1SR with the name of your AD started task.
    Turn on the debug trace
    Verify that the debug trace is on by checking the following message in CPEOUT.
    Verify the debug trace is on
  3. Run a test to retrieve Endevor source from the IBM AD Build Client.
  4. You can see that the Endevor job is submitted and ended with CC=0 for both steps. You might have to temporarily adjust the job class to retain the job on the spool for verification.
  5. The AD build client should receive the Endevor source as normal.
  6. Optionally turn off the debug trace to avoid filling the spool. Replace EZLQA1SR with the name of your AD started task.
    Turn off the debug trace
    Verify that the debug trace is off by checking the following message in CPEOUT.
    Verify the debug trace is off

Troubleshoot if the procedure fails

If the procedure fails, troubleshoot the problem by completing the following steps:
  1. Check the batch job to make sure that both steps are completed with condition code = 0. If the batch job fails, check that the CPEIMAGE and PARMDCB data set names have been substituted with a subtask number between 01 and MAXTASK. Make sure that these data sets exist and are also referenced in the AD started task proc JCL. PARMDCB contains the Endevor requests, and CPEIMAGE contains the Endevor reply data.
  2. Check any B37 errors that are caused from insufficient data set space allocation, and adjust the data set space allocation.
  3. Check the errors in the AD started task job log. Optionally turn on the debug trace that is described in step 6 in the Restart the IBM AD Connect for Mainframe started task, and check IAYOUT for trace messages.
  4. Make sure that the batch job was run on the same z/OS LPAR as the AD Connect started task. This is necessary for the batch job POST step to notify the IBM AD Connect for Mainframe that the job is competed.
  5. If the procedure still fails, send the entire AD agent job log, the Endevor batch job, and other details that might be helpful to IBM support.