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

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.

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.

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.

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)