Skip Headers
Oracle® Identity Manager Connector Guide for IBM RACF Advanced
Release 9.0.4

Part Number E10451-20
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Deploying the IdF Advanced Adapter for IBM RACF

The IdF mainframe adapter is composed of the following main components:

Pioneer: As discussed in one of the earlier chapters, Pioneer (also known as the Provisioning Agent) receives native mainframe identity and authorization change events from the LDAP Gateway. These events are processed against the mainframe authentication repository, in which all provisioning updates from the LDAP Gateway are stored. The response is parsed and returned to the LDAP Gateway.

Voyager: This component is also known as the Reconciliation Agent. The Voyager captures native mainframe events by using System Exits. The Voyager transforms these events into LDAPv3 protocol notification messages through the LDAP Gateway.

System Exits: These are programs that are run after system events in IBM RACF have been detected. System Exits capture these events in real time. They are events occurring from the TSO logins, the command prompt, batch jobs, and other native mainframe events.

Note:

Before you install the mainframe components of the RACF Advanced Adapter on a Production environment, Oracle recommends that you install the product on a Test and/or Development environment for testing, prior to installing on a Production environment.

2.1 Prerequisites

The prerequisites for installing the IdF Advanced adapter as follows:

2.1.1 Message Transport Requirements

Between the LDAPv3 server and mainframe environments, the software supports TCP/IP. For the TCP/IP message transport layer, ports 5190 and 5790 are the default ports for the Voyager Agent and Pioneer Agent, respectively. You can change the ports for these agents. The procedures to configure these message transport layers are described later in this guide.

2.1.2 APF Authorization

Authorized Program Facility (APF) granting the APF authorized status to a program is similar to giving super user status. This process will allow a program to run without allowing normal system administrators to query or interfere with its operation. Both the program that runs on the mainframe system and the user account it runs under must have APF authorization. The IdF Agent user account must have APF authorization.

2.2 Mainframe Adapter Installation

The following sections of this chapter describe the procedure to install the adapter.

2.2.1 Extracting the Files for Deployment from the Distribution Zip Archive File

To extract the files from the distribution zip file:

Extract the contents of the following file to a temporary directory, distribution zip archive file.

The following are the contents of the zip file:

  • clistlib.xmi

  • jcllib.xmi

  • linklib.xmi

  • parmlib.xmi

  • proclib.xmi

  • racf-readme.txt

2.2.2 Uploading Files

You must upload the files that are extracted with the .xmi extension to the computer that is hosting the mainframe. See Section 2.2.1, "Extracting the Files for Deployment from the Distribution Zip Archive File" for information about extracting the files for deployment.

You can upload the files either by using a QWS3270P emulator or FTP. The following is the procedure to upload files by using the QWS3270P emulator:

  1. Log in to the TSO environment of the mainframe, type ISPF at the READY prompt, and then press Enter.

  2. From the ISPF menu, on the Option line, enter "6". The Command entry screen to enter TSO commands is displayed.

    Surrounding text describes idf_upload37.gif.
  3. Use the IND$FILE command to upload files to the computer hosting the mainframe. The upload option of the QWS3270P program enters a formatted command.

    In this example, the host file name is LINKLIB.XMIT and the sending or local file name is as follows:

    C:\Users\My_Name\Desktop\test-RACF\linklib.xmi.
    

    The upload options are in the upload window for QWS3270P are:

    File Conversion: Nothing selected (No ASCII/EBCDIC translation and no CRLF)

    Host Type: TSO selected

    Record Format: Default selected

    Sizes: LRECL and BLKSIZE are left blank

    Surrounding text describes gif1.gif.
  4. Click OK to initiate file upload.

    The File Transfer Status dialog box with a message that the transfer was successfully completed is displayed.

    Surrounding text describes idf_upload2.gif.
  5. Click Exit to dismiss the dialog box.

  6. Repeat Steps 3 through 6 to upload the rest of the .XMI files.

Table 2-1 lists the uploaded files.

Table 2-1 File Names on Client Machine and Mainframe Host

File name on Client Machine Recommended File Name on Mainframe Host

linklib.xmi

LINKLIB.XMIT

proclib.xmi

PROCLIB.XMIT

parmlib.xmi

PARMLIB.XMIT

jcllib.xmi

JCLLIB.XMIT

clistlib.xmi

CLISTLIB.XMIT


2.2.3 Extracting the XMIT Files

The files uploaded to the computer hosting the mainframe (by using the procedure described in Section 2.2.2, "Uploading Files") are XMIT files. An XMIT file is an archived file format used on the mainframe

To extract the files or Partition Datasets (PDS) in the XMIT file:

  1. Enter the RECEIVE command in the area designated to enter commands.

    For example, enter the following command:

    receive inda('linklib.xmit')
    

    Note:

    Filenames in mainframe are case insensitive.

  2. When prompted, enter the following to complete running the RECEIVE command:

    Enter restore parameters or "DELETE" or "END" +
    
  3. Enter the name of the PDS that the XMIT file will expand into. In this case, enter the following:

dataset('USER_NAME.idf.FILE_NAME')

In this command, replace:

  • USER_NAME with the user name on the system you have access to.

  • FILE_NAME with the name of the XMIT file to be extracted.

For example:

dataset('idf.test1.linklib')

In this example, the prefix IDF is the user name that is being used in this section. In your environment, replace the prefix IDF with the user name on the system you have access to. If you specify the PDS name within single quotation marks, then the PDS name with a user name. That is the fully qualified name.

If single quotation marks are not used, then the PDS is created with a prefix of the user name that you are logged on with. In this case, the response is as follows:

dataset(idf.linklib)

Table 2-2 lists the XMIT file names and the corresponding PDS names.

Table 2-2 XMIT File Names and PDS Names

XMIT File Name on Mainframe Host Recommended PDS Name on Mainframe Host

LINKLIB.XMIT

IDF.LINKLIB

PROCLIB.XMIT

IDF.PROCLIB

PARMLIB.XMIT

IDF.PARMLIB

JCLLIB.XMIT

IDF.JCLLIB

CLISTLIB.XMIT

IDF.CLISTLIB


Enter the response and follow the given steps:

  1. Press Enter again for the RECEIVE command to continue.

    The following screen shots shows the output from the execution of the RECEIVE command.

    Surrounding text describes idf_upload3.gif.
    Surrounding text describes idf_upload5.gif.
    Surrounding text describes idf_upload4.gif.
  2. Press Enter for each screen displayed since the output stops when the screen is full.

    The RECEIVE command completes when the Restore successful message has been displayed on the screen.

  3. Press Enter one last time to bring back the command entry screen.

  4. Enter the RECEIVE command for each of the uploaded files using the host files name you selected for them.

  5. Enter the restore parameters in response to each RECEIVE command you enter.

    Note:

    The IDF.LINKLIB once "RECEIVED" can be either a STEPLIB or added to the environments existing Linklist. This library MUST be APF authorized.

  6. After all the files have been processed (extracted from the XMIT file with the Receive command), look at the members of each PDS using the Data Set List Utility which is ISPF option 3.4. on the command line to go there from the command entry screen.

    Surrounding text describes idf_upload6.gif.
    Surrounding text describes idf_upload7.gif.
  7. In the Data Set List Utility Screen Enter:

    'IDF.TEST1.* 
    

    in the Dsname Level field on the screen. This will display a list of the files that match.

    Press Enter to bring up the list.

    Here is the list of the files that matched what you entered.

    Surrounding text describes idf_upload8.gif.
    Surrounding text describes idf_upload9.gif.
  8. Enter V (for view) to the left of one file names, and press Enter to view the members in the PDS.

  9. Enter E (for edit) to edit the members in the list.

  10. Place the cursor to the left of one of the member names on this screen to bring up the editor.

  11. Click EDIT mode to make changes.

2.2.4 Editing the Mainframe Batch Job Files to Match the Settings for the Customer's Site

The PDS IDF.JCLLIB contains the CREATEDSN, IEBCOPYL, IEBCOPYP, IEBCPYRP, and LOADDSN members, which will have to be edited to change file names, volsers, and job names to match your installation specifications. Modify the jobcard for each batch job to meet your installation specifications. The job card will usually be the first three lines of the batch file. To make changes to the batch job file will require TSO.

To make changes to the batch job files:

  1. Logon to TSO.

  2. Go to option 3.4 as shown above.

  3. Edit the dataset name 'IDF.JCLLIB' member is CREATDSN, shown below.

    CREATDSN member in the editor to make changes.

    Surrounding text describes idf_upload10.gif.
  4. To change existing text in the file, type over the existing text with new text. The editor will respond and provide a line to enter the text.

  5. To insert a line of text in the file. Enter I in the number area on the line that we want to start entering text after.

    Surrounding text describes idf_upload11.gif.

    The editor will respond and provide a line that we can enter text into.

  6. Press Enter before entering the text to remove the line.

  7. Press Enter to add another line.

  8. Press Enter to finish.

Surrounding text describes idf_upload12.gif.

There are also variations to the insert line command. A common variation is to enter a number after the "I".

To indicate the number of lines to insert:

  • Use the arrow keys or the mouse to position the cursor to the line to enter text.

    If you press Enter before you have finished entering text in your lines, then the lines that you did not enter text into will disappear.

Surrounding text describes idf_upload13.gif.
Surrounding text describes idf_upload14.gif.

To delete lines in the file:

  1. Enter D in the number area on the line that you want to delete.

  2. Press Enter to delete the line.

    You can see that after entering a "D" in the first screen and in the second screen the line has been deleted.

Surrounding text describes idf_upload15.gif.
Surrounding text describes idf_upload16.gif.

There are variations of the delete line command. A common variation is to enter a number after D to indicate the number of lines to delete. For example:

  • Enter D3 to delete 3 lines.

Surrounding text describes idf_upload17.gif.
Surrounding text describes idf_upload18.gif.

To navigate through the file you need to use the function keys as follows:

  • Press F7 to scroll the edit screen up a screen to the beginning of the file.

  • Press F8 to scroll the edit screen down a screen to the end of the file.

  • Press F3 to finish editing the file.

    This will bring up the exit options.

Surrounding text describes idf_upload19.gif.

The Following are the Members of PDS IDF.JCLLIB:

  • The CREATDSN member is an IEFBR14 file creation stream that will build the files required for Pioneer and Voyager. For each dataset name (DSN), PIONEER is used for the High-Level qualifier (HLQ) for Pioneer files and VOYAGER is used for the HLQ for Voyager files. The HLQ will have to be changed to meet installation standards. The VOL=SER= should be changed to point to the installation dasd volumes. The allocations are adequate. Once this member has been reviewed and changed, submit this job and review the output. The return code (RC) should be 0000.

  • The LOADDSN member loads the files created by CREATDSN to the defined load area. For each DSN, PIONEER is used for the HLQ for Pioneer files and VOYAGER is used for the HLQ for Voyager files. The HLQ will have to be changed to meet installation standards. The SYSUT1 value defines the member to be loaded and SYSUT2 value defines the sequential or flat file it is being loaded into. Submit the job and review the output. The RC should be 0000.

  • The IEBCOPYL member copies the RACF exits (LOGPWX01 and LOGRIX02) and the called caching routine IDFCACHE to an installation LPA library that RACF has access to. The exit modules are renamed during the copy process as ICHPWX01 and ICHRIX02. Review and change the LPA library name to meet installation standards. Submit the job and review the output. The RC should be 0000.

    If your host mainframe has any of the exits already in place that IdF ships (LOGPWX01, LOGRIX02, and LOGEVX01), then it is your responsibility to integrate these exits. TheLOGEVX01 exit is loaded dynamically as IRREVX01. If the customer does not have the staff or knowledge then IdF can be contacted and they will provide assistance via a Professional Services contract.

  • The IEBCOPYP member is an IEBCOPY file copy stream that copies the PROG members to an installation defined parameter library. Review and change the parameter library name in //OUTDD1 to point to the destination installation parameter library name (Parmlib) for the two PROG members. These are required for activation any time a IPL of z/OS occurs. The member PROGID sets APF authorization dynamically for IDF.LINKLIB. This can be added to an existing PROGxx member if desired. The PROG75 member contains the dynamic exit definitions for activation of the LOGEVX01 exit as IRREVX01. The PROG76 member will deactivate it. Submit the JOB stream and review output. The RC should be 0000.

  • The IEBCPYPR member is an IEBCOPY file copy stream for the STC procedures and procedures used by the product. Pioneer and Voyager are STC procedures. Startup and Wrapup are the procedures to build the subpool (STARTUP) and delete the subpool(WRAPUP) for Voyager (See Note). Normally, when z/OS is shutdown the subpool storage area is released. Review the names and change to meet installation specifications. Change the procedure library name to the installation procedure library name. Submit the JOB stream and review the output. The RC should be 0000.

    Remember that the jobcard for each of the above batch jobs will have to be changed to meet installation specifications.

    Files must not be shared in a SYSPLEX. Each Pioneer and Voyager must have their own set of files.

    Note:

    As of Oracle RACF Adapter 9.0.4.22, Startup and Wrap with both incorporated into Voyager. They are for an "Emergency Usage Only".

Table 2-3 lists the CREATDSN variables, corresponding sample values, and site values.

Table 2-3 Pioneer and Voyager CREATDSN Files

CREATDSN Variables Sample Values Site Values

Jobcard

//CREATDSN JOB SYSTEMS, MSGLEVEL(1,1),

// MSGCLASS=X,CLASS=A,PRTY=8,

// NOTIFY=&SYSUID,REGION=4096K

 

VOL=SER=

?????? or XXXXXX

 

Pioneer HLQ

DSN=PIONEER.

 

Voyager HLQ

DSN=VOYAGER.

 

Table 2-4 lists the LOADDSN variables, corresponding sample values, and site values.

Table 2-4 Pioneer and Voyager LOADDSN Files

LOADDSN Variables Sample Values Site Values

Jobcard

//LOADDSN JOB SYSTEMS,MSGLEVEL=(1,1),

//MSGCLASS=X,CLASS=A,PRTY=8,

//NOTIFY=&SYSUID,REGION=4096K

 

SYSUT1

DSN=IDF.PROD.xxxxxx

 

SYSUT2 Pioneer HLQ

DNS=PIONEER.

 

SYSUT2 Voyager HLQ

DNS=VOYAGER.

 

Note: Each Step has a SYSUT1 and a SYSUT2.

   

Table 2-5 lists the IEBCOPYL variables, corresponding sample values, and site values.

Table 2-5 Pioneer and Voyager IEBCOPYL Files

IEBCOPYL Variables Sample Values Site Values

Jobcard

//IEBCOPYL JOB SYSTEMS,MSGLEVEL=(1,1),

// MSGCLASS=X,CLASS=A,PRTY=8,

// NOTIFY=&SYSUID,REGION=4096K

 

INDD

DSN=IDF.PROD.LINKLIB

 

OUTDD

DSN=YOUR.LPALIB

 

Table 2-6 lists the IEBCOPYP variables, corresponding sample values, and site values.

Table 2-6 Pioneer and Voyager IEBCOPYP Files

IEBCOPYP Variables Sample Values Site Values

Jobcard

//IEBCOPYP JOB SYSTEMS,MSGLEVEL=(1,1),

// MSGCLASS=X,CLASS=A,PRTY=8,

// NOTIFY=&SYSUID,REGION=4096K

 

INDD1

DSN=IDF.PROD.PARMLIB

 

OUTDD1

DSN=YOUR.PARMLIB

 

Table 2-7 lists the IEBCPYPR variables, corresponding sample values, and site values.

Table 2-7 Pioneer and Voyager IEBCPYPR Files

IEBCPYPR Variables Sample Values Site Values

Jobcard

//IEBCPYPR JOB SYSTEMS,MSGLEVEL=(1,1),

// MSGCLASS=X,CLASS=A,PRTY=8,

// NOTIFY=&SYSUID,REGION=4096K

 

INDD2

DSN=IDF.PROD.PROCLIB

 

OUTDD2

DSN='YOUR HLQ.PROCLIB

 

Table 2-8 lists the PIONEER & VOYAGER STC, corresponding sample values, and site values.

Table 2-8 Pioneer & Voyager STC Files

PIONEER & VOYAGER STC Sample values Site Values

PARMFLE

for Pioneer STC

DSN=PIONEER.CONTROL.FILE

 

PARMFLE for Voyager STC

DSN=VOYAGER.CONTROL.FILE

 

Table 2-9 lists the MISCELLANEOUS names corresponding sample values, and site values.

Table 2-9 MISCELLANEOUS Names

MISCELLANEOUS Sample Values Site Values

SYSID

SYSTEMNAME or ADCD

 

CREATDSN:

//CREATDSN JOB SYSTEMS,MSGLEVEL=(1,1),
//   MSGCLASS=X,CLASS=A,PRTY=8,
//       NOTIFY=&SYSUID,REGION=0K
//STEP1    EXEC PGM=IEFBR14
//*-----------------------------------
//* CREATE PIONEERS RECONOUT -DD
//*        USED FOR INTERNAL RECONS FILE
//*-----------------------------------
//INDD1    DD   DSN=YOURHLQ.RECON.FILE,
//             DCB=(DSORG=PS,RECFM=FB,LRECL=90,BLKSIZE=27000),
//             UNIT=SYSDA,SPACE=(CYL,50),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX
//*-----------------------------------
//* CREATE PIONEERS LISTINR  -DD
//*        OUTFILE OF INTERNAL IDCAMS EXECUTION
//*----------------------------------- 
//INDD2    DD   DSN=YOURHLQ.ALIAS.LSTOUT,
//             DCB=(DSORG=PS,RECFM=VBA,LRECL=133,BLKSIZE=26300),
//             UNIT=SYSDA,SPACE=(CYL,5),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX
//*-----------------------------------
//* CREATE VOYAGER  CACHESAV  -DD
//*-----------------------------------
//INDD3    DD   DSN=YOURHLQ.CACHESAV.FILE,
//             DCB=(DSORG=PS,RECFM=FB,LRECL=112,BLKSIZE=27888),
//             UNIT=SYSDA,SPACE=(CYL,5),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX 
//*-----------------------------------
//* CREATE PIONEERS PARMFLE  -DD
//*-----------------------------------
//INDD4    DD   DSN=YOURHLQ.CONTROL.FILE,
//             DCB=(DSORG=PS,RECFM=F,LRECL=80,BLKSIZE=80),
//             UNIT=SYSDA,SPACE=(TRK,5),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX
//*-----------------------------------------------
//* CREATE PIONEERS SYSTSPRT -DD
//*        USED FOR INTERNAL CALLED REXX CLISTS
//*        OUTPUT FILE
//*----------------------------------------------- 
//INDD5    DD   DSN=YOURHLQ.REXXOUT.FILE,
//             DCB=(DSORG=PS,RECFM=FB,LRECL=121,BLKSIZE=27951),
//             UNIT=SYSDA,SPACE=(CYL,80),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX
//* CREATE PIONEERS FULLIMPU -DD
//*        OUTPUT OF FULL RECONS USERIDS EXECUTION
//*-----------------------------------------------
//INDD6    DD   DSN=YOURHLQ.IMPORTU.FILE
//             DCB=(DSORG=PS,RECFM=FB,LRECL=121,BLKSIZE=27951),
//             UNIT=SYSDA,SPACE=(CYL,100),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX
//*-----------------------------------------------
//* CREATE PIONEERS FULLIMPG -DD 
//*        OUTPUT OF FULL RECONS GROUPS  EXECUTION 
//*----------------------------------------------- 
//INDD7    DD   DSN=YOURHLQ.IMPORTG.FILE
//             DCB=(DSORG=PS,RECFM=FB,LRECL=121,BLKSIZE=27951),
//             UNIT=SYSDA,SPACE=(CYL,100),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX
//*-----------------------------------------------
//* CREATE VOYAGERS PARMFLE  -DD
//*-----------------------------------------------
//INDD8    DD   DSN=YOURHLQ.CONTROL.FILE,
//             DCB=(DSORG=PS,RECFM=F,LRECL=80,BLKSIZE=80),
//             UNIT=SYSDA,SPACE=(TRK,5),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX
//*-----------------------------------
//* CREATE PIONEERS IDCAMSD  -DD
//*-----------------------------------
//INDD9   DD   DSN=YOURHLQ.IDCAMS.CTL,
//             DCB=(DSORG=PS,RECFM=F,LRECL=80,BLKSIZE=80),
//             UNIT=SYSDA,SPACE=(TRK,5),DISP=(NEW,CATLG),
//             VOL=SER=XXXXXX                     

See Appendix D for information about the relationships between the INDDs in CREATDSN and the DDs used for Pioneer and Voyager.

The purpose of the Pioneer (DDs) and the files that were loaded by CREATDSN are also described.

LOADDSN:

//LOADDSN JOB SYSTEMS,MSGLEVEL=(1,1),
// MSGCLASS=X,CLASS=A,PRTY=8,
// NOTIFY=&SYSUID,REGION=4096K
//STEP1 EXEC PGM=IEBGENER
//SYSUT1 DD DSN=IDF.PROD.JCLLIB(PSAMPLE),DISP=SHR
//SYSUT2 DD DSN=PIONEER.CONTROL.FILE,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY 
//STEP2   EXEC PGM=IEBGENER
//SYSUT1 DD DSN=IDF.PROD.JCLLIB(VSAMPLE),DISP=SHR
//SYSUT2 DD DSN=VOYAGER.CONTROL.FILE,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY

See Appendix B for the information about the relationships between the DSNs in each step in the LOADDSN member and the file contents that are loaded into Pioneer's datasets.

The following is the IEBCOPYL member:

//IEBCOPYL JOB SYSTEMS,MSGLEVEL=(1,1),
// MSGCLASS=X,CLASS=A,PRTY=8,
// NOTIFY=&SYSUID,REGION=4096K
//* ------------------------------- *
//* COPIES RECON EXITS INTO LPA LIB *
//* ------------------------------- *
//MODUCPY1 EXEC PGM=IEBCOPY
//INDD DD DSN=IDF.PROD.LINKLIB,DISP=SHR
//OUTDD DD DSN=YOUR.LPALIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
COPY INDD=((INDD,R)),OUTDD=OUTDD
 S M=((LOGPWX01,ICHPWX01,R))
 S M=((LOGRIX02,ICHRIX02,R))
/*

This following is the IEBCOPYP member:

//IEBCOPYP JOB SYSTEMS,MSGLEVEL=(1,1),
// MSGCLASS=X,CLASS=A,PRTY=8, 
// NOTIFY=&SYSUID,REGION=4096K 
//* --------------------------------------- *
//* COPIES PROG01 APF MEMBER AND IRREVX01 *
//* INTO USER PARMLIB * 
//* --------------------------------------- *
//PARMCPY EXEC PGM=IEBCOPY 
//INDD1 DD DSN=IDF.PROD.PARMLIB,DISP=SHR
//OUTDD1 DD DSN=YOUR.PARMLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD * 
 COPY INDD=((INDD1,R)),OUTDD=OUTDD1
 S M=PROG01
 S M=PROG75
 S M=PROG76
/*
 

This following is the IEBCPYPR member:

//IEBCPYPR JOB SYSTEMS,MSGLEVEL=(1,1),
// MSGCLASS=X,CLASS=A,PRTY=8,
// NOTIFY=&SYSUID,REGION=4096K
//JCLCPY EXEC PGM=IEBCOPY 
//INDD2 DD DSN=IDF.PROD.PROCLIB,DISP=SHR
//OUTDD2 DD DSN='YOUR HLQ.PROCLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
 COPY INDD=((INDD2,R)),OUTDD=OUTDD2
 S M=VOYAGER
 S M=PIONEER
/*

2.2.5 Submitting Batch Job Streams

For submitting batch job streams to z/OS for execution and verify jobs completed successfully, after the jcl files have been edited to reflect the settings for the target environment, the jcl needs to be submitted for batch processing, perform the following steps:

  1. Submit the jobs from the screen where the members of the JCLLIB were displayed.

  2. Type SUBMIT to the left of the member you want to submit for processing.

  3. Press Enter to verify that the jobs have completed successfully.

    If there are any errors when submitting a job, fix the errors in the job and resubmit the job.

Surrounding text describes idf_upload20.gif.

2.2.6 Activating and Loading the Exits

To activate and loading the Exits:

  1. Submit the job IEBCOPYP, which copies the IdF PROGxx members to an installation defined parameter library. These members were PROGID, PROG75, and PROG76.

    In the system defined parameter library, member PROG75 contains the following Dynamic Exit definition:

    EXIT,ADD, EXITNAME=IRREVX01,MODNAME=LOGEVX01,DSNAME=IDF.LINKLIB
    

    When you submitted the job IEBCOPYL, it copied the two exits into the target LPA library for you.

  2. To load the new exits (ICHPWX01 and ICHRIX02), make the z/OS to be IPL.

    The following screen shot shows the z/OS Syslog during the IPL and RAC exit activation.

    Note:

    The RACF message ICH508I indicates that the exits were loaded properly.

    Surrounding text describes idf_upload21.gif.

    Activate the IRREVX01 exit by running the console command SET PROG=75 (or T PROG=75). When in SDSF use a / in front of the command (/T PROG=75), depending on whether the RACF has the proper authority and SDSF authority to issue these commands. IRREVX01 can also be activated via a AUTOCMD member in the SYS1.PARMLIB library.

  3. PROG=75

    Surrounding text describes idf_upload22.gif.
  4. To determine if the IRREVX01 exit is active, issue the command below:

    'D PROG,EXIT,EXITNAME=IRREVX01'
    
    Surrounding text describes idf_upload23.gif.
  5. Set APF authorization for Pioneer and Voyager with PROGID as follows:

    1. Verify that the LPA library containing the exits are in the LPA and have been added to the LPALSTxx member of IEASYSXX.

    2. Start member of Z/OS, usually contained within the SYS1.PARMLIB.

      The executable code (IBM z/OS loadlibs) of Pioneer and Voyager must be APF authorized. This can be achieved by running a dynamic set command(T PROG=ID) or by placing the installation loadlib containing Pioneer and Voyager in the IBM z/OS link list. In order to refresh the LPA library, IPL the IBM z/OS system.

      IBM® provides the PROGxx parmlib member as an alternative to IEAAPFxx, which allows you to update the APF list dynamically and specify an unlimited number of APF-authorized libraries. IBM suggests that you use PROGxx to specify the APF list (regardless of whether you plan to take advantage of the dynamic update capability). The system will process IEAAPFxx and PROGxx if both parameters are specified. If you decide to use PROGxx only, then remove APF=xx system parameters from IEASYSxx and IEASYS00.

2.2.7 Creating a RACF UserID for Pioneer and Voyager with Permissions

To create a RACF UserID for Pioneer and Voyager with permissions:

  1. Add the user that will be running the Pioneer and Voyager STCs. It will need to have Special permission.

    Surrounding text describes idf_upload24.gif.
  2. Modify/alter the user to add all the other privileges and segment definitions.

    Surrounding text describes idf_upload25.gif.
  3. Check the definition information about the user.

    Surrounding text describes idf_upload26.gif.
    Surrounding text describes idf_upload27.gif.

2.2.8 Adding Pioneer/Voyager to the Facility Class Profiles (BPX and IRR)

To add a Pioneer or Voyager to the facility class profiles:

  1. Now add the user (which runs the Pioneer/Voyager STCs) to the Facility class profiles. If the IRR.RADMIN profile doesn't exist you need to define it with the RDEFINE command as follows:

    RDEFINE FACILITY IRR.RADMIN.* UACC(NONE) <or>
    RDEFINE FACILITY IRR.RADMIN.xxxxxxx UACC(NONE)
    (Where the xxxxxxx is the RACF command, please see IBM's Security Server Manual for these commands and permissions)
    

    The userID must be authorized to use the new FACILITY class profiles with the PERMIT command.

    PERMIT IRR.RADMIN.* CLASS(FACILITY) ID(START2) ACCESS(READ)
    <or>
    PERMIT IRR.RADMIN.xxxxxx CLASS(FACILITY) ID(START2) ACCESS(READ)
    (where xxxxxx is the RACF command from the above rdefine command)
    PERMIT BPX.DAEMON CLASS(FACILITY) ID(START2) ACCESS(READ) 
    
  2. Display the information for the Facility class irr.radmin.* with the RLIST command.

    Surrounding text describes idf_upload28.gif.
    Surrounding text describes idf_upload29.gif.
  3. Display the information for the Facility class bpx.daemon with the

    RLIST command.
    
    Surrounding text describes idf_upload30.gif.
    Surrounding text describes rlist_access.gif.

    Note:

    • The RACF userID that runs the Pioneer/Voyager STCs must have special privilege set, which permits Pioneer to issue any RACF commands that a normal central site RACF administrator would issue.

    • This RACF userID needs to be able to perform all functions for IRR.RADMIN so we use IRR.RADMIN.*.

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

    • To pass the IRR.RADMIN call to IRRSEQ00 the RACF API subsystem must be up. To add it and activate it:

    • Create or add to IEFSSN00 member of 'SYS1.PARMLIB' the following statements:SUBSYS SUBNAME(RACF)INITRTN(IRRSSI00) INITPARM('#')Then z/OS must be IPL'ed to activate this member. Most installations all ready have the RACF API activate.

2.2.9 Testing the Installation

Review this manual for the control file parameters for Voyager and Pioneer and change the configuration files (Pioneer and Voyager STC PARMFLE DDs) for the installation. Consult the Identity Manage Installation Staff for TCPIP PORT addresses and TCPIP Addresses for both Voyager and Pioneer. Also consult the IDM staff for the VOYAGER_ID= variable explained later in this manual in the Voyager parameters section.

To test the installation:

  1. IPL the system to bring in the new LPA library modules.

  2. Check that the exit modules have been loaded.

    The following are the list of the members in USER.PROCLIB.

    Surrounding text describes user_proclb.gif.

    Note:

    • The STARTUP and WRAPUP functions are contained within Voyager. These functions are not used directly anymore. Their functionality has been incorporated into Voyager.

    • The STARTUP and WRAPUP functions are executed ONLY in case of an emergency and then with the guidance of the product support team.

  3. Execute Voyager:

    1. Start the Voyager Agent by running "S VOYAGER" from the console or SDSF in TSO. By adding the STC procedure for VOYAGER inside a Job Scheduler is another way you can start the task. To quiesce VOYAGER, issue "F VOYAGER (if this is the STCNAME),SHUTDOWN. Voyager will close the TCPIP sessions, close any open files and delete the subpool that was allocated. To insure no message lost, issue only a "F VOYAGER,SHUTDOWN" to Voyager a "C VOYAGER" can cause messages to be lost. Voyager is a 'single thread' or "single task" application. A F or Modify command may take some time to take effect depending on Voyager activity.

    Voyager control file used for testing:

    SUBPOOL_SIZE=1000K
    TCPN=TCPIP
    IPAD=192.168.1.100
    * IPAD=RACF.LEGACYIDM.COM
    PORT=5097
    CSDATA=N
    VOYAGER_ID=TESTVGER
    CACHE_DELAY=002
    AUDIT_LOG=YES
    PIONEER_ID=PIONEER
    

    See Appendix H for description of the Voyager control file parameters.

    Surrounding text describes idf_upload32.gif.
    Surrounding text describes app_pram.gif.

    JCL for the Voyager Started Task (STC):

    (Shown below is a Voyager STC using 'Voyager' as a High-Level Qualifier, this is just an example).

    //VOYAGER PROC
    //STEP1 EXEC PGM=VOYAGERX,REGION=0M,TIME=1440
    //STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB <--- IF NOT IN LINKLIST
    //CACHESAV DD DSN=VOYAGER.CACHESAV.FILE.DISP=SHR
    //DEBUGOUT DD SYSOUT=*
    //SYSOUT DD SYSOUT=*
    //AUDTLOG DD SYSOUT=*
    //PARMOUT DD SYSOUT=*
    //PARMFLE DD DISP=SHR,DSN=VOYAGER.CONTROL.FILE
    //SYSPRINT DD SYSOUT=*
    //SYSUDUMP DD SYSOUT=X
    // 
    

    Executing Voyager (STC log):

    Note:

    The boldfaced items are the new STARTUP functions now built into Voyager).

    11/28/12 15:27:40:68 IDMV000I - VOYAGER RECONCILATION  AGENT STARTING
    11/28/12 15:27:40:71 IDMV000I - VOYAGER IS EXECUTING  FROM AN APF AUTHORIZED LIBRARY
    11/28/12 15:27:40:72 IDMV000I - VOYAGER FOUND      RACF SECURITY SUBSYSTEM
    11/28/12 15:27:40:79 IDMV070I - VOYAGER PARMFLE    IS NOW OPEN
    11/28/12 15:27:40:79 IDMV070I - VOYAGER PARMOUT    IS NOW OPEN
    11/28/12 15:27:40:82 IDMV071I - VOYAGER PARMFLE    IS NOW CLOSED
    11/28/12 15:27:40:83 IDMV070I - VOYAGER AUDTLOG    IS NOW OPEN
    11/28/12 15:27:40:83 IDMV071I - VOYAGER PARMOUT    IS NOW CLOSED
    11/28/12 15:27:40:84 IDMV202E - VOYAGER NO STORAGE TOKEN  FOUND
    11/28/12 15:27:40:85 IDMV000I - VOYAGER SUBPOOL  INITIALIZATION OK
    11/28/12 15:27:40:87 IDMV003I - VOYAGER SP231  ALLOCATED OK
    11/28/12 15:27:40:88 IDMV001I - VOYAGER SUBPOOL  SIZE IS:    7500 K
    11/28/12 15:27:40:90 IDMV002I - VOYAGER SUBPOOL  WILL HOLD :    76800 MESSAGES
    11/28/12 15:27:40:91 IDMV004I - VOYAGER STORAGE TOKEN BUILT OK
    11/28/12 15:27:40:93 IDMV152I - VOYAGER IP CONNECT REQUEST 192.168.1.10
    11/28/12 15:27:40:93 IDMV004I - VOYAGER STORAGE TOKEN BUILT OK
    11/28/12 15:27:40:93 IDMV006I - VOYAGER BUILD      LEVEL IS AT        201211152017-4.7.0.5
    11/28/12 15:27:40:93 IDMV007I - ORACLE BUILD      LEVEL IS AT     09.00.04.22
    11/28/12 15:27:40:96 IDMV008I - VOYAGER SUBPOOL   100 BYTE VERSION
    11/28/12 15:27:40:97 IDMV009I - VOYAGER DETECTS  (TCPIP)JOBNAME     TCPIP
    11/28/12 15:27:40:99 IDMV010I - VOYAGER DETECTS  (TCPIP)IP ADDRESS   192.168.1.10
    11/28/12 15:27:40:99 IDMV011I - VOYAGER DETECTS   (TCPIP)IP PORT    5097
    11/28/12 15:27:41:02 IDMV019I - VOYAGER DETECTS   DEBUGGING IS      OFF
    11/28/12 15:27:41:03 IDMV021I - VOYAGER DETECTS   COUNTRY CODE OF   US
    11/28/12 15:27:41:05 IDMV012I - VOYAGER DETECTS   ENCRYPTION IS     ON
    11/28/12 15:27:41:07 IDMV017I - VOYAGER DETECTS   ENCRYPTION KVER  200610
    11/28/12 15:27:41:14 IDMV026I - VOYAGER INITIALIZATION OF PTON WAS SUCCESSFUL
    11/28/12 15:27:41:21 IDMV027I - VOYAGER CONNECTED TO GATEWAY SERVER WAS SUCCESSFUL
    11/28/12 15:27:41:23 IDMV025I - VOYAGER ACCEPTING    MESSAGES ON        
    11/28/12 15:27:41:28 IDMV015I - VOYAGER DETECTS     CACHE FILE OPENED  OK
    

    Execute Voyager (PARMSOUT log):

    11/28/12 15:27:40:79 IDMV400I   *PARM* - * PARMFLE * OPEN
    11/28/12 15:27:40:79 IDMV400I   *PARM* - SUBPOOL_SIZE=7500K
    11/28/12 15:27:40:79 IDMV400I   *PARM* - TCPN=TCPIP
    11/28/12 15:27:40:79 IDMV400I   *PARM* - * IPAD=192.168.1.10
    11/28/12 15:27:40:79 IDMV400I   *PARM* - IPAD=192.1.10.102
    11/28/12 15:27:40:79 IDMV400I   *PARM* - * IPAD=RACF.LEGACYIDM.COM
    11/28/12 15:27:40:79 IDMV400I   *PARM* - PORT=5097
    11/28/12 15:27:40:79 IDMV400I   *PARM* - DEBUG=N
    11/28/12 15:27:40:80 IDMV400I   *PARM* - ESIZE=16
    11/28/12 15:27:40:80 IDMV400I   *PARM* - * DELAY=00
    11/28/12 15:27:40:80 IDMV400I   *PARM* - * STARTDELAY=10
    11/28/12 15:27:40:80 IDMV400I   *PARM* - * PRTNCODE=SHUTRC
    11/28/12 15:27:40:80 IDMV400I   *PARM* - CSDATA=N
    11/28/12 15:27:40:80 IDMV400I   *PARM* - VOYAGER_ID=TESTVGER
    11/28/12 15:27:40:80 IDMV400I   *PARM* - CACHE_DELAY=000
    11/28/12 15:27:40:80 IDMV400I   *PARM* - AUDIT_LOG=YES
    11/28/12 15:27:40:83 IDMV400I   *PARM* - ALL PARMS GOOD
    
  4. Starting Pioneer:

    Start the Pioneer Agent by running "S PIONEER" from the console or by running /S PIONEER in SDSF under TSO. Adding the STC procedure for PIONEER inside a Job Scheduler is another way you can start the task.

    Pioneer Control file used for testing:

    TCPN=TCPIP
    IPAD=0.0.0.0
    PORT=5697
    DEBUG=N
    ESIZE=16
    LPAR=ZPDT-112
    POST_PROC_ALIAS=T
    IDLEMSG=N
    DEBUGOUT=SYSOUT,CLASS(S)
    SPIN_CLASS=K
    AUDIT_LOG=YES
    

    See Appendix H for information about Pioneer control file parameter descriptions.

    Surrounding text describes idf_upload33.gif.
    Surrounding text describes piocont.gif.

    JCL for the Pioneer Started Task (STC)

    (As of Oracle Adapter Release 4.7.0.5)

    (Shown below is a Pioneer STC using 'Pioneer' as a High-Level Qualifier, this is just an example).

    //PIONEER EXEC PGM=PIONEERX,REGION=0M,TIME=1440
    //JCLOUTP DD SYSOUT=* 
    //PARMFLE DD DISP=SHR,DSN=PIONEER.CONTROL.FILE
    //SYSTSPRT DD DISP=SHR,DSN=PIONEER.REXXOUT.FILE
    //GRPS DD DUMMY
    //AUDTLOG DD SYSOUT=*
    //DEBUGOUT DD SYSOUT=*
    //SYSEXEC DD DISP=SHR,DSN=PIONEER.REXX.CLISTS 
    //RECONJCL DD DISP=SHR,DSN=PIONEER.RECON.LIBRARY
    //RECONOUT DD DISP=SHR,DSN=PIONEER.RECON.FILE 
    //FULLIMPU DD DISP=SHR,DSN=PIONEER.IMPORTU.FILE
    //FULLIMPG DD DISP=SHR,DSN=PIONEER.IMPORTG.FILE
    //IDCAMSD  DD DISP=SHR,DSN=PIONEER.IDCAMS.CTL
    //LISTINR DD DISP=SHR,DSN=PIONEER.ALIAS.LSTOUT,
    // DCB=(RECFM=VB,LRECL=137)
    //SYSPUNCH DD SYSOUT=(*,INTRDR)
    //SYSPRINT DD SYSOUT=*
    //SYSOUT DD SYSOUT=*
    //SYSUDUMP DD SYSOUT=X
    //
    

    Executing Pioneer(STC log):

    0090  $HASP373 PIONEER  STARTED
    0281  IEF403I PIONEER - STARTED - TIME=19.21.51
    0090  IDMP000I - PIONEER STARTING
    0090  IDMP001I - PIONEER INPUT    PARAMETERS ARE   OK
    0090  IDMP002I - PIONEER DETECTS  IDF-BUILD        201212061406-4.7.0.5
    0090  IDMP002I - PIONEER DETECTS  ORACLE BUILD     09.00.04.22
    0090  IDMP002I - PIONEER DETECTS  AUDIT LOG IS NOW: ACTIVE
    0090  IDMP003I - PIONEER DETECTS  TCPIP JOBNAME    TCPIP
    0090  IDMP004I - PIONEER DETECTS  TCPIP IP ADDRESS 0.0.0.0
    0090  IDMP005I - PIONEER DETECTS  TCPIP IP PORT    5697
    0090  IDMP006I - PIONEER DETECTS  DEBUGGING IS     NOT ACTIVE
    0090  IDMP011I - PIONEER DETECTS  CPUID            01B0DB1090
    0090  IDMP012I - PIONEER DETECTS  SYSPLEX SYSNAME  ADCD
    0090  IDMP013I - PIONEER DETECTS  LPARNAME AS      ZPDT-112
    0090  IDMP014I - PIONEER DETECTS  COUNTRY CODE OF  US
    0090  IDMP009I - PIONEER DETECTS  ENCRYPTION       ENABLED
    0090  IDMP016I - PIONEER APF LIBRARY  IS GOOD
    0090  IDMP031I - PIONEER GETCLIENTID WAS SUCCESSFUL
    0090  IDMP032I - CLIENT  NAME IS PIONEER
    0090  IDMP033I - CLIENT  TASK IS PIONEERX
    0090  IDMP035I - PIONEER BIND SOCKET WAS SUCCESSFUL
    0090  IDMP036I - PIONEER LISTENING PORT IS  5697
    0090  IDMP037I - PIONEER LISTENING ADDRESS IS 0.0.0.0
    0090  IDMP038I - PIONEER LISTEN SOCKET CALL WAS  SUCCESSFUL
    0090  IDMP038A - PIONEER IS READY FOR MESSAGES
    
  5. Stop the started tasks:

    The operator interface is named POLLOPER in both Voyager and Pioneer. Both STCs are Single thread and commands are passed to them via a z/OS modify("F") command.

    Pioneer can be controlled by commands via Operator Interface with the commands given in Table 2-10.

    Table 2-10 Pioneer Commands via Operator Interface

    Pioneer Commands Description

    F PIONEER,SHUTDOWN

    Shuts Down Pioneer

    F PIONEER,STATUS

    Heartbeat message

    F PIONEER,DEBUG=Y

    Turns on Debugging

    F PIONEER,DEBUG=N

    Turns off Debugging


Functions:

Surrounding text describes idf_upload35.gif.
Surrounding text describes pion.gif.

Table 2-11 lists Voyager Commands via Operator Interface.

Table 2-11 Voyager Commands via Operator Interface

Voyager Commands Description

F VOYAGER,SHUTDOWN

Shuts Down Voyager

F VOYAGER,STATUS

Heartbeat message

F VOYAGER,DEBUG=Y

Turns on Debugging

F VOYAGER,DEBUG=N

Turns off Debugging

F VOYAGER,IPAD=999.999.999.999,PORT=99999

Swaps LDAP Gateway


Note:

The commands in the following screen shots are not required if DNS is used.

Surrounding text describes voyg_shtdwn.gif.
Surrounding text describes vyg_shtd.gif.