3 Connector Deployment on the Mainframe

You deploy the Reconciliation Agent and Provisioning Agent on the mainframe. These agents communicate with the LDAP Gateway during connector operations.

The following section summarizes the procedure to deploy the Reconciliation Agent and Provisioning Agent:

• Section 3.1, "Summary of the Deployment Procedure"

The following sections describe each deployment step in detail:

• Section 3.2, "Reviewing Deployment Requirements"

• Section 3.3, "Deploying the Reconciliation Agent and Provisioning Agent"

• Section 3.4, "Configuring the Started Tasks"

• Section 3.5, "Installing the Reconciliation Agent Exits"

• Section 3.6, "Creating LIDs for the Reconciliation Agent and Provisioning Agent STCs"

• Section 3.7, "Starting Up and Shutting Down the Reconciliation Agent and Provisioning Agent"

• Section 3.8, "Pioneer Control File"

• Section 3.9, "Pioneer Post-Processing"

• Section 3.10, "Pioneer/Voyager Operator Commands"

3.1 Summary of the Deployment Procedure

The following steps summarize the procedure to deploy the connector components on the target system:

1. Review and address the deployment requirements.

2. Deploy the Reconciliation Agent and Provisioning Agent.

3. Configure the started tasks.

4. Install the Reconciliation Agent exits.

5. Create LIDs for the Reconciliation Agent and Provisioning Agent STCs.

6. Test the setup by starting up and shutting down the Reconciliation Agent and Provisioning Agent.

Note:

In addition to the procedures described in this chapter, see Section 5.4, "Configuring the Connector for Provisioning to Multiple Installations of the Target System" if you want to configure the connector to work with multiple LPARs on the IBM z/OS system.

3.2 Reviewing Deployment Requirements

The following is a summary of the deployment requirements:

• The STCs for the Reconciliation Agent and Provisioning Agent must each have a LID associated with it. See Section 3.6, "Creating LIDs for the Reconciliation Agent and Provisioning Agent STCs" for more information.

• The Reconciliation agent uses memory subpools to manage peak-load conditions. The subpool (231) can be configured to use 200 KB to 1000 K of mainframe memory for storing CA ACF2 events.

• The subpool is located in the CSA above the 16 M byte line, you configure this subpool while installing the Reconciliation Agent. The procedure is described in Section 3.3, "Deploying the Reconciliation Agent and Provisioning Agent."

• Because TCP/IP is used in the message transport layer, the administrator performing the procedures described in this chapter must have authorization to create security profiles.

• The Reconciliation Agent operates by using exit technology, within the IBM z/OS operating system environment. Command execution is captured by an exit, just before full completion of the native mainframe command. If the exit fails, then the command fails and returns an error message. Maintaining a specific password format is an example of the objective for which you use custom exits, such as the ones used by the Reconciliation Agent. The Reconciliation Agent exits are engineered to be the last exits called in sequence. This allows existing exits to function normally.

  Note:

  The systems programmer must perform an IPL after a system component is changed or modified.

3.3 Deploying the Reconciliation Agent and Provisioning Agent

To deploy the Reconciliation Agent and Provisioning Agent:

1. Extract the contents of the following file from the installation media to a temporary directory on any computer:

   etc/Provisioning and Reconciliation Connector/Mainframe_ACF2.zip

   The Mainframe_ACF2.zip file contains the following files:

   • jcllib.xmi is an IBM z/OS PDS library with members for creation of data sets required by the Reconciliation Agent, Provisioning Agent, and auxiliary functions required by the Reconciliation Agent.

   • linklib.xmi contains the executable code or Loadlibs for the product.

   • parmlib.xmi is the PDS library containing members for the activation of the CA ACF2 exits required by the Reconciliation Agent.

   • proclib.xmi contains the STCs required to run the Reconciliation Agent and Provisioning Agent.

   • Clistlib.xmi contains Rexx clists used for the LDAP initiated Search functions.

2. Transmit the XMI files to the IBM z/OS computer.

   You can transmit the files either through FTP or IND$FILE on a TN3270 emulator. The files must be transmitted in binary format.

   The output files are in JES2 XMIT format. The output file names can be, for example:

   IDF.JCLLIB.XMIT

   IDF.LINKLIB.XMIT

   IDF.PARMLIB.XMIT

   IDF.PROCLIB.XMIT

   IDF.CLISTLIB.XMIT

   The file attributes are as follows:

   RECFM=FB

   LRECL=80

   BLKSIZE=3120

   DSORG=PS

3. Log in to the TSO environment of the mainframe.

4. Receive the uploaded files as follows:

   TSO RECEIVE INDA('IDF.JCLLIB.XMIT')
   TSO RECEIVE INDA('IDF.LINKLIB.XMIT')
   TSO RECEIVE INDA('IDF.PROCLIB.XMIT')
   TSO RECEIVE INDA('IDF.PARMLIB.XMIT')
   TSO RECEIVE INDA('IDF.CLISTLIB.XMIT')
   

5. When prompted to specify restore parameters, enter the following:

   DA('NAME_OF_INSTALLATION_DATASET_TO_BE_CREATED')
   

   Note:

   DA is a parameter of the RECEIVE command. It means Dataset.

6. To expand the LINKLIB dataset, enter the following command from the ISPF command line:

   TSO RECEIVE INDA('IDF.LINKLIB.XMIT')
   

7. When prompted to enter restore parameters, enter the following:

   DA('IDF.LINKLIB')
   

8. Edit the members of the JCLLIB.xmi uploaded PDS, and change the jobcard on each member to match installation standards.

9. Determine where you want the STC procedures and parmlib members to reside, and change the destination library on the IEBCOPYs for IEBCOPYL, IEBCOPYP, and IEBCPYPR PDS members.

10. Submit the following JCL members from the JCLLIB mentioned in Step 9:

    • CREATDSN

    • LOADDSN1

    • IEBCOPYL

    • IEBCOPYP

    • IEBCPYPR

11. Verify that each job ends with an MVS Condition code of 0000 (that is, ends with no errors).

12. Verify that the RACF subsystem interface is activated at IPL time. The SYS1.PARMLIB member is IEFSSNxx, where xx is the user's suffix. The required parameters for the RACF API are as follows:

    SUBSYS SUBNAME(RACF)                   /* RACF SUBSYSTEM    */
    INITRTN(IRRSSI00) INITPARM('#')
    
    (Or)
    SUBSYS SUBNAME(RACF)
    INITRTN(IRRSSI00)
    

    The INITPARM can be any character that IBM z/OS supports. Even though the Security Subsystem is ACF2, this RACF API is still used by Pioneer when it makes the call to R_admin API.

13. Verify that the LPA library containing the exits are in the LPA, IEASYSXX Start member of Z/OS, usually contained within the SYS1.PARMLIB.

14. The executable code (IBM z/OS loadlibs) of the Reconciliation Agent and Provisioning Agent must be APF authorized. This can be achieved by running a dynamic set command (T PROG=) or by placing the installation loadlib containing the Reconciliation Agent and Provisioning Agent in the IBM z/OS link list.

15. To refresh the LPA library, IPL the IBM z/OS system.

WARNING:

Do not reserve ports in the TCPIP profile or data file for Pioneer or Voyager. This will cause issues within Pioneer and Voyager.

3.4 Configuring the Started Tasks

Two different STCs are required to set up and run the Reconciliation Agent and Provisioning Agent. Pioneer and Voyager are sample STCs shipped along with the connector for the Reconciliation Agent and Provisioning Agent, respectively. These procedure members are in IDF.PROCLIB. The following sections provide information about configuring these samples:

• Section 3.4.1, "Configuring the STC for the Reconciliation Agent (Voyager)"

• Section 3.4.2, "Configuring the STC for the Provisioning Agent (Pioneer)"

3.4.1 Configuring the STC for the Reconciliation Agent (Voyager)

Note:

The PROCLIB Member = VOYAGER.

The following is the procedure for Voyager STC (Started Task):

//VOYAGER  PROC
//STEP1    EXEC PGM=VOYAGERX,REGION=0M,TIME=1440
//CACHESAV DD DISP=SHR,DSN=VOYAGER.CACHESAV
//SYSPRINT DD SYSOUT=*
//DEBUGOUT DD SYSOUT=*
//PARMFLE  DD DISP=SHR,DSN=VOYAGER.CONTROL.FILE
//PARMOUT  DD SYSOUT=*
//SYSUDUMP DD SYSOUT=X
//

The new control file "DD" PARMFLE is created via the CREATDSN job step and is loaded with a sample set of control parameters similar to what is shown in Table 3-1. Additionally, "DD" PARMOUT was added, and this is a display of the control file contents.

Table 3-1 lists the required parameters for Voyager.

Table 3-1 STC Parameters for Voyager

Parameter	Description	Sample/Default Values
TCPN	This parameter contains the name of the TCPIP STC where Voyager is executing.	8 characters
IPAD	This parameter contains the DNS HOSTNAME or TCPIP address of the LDAP Gateway Server.	IPAD=999.999.999.999 or IPAD=hostname.com 44 characters maximum
PORT	This parameter contains the port address that the LDAP Gateway is listening on for Voyager messages.	999999 The PORT defined in the LDAP properties xml that the LDAP listens on.
DEBUG	This parameter contains the N or Y=DEBUG=N is the normal setting and must be set to DEBUG=Y if required by Vendor Personnel.	Y or N Y turns on debugging and output goes to //DEBUGOUT N Debugging is off debugging. This is the normal way to execute Voyager.
ESIZE	This parameter contains the encryption used by Pioneer.	ESIZE=16 This value must be coded and not changed.
DELAY	This value is only valid in environments running CA Top-Secret.	Code DELAY=00 This value must be coded.
START DELAY	This value represents the delay before Voyager tries to connect to the LDAP.	STARTDELAY= 99 00 - 99, valid in seconds 00 is no delay.
PRTN CODE	If Voyager will honor, it willreturn codes internally.	If an error happens inside and the MVS condition is desired then PRTNCODE=TERMRC should be coded. If the MVS condition is not a wanted code,then PRTNCODE=SHUTRC
FILTER	This parameter filters ACF2 events from the subpool.	FILTER=NO. No filtering let all subpool messages be submitted to the LDAP. FILTER=YES,A=xxxx, V=yyy,yyy,yyy When found this event will be passed to the LDAP for processing. The Filter=Y does not apply to ACF2 Deletes. This is a special purpose parameter and not generally required in most installations. There are restrictions on what can be filtered. The A=text and V=text value. A good example of this filtering is: Filter=Y,A=DFT-PFX,V=TEST1,TEST2. In this case if the DFT-PFX is TEST1 or TEST2 when the event is processed it will be passed as a Message to the LDAP for processing.
VOYAGER_ID	A unique identifier used by the LDAP to identify Voyagers using the same LDAP.	8 characters If for example, 8 Voyagers are sharing the same LDAP, then all of the voyagers must use the same VOYAGER_ID.

Note:

The Cachesav "DD" (Data Definition) statement is for a QSAM file that is created during the installation process and is used by Voyager to save subpool entries if there is a shutdown while entries are in the subpool. Upon restart, Voyager reloads the subpool with entries from the Cachesav plus any entries that are all ready in the subpool. No entries will be lost.

If a “C VOYAGER” is issued while Voyager is in recovery and trying to connect to the LDAP resulting in messages queued in the subpool, then some messages may be lost. These lost messages, if any, will be recovered via the reconciliation mechanism.

3.4.2 Configuring the STC for the Provisioning Agent (Pioneer)

The following is the procedure for Pioneer STC (Started Task):

//PIONEER  EXEC PGM=PIONEERX,REGION=0M,TIME=1440,
//    PARM=('TCPN=TCPIP',
//          'IPAD=0.0.0.0',
//          'PORT=5897',
//          'DEBUG=N')
//JCLOUTP  DD SYSOUT=*
//LINEOUT  DD SYSOUT=*
//BATJINFO DD DISP=SHR,DSN=PIONEER.BATJCARD
//RECONJCL DD DISP=SHR,DSN=PIONEER.RECON.LIBRARY
//RECONOUT DD DISP=SHR,DSN=PIONEER.RECON.FILE
//VSAMGETO DD DISP=SHR,DSN=PIONEER.ACF2COUT
//PARMFLE  DD DISP=SHR,DSN=PIONEER.CONTROL.FILE
//INJCLR   DD DISP=SHR,DSN=PIONEER.INJCL.LIBRARY
//LISTINR  DD DISP=SHR,DSN=PIONEER.ALIAS.LSTOUT,
//            DCB=(RECFM=VB,LRECL=137)
//SYSPUNCH DD SYSOUT=(*,INTRDR)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=X
//

Table 3-2 lists the required STC parameters for Pioneer.

Note:

STC parameters are changed as of Release 9.0.4.17.

Table 3-2 STC Parameters for Pioneer

STC Parameter	Description	Sample/Default Values
TCPN	This parameter contains the name of the TCPIP STC where Pioneer is executing.
IPAD	This parameter contains the Socket Server address.	This parameter indicates that Port Pioneer is listening on for incoming messages from the LDAP Gateway. IPAD=999.999.999.999
PORT	This parameter indicates Port address Pioneer is listening on.	Value is 999999 This value is coded in the LDAP Property xml.
DEBUG	This parameter indicates Pioneer is functioning normally or not.	DEBUG=Y DEBUG=Y Turns on Debugging and output goes to //DEBUGOUT DEBUG=N no debugging

Table 3-3 Parmfle Parameters

Parmfle Parameters	Description	Sample/Default Values
ESIZE	The encryption routine being used. ESIZE=16 is the only accepted value.	ESIZE=16 only ESIZE=16 is AES128 bit encryption
LPAR	Unique identifier	Identifier can be a maximum of 20 characters. This field is not used and may be anything that the installation wants.
RWAIT	Reconciliation wait time. The time in seconds is the waiting time for Pioneer for a batch reconciliation job to complete. These jobs are requested via the LDAP and are usually groups of LIDS, Groups, datasets or facilities.	RWAIT=000 to 999 This value is in seconds.
JWAIT	Job wait time. The time in seconds Pioneer waits for ALIAS job submissions to complete. The ALIAS is either being defined or deleted by a request from the LDAP.	JWAIT=000 to 999 This value is in seconds.
POST_PROC_ALIAS	Pioneer will either process LDAP ALIAS requests or not.	T = True F = False POST_PROC_ALIAS=T Pioneer will process all ALIAS requests from the LDAP POST_PROC_ALIAS=F Pioneer will not process any ALIAS requests from the LDAP.
IDLEMSG	Pioneer will display an idle message during times of no work.	Y = Yes , every 60 minutes N = No , None
DEBUGOUT	Output destination of DEBUG output when DEBUG=Y is on.	FILE. When DEBUGOUT=FILE is specified, the output goes to a dataset fixed inside Pioneer. DSN='PIONEER.DEBUG.LOGXX' Where xx is 01-99 SYSOUT,CLASS(X) When DEBUGOUT=SYSOUT,CLASS(X) The output goes to JES2 Class(x) can be viewed via SDSF or IOF.
SPIN_CLASS	Output class when a DEBUGOUT output is created when the DEBUG=N is issued via the Operator Interface.	1 character Valid JES2 class
QUEUE_DSN	Name of the queue dataset used by all reconciliation submitted jobs. For more information, see Table 3-4.	QUEUE_DSN=xxxxxxxxxx The DSN can be a maximum of 44 characters. This dataset must also be defined to ACF2 for Pioneer and the batch submitted JCL contained in the //RECONJCL 'DD'.

Table 3-4 Pioneer 'DD's (Data Definition statements)

DD Name	Description	ACF2 Type Access Required By Pioneer
//JCLOUTP	Display of JCL statements for submitted jobs	Write only
//RULELOG	Display of LDAP built ACF2 rules	Write only
//RECONJCL	JCL skeleton for all LDAP Recon submitted jobs	Read only
//RECONOUT	Output file for LDAP batch Recon submitted jobs	Read and Write
//BATJINFO	JCL skeleton for LDAP submitted ACF2 rules	Read only
//VSAMGETO	Output file for LDAP submitted ACG2 rules	Read and Write
//PARMFLE	Pioneers parameters	Read only
//LISTINR	Output from Alias job submission	Read and Write
//INJCLR	JCL skeleton for LDAP submitted ALIAS executions	Read only
//SYSPUNCH	Output for all job submissions	Output

Note:

Because of the wide variety of installations, ACF2 definitions are not usually included with this document. The ACF2 expertise generally resides at the installation performing the work.

Pioneer Reconciliation Search Flow:

The following steps show how the Pioneer reconciliation search flows.

1. LDAP passes request from Oracle Identity Manager or other Identity Manager requesting one of the following functions:

   SERCHALL,ACCRALL,RESRALL,RULELST or RULEQRY.

2. LDAP passes the encrypted request to PIONEER.

3. PIONEER receives the request via PORT= and decrypts it, converts to EBCDIC and validates the request.

4. Pioneer reads the RECONJCL skeleton JCL inserting the clistname and the queue_dsn name and submits the job stream via the internal reader (syspunch) for execution.

5. Pioneer will then go into a wait based on RWAIT=

6. Pioneer will then check on RWAIT where the queue_dsn was created, if not, Pioneer will wait again RWAIT= until the file has been created.

7. Once created, Pioneer reads the file, builds the messages for the LDAP converts to ASCII and encrypts them and then issues a write socket to the LDAP until it has read the entire file.

8. Once end-of-file has been encountered, the file is cleared.

The following are attributes of data sets required by the Provisioning Agent (they are created in the installation process):

BATJCARD - DSORG=(PS),LRECL=(80),RECFM=(FB),BLKSIZE=(8000),Tracks=1
VSAMGETO - DSORG=((PS),LRECL=(133),RECFM=(VBA),BLKSIZE=(27930),cylinders=10
PARMFLE  - DSORG=(PS),LRECL=(80),RECFM=(F),BLKSIZE=(80),Tracks=2
RECONJCL – DSORG=(PS),LRECL=(80),RECFM=(FB),BLKSIZE=(80),Tracks=2
RECONOUT – DSORG=(PS),LRECL=(90),RECFM=(FB),BLKSIZE=(27000),CYLINDERS=50
INJCLR   - DSORG=(PS),LRECL=(80),RECFM=(FB),BLKSIZE=(80),Tracks=2
LISTINR  - DSORG=(PS),LRECL=(133),RECFM=(VBA),BLKSIZE=(1330),Tracks=20

These allocations are created with a M=CREATDSN in the JCLLIB shipped with the product. These are starting allocations. The only file that may need increasing is RECONOUT. This is dependent on how many users are contained within the ACF2 database.

Note:

These file allocation values are similar to the values given in the JCLLIB.XMI distribution file. You need not change these values.

The following are contents of the BATJCARD data set, which is required for CA ACF2 rule processing:

//QACF0001 JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,
//     CLASS=A,PRTY=8,NOTIFY=&SYSUID,REGION=4096K,USER=abcdef
//ACFJOB  EXEC  PGM=IKJEFT01,DYNAMNBR=25
//SYSTSPRT DD DISP=SHR,DSN=ADCDM.ACF2COUT
//SYSHELP DD DISP=SHR,DSN=SYS1.HELP
//SYSLBC  DD DISP=SHR,DSN=SYS1.BRODCAST

Make the following changes in these lines:

• In the second line of code, replace abcdef with a system-level UID that has the CA ACF2 privileges required to create, modify, and delete users.

• In the fourth line of code, ensure that the SYSTSPRT DD data set name matches the Pioneer dataset name in the VSAMGETO DD line shown earlier in this section.

3.5 Installing the Reconciliation Agent Exits

To allow the LDAP Gateway to capture events, the Reconciliation Agent and its exits must be installed on each LPAR that shares the authentication repository. The following exits are provided along with this connector:

• IDFACF2E

  This connector exit replaces the standard CA ACF2 exit LIDPOST. It captures CA ACF2 events (LIDREC), such as INSERT and CHANGE, and places them into subpool 231.

• IDFACF2P

  This connector exit replaces the standard CA ACF2 exit NEWPXIT. It captures LIDREC information related to password changes by the user at logon time, and places this information into subpool 231.

  Note:

  Install this exit only if you want to capture password changes and send them to Oracle Identity Manager.

• IDFACF2X

  This connector exit replaces the standard CA ACF2 exit EXPPXIT. It captures LIDREC information about a password when the password expires, and places this information into subpool 231.

  Note:

  Install this exit only if you want to capture changes related to passwords expiring and send these changes to Oracle Identity Manager.

• IDFCACHE

  This is the caching module used by the preceding 3 exit modules to build events for the Reconciliation Agent. This caching module must be in the same LPA library as the 3 exit modules.

Because the exit modules are in the IBM z/OS Load Library, an IPL may or may not be required to complete the installation. This depends on whether the z/OS Load Library is added to the LPA, which is a z/OS storage area defined at the time of an IPL.

To install the Reconciliation Agent exits:

1. Ensure that the exits are modules in a LINKLIB, and the SYS1.PARMLIB activates the exits. For example, a typical system would have an entry in OIMACF2.PARMLIB(LPALSTCA).

2. Copy the exits into the appropriate LPAR for the system.

   Copy the IDFACF2E, IDFACF2P, IDFACF2X modules into CAI.CAILPA or an installation-defined LPA library. In addition, copy a utility module called IDFCACHE into CAI.CAILPA or an installation-defined LPA library. The exit modules are in LINKLIB PDS and must be copied to the appropriate LPAR for the system.

3. Modify the control GSO record for the system to add the exits. If the GSO record already exists, then either change it to activate the exits or add a new record. The CA ACF2 exit activation through z/OS is as shown here:

   See Also:

   Target system documentation for information about GSO

   READY ,
    
   ACF
    
    ?  SET CONTROL(GSO) SYSID(SYSTEMNAME)
    
    ?  INSERT SYSID(SYSTEMNAME) EXITS LIDPOST(IDFACF2E) EXITS EXPPXIT(IDFACF2X) NEWPXIT(IDFACF2P)
    
    ACF0A026 RECORD ALREADY EXISTS,
    
    ?  CHANGE SYSID(SYSTEMNAME) EXITS LIDPOST(IDFACF2E) EXPPXIT(IDFACF2X) NEWPXIT(IDFACF2P)
    
     SYSTEMNAME / EXITS LAST CHANGED BY MLIGHT ON 03/22/06-23:24,
    
     NEWPXIT(IDFACF2P) EXPPXIT(IDFACF2X) LIDPOST(IDFACF2E)
    
    ? QUIT
   

   Note:

   SYSTEMNAME mentioned in the code is the name of the deployment system.

4. Refresh the GSO to add in the new values by running the following command:

   READY
    
   ACF
    
    ?  F ACF2,REFRESH(EXITS)
    
    ACF79507 GSO PROCESSING COMPLETED WITHOUT ERROR
    
    ?  QUIT
    
    READY
   

5. IPL IBM z/OS to make the exits operational.

Activating the Exits

To dynamically activate the Reconciliation Agent exits:

1. Create a dynamic member as follows:

   SYS1.PARMLIB(PROG78)
   EXIT, ADD, EXITNAME(LIDPOST), MODULE(IDFACF2E), STATE(ACTIVE)
   EXIT, ADD, EXITNAME(NEWPXIT), MODULE(IDFACF2P), STATE(ACTIVE)
   EXIT, ADD, EXITNAME(EXPPXIT), MODULE(IDFACF2X), STATE(ACTIVE)
   

2. Run the following command from the IBM z/OS master console:

   T PROG=78
   

3. At the TSO READY prompt:

   READY ,
   ACF
   ?  SET CONTROL(GSO) SYSID(SYSTEMNAME) 
   ?  DELETE SYSID(SYSTEMNAME) EXITS LIDPOST(IDFACF2E) EXITS EXPPXIT(IDFACF2X) NEWPXIT(IDFACF2P)
    
   

4. Shut down IBM z/OS.

5. IPL IBM z/OS.

Deactivating the Exits

To dynamically deactivate the Reconciliation Agent exits:

1. Create a dynamic member as follows:

   SYS1.PARMLIB(PROG79)
   EXIT, DELETE, EXITNAME(LIDPOST), MODULE(IDFACF2E), FORCE=YES
   EXIT, DELETE, EXITNAME(NEWPXIT), MODULE(IDFACF2P), FORCE=YES
   EXIT, DELETE, EXITNAME(EXPPXIT), MODULE(IDFACF2X), FORCE=YES
   

2. Run the following command from the IBM z/OS master console:

   T PROG=79
   

Integrating the Exits

Below is one schema that works only with IDFACF2E (LIDPOST) exit on ACF2.

1. Build a driver assembler routine as shown:

   Column1	Column 10	Column 16
   LIDFRONT	CSECT
   LDFRONT	RMODE	ANY
   LIDFRONT	AMODE	31
   	YREGS
   	BAKR	R14, 0
   	LR	R12, R15
   	USING	LDFRONT, R12
   	L	R15,=V(IDFACF2E)
   	BASR	R14, R15
   	LTR	R15, R15
   RETURN	DS	0H
   	PR
   	END	LIDFRONT

   
   

2. Assemble and link making sure the libraries containing IDFACF2E and IDFCACHE are correctly concatenated in the assemble and linkedit job stream.

3. Deactivate the existing exit.

4. Activate the new exit.

   Note:

   This is not a tutorial in the actual integration of Oracle/IDF exits into the customer's environment. It is the customer's responsibility to integrate the exits.

   If the customer needs assistance in this matter Oracle should be contacted and appropriate arrangements will be made for assistance.

3.6 Creating LIDs for the Reconciliation Agent and Provisioning Agent STCs

The Reconciliation Agent and Provisioning Agent STCs must each have a LID associated with it.

The CA ACF2 definitions for the Reconciliation Agent are as shown in the following screenshot:

The Provisioning Agent STC LID must have administrative privileges to run functions such as Create, Change, List, and Replace. The CA ACF2 definitions for the Provisioning Agent are as shown in the following screenshot:

To create LIDs for reconciliation agent and provisioning agent STCs:

1. Add the Pioneer LID and Voyager LID into TSO or in batch.

2. Set LID as:

   1. INSERT PIONEER NAME (PIONEER STC ID) STC.

   2. INSERT VOYAGER NAME (VOYAGER STC ID) STC.

   3. CHANGE PIONEER ACCOUNT SECURITY.

3. Add Pioneer/Voyager to Resource rule fac (bpx) as:

   1. DAEMON UID (PIONEER) SERVICE(READ) LOG

   2. DAEMON UID (VOYAGER) SERVICE(READ) LOG

4. Add Pioneer/Voyager to Resource Rule fac(irr) as:

   1. IRR.RADMIN.* UID(PIONEER) SERVICE(READ) LOG.

   2. IRR.RADMIN.LISTUSER UID(VOYAGER) SERVICE(READ) LOG.

Note:

Pioneer must have SECURITY privileges, which acts as a central site security administrator and must be able to add lids, change lids, delete lids as well as resources, rules.

Voyager only needs to be able to perform IRR.RADMIN.LISTUSER.

All IRR.RADMIN calls are through the standard IBM module IRRSEQ00.

3.7 Starting Up and Shutting Down the Reconciliation Agent and Provisioning Agent

Both agents use the standard CICS Socket Interface EZASOKET. Error messages that the agents can return are documented in Appendix A and Appendix B. In addition, see z/OS V1R9.0 Communications Server IP CICS Sockets Guide for more information.

Note:

The subpool and the LDAP Gateway must be started before starting the Reconciliation Agent. If the LDAP Gateway is not available when the Reconciliation Agent is started, then an error is generated with RETCODE=-01 and ERRORNO=61.

To start up the Reconciliation Agent and Provisioning Agent:

1. IPL z/OS.

2. Start CA ACF2.

3. JES2 is started.

4. TCP/IP and other communications-related STCs are started.

5. The STARTUP procedure is executed to establish the subpool that is used to capture CA ACF2 events. The following is the startup procedure:

   //STARTUP  PROC
   //STEP1    EXEC PGM=STARTUP,TIME=1440,
   //         PARM=('SUBPOOL=0800K')
   //SYSPRINT DD SYSOUT=*
   //SYSUDUMP DD SYSOUT=*
   // 
   

   Startup only requires 1 parameter SUBPOOL = x. This value must have leading zeros if below 1000K, for example, 900k would be expressed as SUBPOOL = 0900K.

   Note:

   This step must be performed only after an IPL or after the WRAPUP procedure is run. WRAPUP deletes the subpool. If the subpool is not established, the Reconciliation Agent fails with a message indicating that the subpool is missing.

   The Provisioning Agent does not require the subpool.

6. To start the Reconciliation Agent, run the S VOYAGER command from the IBM z/OS operator's console or SDSF in TSO.

7. To start the Provisioning Agent, run the S PIONEER command from the IBM z/OS operator's console or SDSF in TSO.

To shut down the Reconciliation Agent and Provisioning Agent:

To shut down the Reconciliation Agent, run the F VOYAGER,SHUTDOWN command from the z/OS Operator console or TSO/ISPF issue.

To shut down the Provisioning Agent, run the F PIONEER,SHUTDOWN command from the z/OS Operator console or TSO/ISPF issue.

3.8 Pioneer Control File

From this release onwards, Pioneer will use a control file defined to Pioneer as a "DD" of "PARMFLE". Table 3-5 shows the parameters and the format in the QSAM file.

Table 3-5 Pioneer Parameters

Parameter	Description
ESIZE	This parameter contains the encryption used by Pioneer. Sample value: 16
LPAR=xxxxxxxxxxxxxxxxxxxx	This parameter contains the user definition for Pioneer. Default value: 20 byte
JWAIT=999	This parameter contains the amount of time Pioneer waits after an ALIAS has been submitted and Pioneer wait before attempting a read of the file to be send back to the LDAP. Sample value: 001 to 999 in seconds
POST_PROC_ALIAS=T	This parameter tells Pioneer to process ALIAS requests. Sample value: T (true) or F (false)
IDLEMSG	This parameter contains the values as: N (NO) or Y (YES) for IDLE Messages. If set to N, then no IDLE messages display in SYSOut of Pioneer ot Z/OS console Log. If set to Y, the IDLE messages will display every 60 minutes if Pioneer is IDLE for 60 minutes.
DEBUGOUT=SYSOUT,CLASS(X)	Using this parameter, two values can be coded, the one shown or DEBUGOUT=FILE. If DEBUG=Y, then this parameter is honored by Pioneer. If DEBUG=N, it is ignored. SYSOUT,CLASS directs the DEBUGOUT to JES2 with CLASS (x). DEBUGOUT=FILE directs DEBUGOUT to a QSAM file. Allocation parameters are displayed in the SYSOUT of Pioneer. Allocation, whether it is SYSOUT or FILE is dynamic.
SPIN_CLASS=x	This parameter is used in conjunction with DEBUG=Y and DEBUGOUT=SYSOUT, CLASS (x), used via And Operator command. Note: If no more parameters are coded after SPIN_CLASS in the control file, POST-PROCESSING will not be done.

3.9 Pioneer Post-Processing

To enable Pioneer to Post-Processing, the following command is required:

Acf2 command, M= , L=

The valid ACF2 commands are INSERT,CHANGE and DELETE.

Example# 1:

C=INSERT,M=ABCD,L=YOUR.JCLLIB

In this example, only INSERTS coming through the LDAP will be Post-Processed. Every INSERT sent through the LDAP will execute the member = ABCD of Library = your.jcllib. By default Pioneer will also pass the ACF2 LID to a clist that is invoked by the INSERT post-processing such as L=YOUR.JCLLIB.

/REXXBTH JOB ,SYSTEMS,CLASS=A,MSGCLASS=X,
//      MSGLEVEL=(1,1),REGION=4096K,NOTIFY=&SYSUID
//STEP1   EXEC  PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPROC  DD DSN=YOUR.CLIST.LIBRARY,DISP=SHR
 //SYSTSIN  DD *
 %ABCD LIDNAME
 
M=ABCD
/* rexx   */
arg lid
say 'Parms passed by Pioneer are:  ' lid

Example# 2:

C=INSERT,M=ABCD,L=YOUR.JCLLIB
C=CHANGE,M=DEFG,L=YOUR.JCLLIB

In this example, INSERTs and CHANGES are Post-Processed and use the same logic as illustrated above to execute Rexx clists.

Example# 3:

C=INSERT,M=ABCD,L=YOUR.JCLLIB
C=CHANGE,M=DEFG,L=YOUR.JCLLIB
C=DELETE,M=HIJK,L=YOUR.JCLLIB

In this example, INSERT, CHANGES and DELETES are Post-Processed and use the same logic as illustrated above to execute Rexx clists such as, The L= and M= are dynamically allocated by Pioneer, read by Pioneer and then punched to the Intrdr and the L= and M= are closed and freed.

3.10 Pioneer/Voyager Operator Commands

The Operator Interface of Pioneer/Voyager has been enhanced in ACF2 Adapter 9.0.4.15. Many new commands have been added to both Pioneer and Voyager. The commands whether if they are issued to Pioneer or Voyager are issued via the z/OS modify interface. For example, if the STC (Started Task) names are Pioneer and Voyager, the modify command syntax would be F PIONEER command or F VOYAGER command. Table 3-6 shows the commands that can be issued and its action.

Table 3-6 Pioneer/Voyager Operator Commands

Command	Action
F PIONEER,SHUTDOWN	Shutsdown Pioneer
F VOYAGER,SHUTDOWN	Shutsdown Voyager
F PIONEER,STATUS	Shows status of Pioneer
F VOYAGER,STATUS	Shows status of Voyager
F PIONEER,DEBUG=Y	Turns debugging on
F PIONEER,DEBUG=N	Turns debugging off
F PIONEER,RWAIT=999	Modifies RWAIT timer to 999
F PIONEER,JWAIT=999	Modifies JWAIT timer to 999

Note:

• Pioneer and Voyager are both single threaded STC (Started Tasks). If the command is entered and a MODIFY TASK BUSY is returned, then STC is processing and the command should be retried later.

• When entering a RWAIT or a JWAIT value, leading zeros are required, for example, 9 seconds would be JWAIT=009 and RWAIT=9.