Enabling TCP/IP Connection to a Remote IWS Controller Address Space

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.

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.

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)
```

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