Before you begin
This configuration procedure is required only if you need to connect to a remote IBM® Workload Scheduler (IWS, previously known as TWS) controller address space that is running on another LPAR in your sysplex or in a remove z/OS® instance.
About this task
IBM AD Connect for Mainframe can be configured to use the IWS program interface (PIF) that runs under the TCP/IP server for retrieving the information of applications and jobs from a remote IWS. The information refers to the IWS-defined applications, jobs, and their dependencies.
Procedure
-
Ensure that the remote IWS controller is running. See the following checklist:
- The IWS TCP/IP server is configured and active.
- The IWS TCP/IP server is used for end-to-end processing. It communicates between the controller and the end-to-end domains. The IBM AD Connect for Mainframe server tasks use TCP/IP to handle communication to a remove IWS controller. Therefore, your z/OS systems must have the IWS TCP/IP server configured and active.
- See the following sample JCL statements for starting the IWS TCP/IP server address
space:
********************************* Top of Data *****************************
//TWC1S EXEC PGM=EQQSERVR,REGION=6M,TIME=1440
//EQQMLIB DD DISP=SHR,DSN=TWS.V8R2M0.SEQQMSG0
//EQQMLOG DD SYSOUT=*
//EQQPARM DD DISP=SHR,DSN=EQQUSER.TWS01.PARM(SERP)
//SYSMDUMP DD SYSOUT=*
//EQQDUMP DD SYSOUT=*
//*
See
the following configuration parameters that are referenced by the IWS TCP/IP server address space.
The TCPIPJOBNAME, HOSTNAME, and
SRVPORTNUMBER parameters must be set for your
site./*********************************************************************/
/* SERVOPTS: run-time options for SERVER KER processor */
/********************************************************************/
SERVOPTS SUBSYS(OPCC)
/*------------------------------------------------------------------------------------------------------------*/
/* If you want to use Automatic Restart manager you must specify: */
/* ARM(YES) */
/*---------------------------------------------------------------------------------------------------------- -*/
/* TCPOPTS : TCP/IP communications - local definition $CMDA */
/*---------------------------------------------------------------------------------------------------------- -*/
TCPOPTS TCPIPJOBNAME('TCPIP') == > TCPIP STACK NAME
HOSTNAME(9.30.114.131) ==> Host IP Address
SRVPORTNUMBER(350) ==> Server port Number
/* CONNTIMEOUT(15) */
/* SSLLEVEL(FORCE) */
/* SSLKEYSTORE('wrkdir/ssl/TWS.kdb') */
/* SSLKEYSTOREPSW('wrkdir/ssl/TWS.sth') */
/* SSLAUTHMODE(STRING) */
/* SSLAUTHSTRING('MYSTRING') */
/* CALENDAR parameter is mandatory for server when using TCP/IP */
/* server. */
/*---------------------------------------------------------------------------------------------------------*/
INIT CALENDAR(DEFAULT)
- For detailed customization of the TCP/IP server, see IBM Z® Workload Scheduler Customization and Tuning.
- The IBM AD Connect for Mainframe user ID is defined to the security server of the remote LPAR where the IWS controller is running.
- The user ID must remain the same. If the remote IWS controller is on another LPAR in the same sysplex and RACF® sysplex data sharing is enabled, this user ID does not need to be defined again. The default group that the IBM AD Connect for Mainframe user ID is defined to must also be present on the remote LPAR. After the user ID is defined on the remote system, it must be given read access to the following resources:
- The OPCC resource in the APPL class
- If the APPL class is not set up, see chapter
Implementing security
in IBM Z Workload Scheduler Customization and Tuning. The following example shows how to grant user ID IAYV5108 read access. You can replace the user ID with the one that is assigned to IBM AD Connect for Mainframe at your site.PERMIT OPCC ID(IAYV5108) ACCESS(READ) CLASS(APPL)
- The IWS fixed resource AD
- IBM AD Connect for Mainframe uses the AD resource of the IWS controller to retrieve job and application details. The IWS fixed resource that is named AD is coincidental and not related to IBM AD Connect for Mainframe.
- If security is in place for restricted access to the resources, you must provide read access to the AD fixed resource. The AUTHDEF statement controls how IWS resource security is handled. The following example shows how to grant IBM AD Connect for Mainframe user ID IAYV5108 read access. IBMOPC is the IWS class that is defined in the AUTHDEF statement of the controller.
RDEFINE IBMOPC AD UACC(NONE)
PERMIT AD ID(IAYV5108) ACCESS(READ) CLASS(IBMOPC)
SETROPTS RACLIST(IBMOPC) REFRESH
- For setup of the default scheduler class IBMOPC and more details on the AUTHDEF statement or
scheduler resources, see IBM Z Workload Scheduler Customization and Tuning.
- APF authorize the IWS load-module library, or define the library in the linklist.
IBM AD Connect for Mainframe requires the IWS library to be present on the LPAR as it users PIF modules to make the connection to the remote TCP/IP server. If you add the library to the IBM AD Connect for Mainframe started task JCL STEPLIB, you can APF authorize the IWS library. Update the active APF member (IEAAPFnn or PROGnn) to authorize the
library.
If you don't want to add the IWS library to the IBM AD Connect for Mainframe started task JCL STEPLIB and APF authorize the IWS library, you can define the library in the linklist.
- Configure local OPCC.
For local OPCC configuration, the IBM AD Connect for Mainframe started task JCL needs the following DD statements:
//EQQMLIB DD DISP=SHR,DSN=TWS951.SEQQMSG0
- This line can be changed if the IWS message library has a different name on your site. If a user
library is defined for IWS messages, this user library can be placed first in the EQQMLIB DDname
concatenation, and the two libraries names might be concatenated.
//EQQDUMP DD DISP=SHR,DSN=IAY.USER.TWS.EQQDUMP
- The EQQDUMP DDname refers to an IWS dump data set that is created to capture IWS dump. This data
set must be created with record format VBA, record length 84, and block size 3120. 10 primary tracks
are sufficient, but you might allocate more.
//EQQMLGnn DD DISP=SHR,DSN=IAY.USER.TWS.MLOG.TASKnn
-
Creates MAXTASK data sets named AY.USER.TWS.MLOG.TASKnn as sequential files
with record format VBA, record length 125, and block size 1632. nn goes from 01
to the number of tasks that are specified in MAXTASK. 10 primary tracks are sufficient.
- Configure remote OPCC.
For remote OPCC configuration, the IBM AD Connect for Mainframe started task JCL needs two additional DD statements: EQQYPARM and EQQMLOG.
//EQQYPARM DD DISP=SHR,DSN=IAY.AD.PARMLIB(PIFPARM) : -
- The PDS or sequential file for the EQQYPARM DDname can be a member of a partitioned data set or
a sequential file. This line represents the EQQYPARM statement required for the remote connection
with the SERVER task that is running on the remote machine.
- The EQQYPARM statement contains an initialization statement: INIT. The INIT statement overrides
the values that are set by the INTFORTS statement in the EQQYPARM statement. The most important
settings are SUBSYS, REMHOSTNAME, REMPORTNUMBER, and DUBPROC. See the following EQQYPARM
sample:
/*********************************************************************/
/* INIT STATEMENT FOR PIF PROGRAMS (EQQYPARM DD) */
/*********************************************************************/
INIT CALENDAR(DEFAULT)
OIWSNAME(IGNORE)
SUBSYS(OPCC) /*Remote TWS controller Subsystem name*/
TRACE(0) CWBASE(00) HIGHDATE(711231)
REMHOSTNAME(9.30.114.131) /* Remote MAINFRAME IP STACK */ REMPORTNUMBER(350) /* PORTNUMBER IN SERVOPTS on remote LPAR */ DUBPROC(Y) /*should not be changed or deleted for AD connect for MF*/
// EQQMLOG DD SYSOUT=*
- The EQQMLOG DDname is the message log data set, and it must be defined in the IBM AD Connect for Mainframe started task.
- The message log data set can be written to SYSOUT or a data set. The data control block (DCB)
for this data set is defined by IWS as
follows:
EQQMLOG Dataset DCB attributes (RECFM=VBA,LRECL=125,BLKSIZE=1632)
Example
The following example shows the IBM AD Connect for Mainframe procedure JCL setup for an IWS remote connection.//IAYV5107 PROC RVER=IAYV5108,
//* BVER=IAYV510,
//* TVER=IAYV5108,
// PGMNAME=IAYLISPR,
// CONNNAME=IAYCONN,
// TCPAS=TCPIP, --> TCP/IP ADDRESS SPACE NAME
// PORT=05108, --> TCP/IP PORT NUMBER
// HOSTCP=00037, --> HOST CODE PAGE (CCSID)
// CLNTCP=00850, --> CLIENT CODE PAGE (CCSID)
// MAXTK=5, --> MAX TASK FOR THIS RUN
// RXI=N,
// DEB=L --> DEBUG MODE THIS RUN (Y/N/L/S/T)
//LISTEN EXEC PGM=&PGMNAME,REGION=0M,
// PARM='&TCPAS,&PORT,&MAXTK,&CONNNAME,&DEB,&HOSTCP,&CLNTCP,N,&RXI'
//STEPLIB DD DISP=SHR,DSN=&RVER..LOADLIB
//* -- TWS APF LOAD LIB BELOW
// DD DISP=SHR,DSN=TWS.V9R5M0.SEQQLMD0 ==> Workload Scheduler LOADLIB
//IAYINTR DD SYSOUT=(*,INTRDR)
//IAYINT01 DD SYSOUT=(*,INTRDR)
//IAYINT02 DD SYSOUT=(*,INTRDR)
//IAYINT03 DD SYSOUT=(*,INTRDR)
//IAYINT04 DD SYSOUT=(*,INTRDR)
//IAYINT05 DD SYSOUT=(*,INTRDR)
//* <-- IAY INTERNAL OUTPUT DDS
//CPEOUT DD SYSOUT=*
//IAYOUT DD SYSOUT=*
//IAYERR DD SYSOUT=*
//CPEOUTRS DD SYSOUT=*
//CPEOUTRQ DD SYSOUT=*
//CPESNAP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//* <-- IAY INTERNAL REXX INTEGRATION DD
//SYSEXEC DD DISP=SHR,DSN=&RVER..SAMPLIB
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD DUMMY,BLKSIZE=80
//SAMPLJCL DD DISP=SHR,DSN=&RVER..SAMPLIB
//IAYIRXPC DD DISP=SHR,DSN=&RVER..SAMPLIB(IAYINI00)
//***TWS
//EQQYPARM DD DISP=SHR,DSN=IAYV510.AD.PARMLIB(PIFPARM) ==> Parameter
//* file for remote connection
//EQQMLIB DD DISP=SHR,DSN=TWS.V9R5M0.SEQQMSG0 ==> Workload
//* Scheduler MSGLIB
//EQQDUMP DD SYSOUT=*
//EQQMLOG DD SYSOUT=* ==> EQQMLOG is mandatory
//EQQMLG01 DD DISP=SHR,DSN=IAYV5108.TWS.MLOG.TASK01
//EQQMLG02 DD DISP=SHR,DSN=IAYV5108.TWS.MLOG.TASK02
//EQQMLG03 DD DISP=SHR,DSN=IAYV5108.TWS.MLOG.TASK03
//EQQMLG04 DD DISP=SHR,DSN=IAYV5108.TWS.MLOG.TASK04
//EQQMLG05 DD DISP=SHR,DSN=IAYV5108.TWS.MLOG.TASK05