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.
- 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.
- 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
- Allocate a PDS(E) data set with fixed block and LRECL=80 to contain the skeleton JCL member, or select an existing JCL library.
- 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.
- Set up the JOB card information to conform to the site standards.
- 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.
- 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.
- 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).
- 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.
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. - 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.
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. - 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.
- 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.
- 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
- Add the following DDNAMES to the IBM AD Connect for
Mainframe started
task procedure as follows.
- 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.
- 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.
- 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.
Restart the IBM AD Connect for Mainframe started task
- Make sure that the task starts normally, and no JCL errors that are related to the new data set allocations occur.
- 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.Verify that the debug trace is on by checking the following message in CPEOUT.
- Run a test to retrieve Endevor source from the IBM AD Build Client.
- 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.
- The AD build client should receive the Endevor source as normal.
- Optionally turn off the debug trace to avoid filling the spool. Replace EZLQA1SR with the name
of your AD started task.Verify that the debug trace is off by checking the following message in CPEOUT.
Troubleshoot if the procedure fails
- 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.
- Check any B37 errors that are caused from insufficient data set space allocation, and adjust the data set space allocation.
- 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.
- 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.
- 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.