Installation Procedure - mfx - 3.1

The procedure for installing MFX with SMP/E consists of several steps. It also includes suggestions for testing MFX and BetterGener.   

STEP 1: Download MFX and Load the Sample JCL Library                  

This step explains how to access the tersed installation files from the Precisely secure FTP server, upload them to your mainframe, and unpack the tersed data sets.

1. Open the Syncsort™ MFX page on the Precisely Support website and click Software Download in the Release 3.1 section to download the base product to your machine.
2. Extract the contents of the MFX310_Install.zip file to a local directory. This includes a README with instructions for “Transferring Syncsort™ MFX SMP/E files to Mainframe” and PDFs of the Syncsort™ MFX documentation.
3. Upload the SS3100.BT541.SIS31.README.TXT to your mainframe, modifying the job control statement with your local system’s credentials. The Precisely secure FTP server will then transfer nine tersed hlq.SSP.BT541 files and the hlq.SS.BT541.UPKSIS31.TXT file to your mainframe.
   Note: You can delete the hlq.SSP.BT541 files after completing the installation.
4. Modify and submit the JCL in the hlq.SS.BT541.UPKSIS31.TXT file according to the directions in the job to unterse the compressed files into these nine z/OS-formatted data sets:

   hlq.BT541.SYNSRT.BSSIC31.F1

   hlq.BT541.SYNSRT.BSSID31.F1

   hlq.BT541.SYNSRT.BSSIJ31.F1

   hlq.BT541.SYNSRT.BSSIL31.F1

   hlq.BT541.SYNSRT.BSSIP31.F1

   hlq.BT541.SYNSRT.BSSIZ31.F1

   hlq.BT541.SYNSRT.BSSIZ31.F2

   hlq.BT541.SYNSRT.R31.SMPMCShlq.BT541.SY

5. The sample JCL library named hlq.BT541.SYNSRT.SAMPLE.JCL contains the following the job members to proceed with the installation.

   MFXOPT	SS31CPR	SS31MKDR	SS31TST1
   SS31ACPT	SS31DDEF	SS31OMFX	SS31TST2
   SS31ALOC	SS31HALO	SS31OPTS	SS31TST3
   SS31ALOE	SS31HINT	SS31RECV	SS31TST4
   SS31APLY	SS31HPRC	SS31RNMS	SS31TST5
   SS31BN89	SS31INIT	SS31SVC	SS31TST6

STEP 2: Execute SYNCCPR       

Before continuing with the installation process, it is a good idea to take the time now to provide the necessary information to acquire your license key.   

In order to generate the appropriate license key, Precisely requires certain information about the machine on which MFX will be running. The SYNCCPR program produces a report with this information.

Review and submit SS31CPR in the sample JCL library to execute SYNCCPR. If you will be using MFX on multiple machines, submit SS31CPR on each machine.

After producing a report for each applicable machine, request your license keys by referring to the instructions given in Downloading a License Key File from Precisely Support section of appendix B.

STEP 3: Allocate Target and Distribution Libraries       

To allocate the target and distribution libraries needed to install MFX, edit and submit SS31ALOC   from the sample JCL library. Comments in the member will help you to add any information that is needed.   

STEP 4: Allocate SMP/E Libraries       

Modify and submit member SS31ALOE from the sample JCL library. This job allocates the CSI, LOG, LTS, MTS, PTS, STS, and SCDS data sets.   

STEP 5: Initialize SMP/E CSI       

Modify and submit member SS31INIT from the sample JCL library to initialize the newly created SMPCSI data set.   

STEP 6: Create a zFS Directory (Optional)

If you plan to create PDF, RTF, and HTML files using the OUTFIL facility in a Java environment, then modify and submit member SS31MKDR from the sample JCL library to create a zFS directory. Make sure you have the necessary access permissions to CREATE and WRITE for the designated directory on the z/OS UNIX system.

STEP 7: Create DDDEFs      

Modify and submit member SS31DDEF from the sample JCL library to create DDDEFs in the SMP/E zones.

STEP 8: RECEIVE the MFX Functions   

Modify and submit member SS31RECV from the sample JCL library to RECEIVE the MFX functions. Comments in the member will help you select the functions needed at your site.

STEP 9: Supply a Module Name for the MFX SVC       

Modify and submit SS31SVC from the sample JCL library to supply the MFX module name for the SVC. You must have the SVC number for MFX R3.1 to complete this step. For more information, see SVC Option.   

STEP 10: APPLY the MFX Functions      

Modify and submit member SS31APLY from the sample JCL library to APPLY the MFX functions.

STEP 11: Configure a Java Environment (Optional)

If you installed function BSSIJ31 and the APPLY step has successfully completed, you can access the zFS directory you created in the STEP 6: Create a zFS Directory (Optional) above, which unpacks and stores the package in the designated directory created in STEP 7. There are two subdirectories and one script file to unpack the package after installation.

If you plan to use 31-bit Java SDK release 8, you must code the full path of sshfsj6 in the SYNCHOME; directory and use sshfsj6X for 64-bit Java SDK release 8. If you plan to use Java Semeru V11 or later then use sshfsj6X as JAVA is 64-bit only from this version onwards.

The following example uses the 64-bit Java SDK for the run-time environment:

SYNCHOME=’/u/syncsort/mfx/sshfsj6X’

One of the directories will be specified for the SYNCHOME option in USERMODA and/or SS31OMFX described in the next step.

For the 64-bit Java SDK release 8, you must also set the JVM64 option to “YES” in USERMODA and/or SS31OMFX, as follows (for Release 11 and above option not required as 64-bit is implied):

JVM64=YES

If you do not install the BSSIJ31 function at installation time and would like to install this function, you need to do the following:

• Modify and submit options in STEP 6: Create a zFS Directory (Optional) above to create the zFS directory if it does not exist.
• Modify SMP/E SYNCTZFS DDDEF’s definition and submit the JCL stream if the zFS directory is different from installation default of /u/syncsort/mfx/.

  SET BDY (SYNCTGT).

  UCLIN.

  REP DDDEF(SYNCTZFS) PATH('/u/smpe/mfx/').

  ENDUCL.

STEP 12: Set and Install the MFX Options                   

The MFX options are the values that MFX uses as defaults when it executes. An explanation of each option is provided in chapter Default Options.

There are two methods that can be used to customize installation options for MFX.   

• The first method stores the installation options within the MFX load libraries. This method is appropriate when only one set of installation options is required.
• The second method has two options for storing the installation options in data sets that are independent of the MFX libraries, and allows more than one set of options. This method is appropriate when different LPARs require different options. It is also beneficial at sites where the MFX SMP/E libraries reside at a central location and there is a need to change options on an LPAR at a remote location that has only target libraries.

If you prefer not to store the data set name of your MFX options in the PARMLIB concatenation, as described in Method 2a below. You can use the ALTOPLIB sub-parameter of the MFXPRM statement to customize the installation options for MFX outside of SMP/E without using SYS1.PARMLIB, as described in Method 2b below.

If an MFX installation on a particular LPAR has both methods deployed, then the options deployed by Method 2a or Method 2b take precedence.

Method 1

This method is done entirely within SMP/E. To set options with this method, do the following:   

• Edit the values in member USERMODA in the sample JCL library. You must specify values for the SVC and KEY or KEYDSN options; otherwise these options will default to null values. Customize the values of the other options or take the values shown. A complete explanation of each option is given in chapter Default Options. 
• Modify and submit member SS31OPTS from the sample JCL library to RECEIVE and APPLY the sysmod that is in member USERMODA.   

Method 2a and Method 2b

Method 2a and 2b are done entirely outside of SMP/E. The SMPCSI, SMPPTS, SMPSCDS, SMPLTS, SMPMTS and SMPSTS do not have to be accessed.

Method 2a – Default Option PARMLIB

To set options with this method, do the following:   

• Review the JCL in member SS31OMFX in the sample JCL library. Comments in the member will help you add any information that is needed. The SS31OMFX job does an assembly and then a link edit of a set of option values and places the options into a load module. Carefully edit the option values in SS31OMFX as needed. For more detailed information, see chapter Default Options. Since you will execute this job multiple times, you should assign a unique name to the output of the link edit for each execution. Each SS31OMFX execution defines a unique set of option values that you can activate on a particular date, time or LPAR. This is why you must make the combination of the output library name plus module name unique for each SS31OMFX execution.
• In the SYS1.PARMLIB library (or a library in the PARMLIB concatenation), you must create a member named MFXPRMxx, where xx can be any two characters. You most likely will have multiple MFXPRMxx members. Each MFXPRMxx member will correspond to each output of your SS31OMFX execution. In the MFXPRMxx member, specify the unique name of the output load library and module name you have specified in job SS31OMFX. Each MFXPRMxx member contains just one line as follows,

  assigned.load.library.name(assigned_module_ name)

• In the SYS1.PROCLIB library (or a library in the PROCLIB concatenation), create a member named MFXOPT with the JCL below (note: you can copy the JCL directly from member MFXOPT in the sample JCL library to your newly created member in SYS1.PROCLIB). The MFXOPT JCL will run as a started task that executes the program named MFXPRMG. The MFXPRMG program resides in the SYNCPRMG target library. MFXPRMG must run as an authorized program and therefore the SYNCPRMG library must be APF-authorized. To temporarily make the SYNCPRMG library APF-authorized you can issue the following system command,

  SETPROG APF,ADD,DSNAME=SYNCSORT.MFX.R31.SYNCPRMG,SMS

  Program MFXPRMG searches the PARMLIB concatenation for the MFXPRMxx member whose name is passed in the PARM field. It opens and reads the assigned library/module in the MFXPRMxx member and makes these options available to all MFX applications until the started task is deactivated. The following is the MFXOPT JCL

  //MFXOPT    PROC

  //MFX1   EXEC PGM=MFXPRMG,PARM=’&MFXPRM’

  /STEPLIB    DD    DISP=SHR,DSN=SYNCSORT.MFX.R31.SYNCPRMG

• The system command to start MFXOPT is coded as follows,

  S MFXOPT,MFXPRM=’ACT,xx,r.r’

  where MFXPRM is the symbolic parameter in the JCL displayed in the previous item, ACT tells MFXPRMG this is an activation request (see DISP and DEACT requests further down), xx is the suffix of the MFXPRMxx PARMLIB member and r.r is the release of MFX.

  There are two ways to issue the start MFXOPT command. First, you can issue the command directly from the system console which starts MFXOPT immediately. The alternative, which will start MFXOPT after each IPL, is to cre­ate a new COMMNDxx member in SYS1.PARMLIB and place the START MFX­OPT command in it.

  The MFXOPT return codes are:   

  0 - The MFXOPT command was successfully executed.   

  8 - An error occurred during MFXOPT processing. Refer to the WER8nna MFXOPT message for more information.   

  12 - The MFXPRMG program was not executed from a START MFXOPT command. This type of invocation is not valid.

   You can display the source location of the options in effect by using the command:

  S MFXOPT,MFXPRM=’DISP’

  You can deactivate the options in effect by using the command:

  S MFXOPT,MFXPRM=’DEACT,3.1’    

See IBM’s z/OS MVS PLANNING: Operations for information about controlling who can issue the START MFXOPT command.

Method 2b – Default Option ALTOPLIB

If you prefer not to store the data set name of your MFX options in the PARMLIB concatenation, as described in Method 2a above. You can use the ALTOPLIB sub-parameter of the MFXPRM statement to customize the installation options for MFX outside of SMP/E. When using ALTOPLIB, you do not have to create a member in SYS1.PARMLIB named MFXPRMxx.

However, when you issue the START command for the MFXOPT started task, you will need to use the ALTOPLIB parameter on the MFXPRM statement to indicate the output load library and module name specified in job SS31OMFX.

The supported syntax is as follows:

S MFXOPT,MFXPRM='ACT,ALTOPLIB=dsn(member),3.1

S MFXOPT,MFXPRM='ACTIVATE,ALTOPLIB=dsn(member),3.1

These messages could reflect the possible use of ALTOPLIB as an alternative to a PARMLIB member: WER805A, WER806A, WER813I and WER815I.

 See IBM’s z/OS MVS PLANNING: Operations for information about controlling who can issue  the START MFXOPT command.   

STEP 13: Perform Installation Verification Testing             

After SS31OPTS has completed successfully or you have started MFXOPT, you should review and submit member SS31TST1 in the sample JCL library to confirm that your installation is complete up to this point. If you have chosen the KEYDSN option, you should create your key data set and place your license keys into it before running the verification test. For more information, see Appendix B, Using a Data Set for MFX License Keys.   

STEP 14: Allocate Global DSM’s History Data Set                  

Review and submit SS31HALO in the sample JCL library to allocate the history data set that will be used by global DSM.   

If MFX is running on more than one z/OS system image or logical partition (LPAR), you must allocate a history data set for each. SS31HALO contains descriptive comments, and it may be run as many times as necessary to allocate multiple history data sets. 

History data sets are not compatible with Extended address volumes (EAV), therefore parameter EATTR=NO must be specified when allocating the data set. Note that sort data sets like SORTIN/SORTOUT are EAV compatible.  

STEP 15: Initialize Global DSM’s History Data Set            

There are two ways to initialize the global DSM (GDSM) history data set, depending upon whether you are a first time user of GDSM or are converting from an earlier release of MFX in which you were also using GDSM.   

• If you are installing GDSM for the first time, you must initialize each history file you created in the prior step. To perform this initialization you must review and submit SS31HINT on each system where you have allocated a history data set. SS31HINT is a member in the sample JCL library, and it contains descriptive comments.
• If you have been using GDSM, you will want to preserve the history information developed by the earlier release of MFX. So instead of running SS31HINT, copy your existing history data set to the one you just allocated. If you have more than one history data set because of multiple system images, be sure that the input and output data sets for each copy operation are on the same system because each history data set needs specific information from the system on which it will be used. If the data set is copied from a different system, GDSM will terminate with a WER619A message.
• If the system identifier on your system changes, you must reinitialize the history data set on that system by running SS31HINT again. The system identifier is the SID parameter in member SMFPRMxx of SYS1.PARMLIB.      

STEP 16: Place SYNCG310 PROC into SYS1.PROCLIB      

Global DSM cannot be activated until you review and submit SS31HPRC to place the procedure SYNCG310 in SYS1.PROCLIB.SS31HPRC is a member in the sample JCL library, and it contains descriptive comments.   

STEP 17: Perform Production Validation Testing             

After the installation verification test (see STEP 13 above ) has run successfully and global DSM is ready for activation, you should perform a variety of production validation tests. To prepare for these tests, do the following:   

1. If you are using a type 3 SVC number in the range 200-255, update IEASVCxx in SYS1.PARMLIB with the SVC number being used for MFX. If you are using SVC 109 with the alternate routing code then do not update IEASVCxx.
2. Update LPALSTxx in SYS1.PARMLIB with the SYNCLPA data set name. If you want a system resident configuration of MFX, also place the SYNCRENT data set name in LPALSTxx.
3. Update IEAAPFxx in SYS1.PARMLIB with the SYNCAUTH and SYNCPRMG data set names. If member PROGxx in SYS1.PARMLIB is the preferred member used at your site to specify program libraries that are to receive APF authorization then add these names to the APF statement in PROGxx. If you have performed the optional procedure in STEP 6: Create a zFS Directory (Optional) above and if you are using an authorized Syncsort™ MFX version, then also APF-authorize the “libSSLib.so” which is present in your SYNCHOME directory. Go inside the SYNCHOME directory and issue the command that follows below. (APF authorization is mandatory for this DLL file if you are using an authorized Syncsort™ MFX version, irrespective of the Java version you are using.)

   extattr +a libSSLib.so

4. After updating SYS1.PARMLIB, IPL your system.

5. After the IPL, activate global DSM by issuing the START command for procedure SYNCG310. For complete information on activating global DSM, see Activating Global DSM with the START Command section.   

During production validation testing, you should run the key jobs at your installation in parallel with the current production runs of those jobs, and compare the results. You should also make the new release of MFX available to selected users. The jobstreams for both the parallel jobs and the selected user jobs should contain STEPLIBs linking them to your SYNCLINK library. (If you have not chosen a system resident configuration, the job streams should also contain a STEPLIB to the SYNCRENT library.)   

To confirm the Java environment is set up correctly, submit sample job SS31TST2 which will create a PDF. If you have elected to support the email facility then also submit SS31TST3 which will create a PDF and email it to a specified recipient.

STEP 18: Put MFX into Production 

To put the new release of MFX into production, you must place your SYNCLINK library in the link list concatenation. Depending on whether you are using member LNKLSTxx or PROGxx to define your link list concatenation, you must update one of these members in SYS1.PARMLIB. Add SYNCLNK to the APF-table (member PROGxx of PARMLIB), if you use LNKAUTH=APFTAB in IEASYSxx. Take note of these additional items:

1. If you decided to activate BetterGener, then you must ensure that the applications that execute program IEBGENER find the IEBGENER member in your SYNCLINK library ahead of the IBM IEBGENER in SYS1.LINKLIB. Choose one of the following methods to facilitate this:
   1. You can place the MFX SYNCLINK library ahead of SYS1.LINKLIB in your system link list concatenation, or
   2. You can keep SYS1.LINKLIB at the top of the link list but use UCLIN to change the target DDname of the LMOD IEBGENER from LINKLIB to some alternate name (e.g., GENRLIB). Allocate a ‘SYS1.GENRLIB’ library. Add a DDDEF in the operating system target zone for GENRLIB which points to ‘SYS1.GENRLIB’. Create a USERMOD whose FMID is the function that owns the IBM IEBGENER module in your level of the operating system, and then use a ++MOVE statement have SMP/E move IEBGENER and its alias to GENRLIB. This USERMOD must be received and applied in the operating system SMP/E zones. Then construct your link list concatenation so that ‘SYS1.LINKLIB’ is on top, followed somewhere below by ‘SYNCSORT.MFX.R31.SYNCLINK’ and followed somewhere below that is your new ‘SYS1.GENRLIB’, or
   3. You can keep SYS1.LINKLIB at the top of the link list but create a USERMOD whose FMID is the function that owns the IBM IEBGENER in your level of the operating system, and then use the ++RENAME statement to change the name of IBM’s IEBGENER to a new name, such as OLDGENER. This USERMOD must be received and applied in the operating system SMP/E zones.
   Note: If any installation has the SMP/E sysmod BSSIAnn where nn represents release 1.4 or earlier, you must RESTORE it out of the operating system zones because mixing release components will yield unpredictable results.
2. If you have chosen a non-resident configuration, then you must place your SYNCRENT library in the link list concatenation by adding SYNCRENT to the link list concatenation in LNKLSTxx or PROGxx. Add SYNCRENT to the APF-table (member PROGxx of PARMLIB), if you use LNKAUTH=APFTAB in IEASYSxx. Putting the SYNCRENT library in the link list concatenation presumes that you have not already chosen a resident configuration by putting SYNCRENT in the LPALSTxx as described in item number 2 in the prior step.

After refreshing LLA, submit the following test jobs in the sample JCL library as production verification tests. Submit sample job SS31TST4 to do a test sort. If you activated BetterGener, submit sample job SS31TST5. If you have an Syncsort PipeSort license, submit sample job SS31TST6. If sysmod BSSIP31 (DB2 Query Support) was installed, then either DB2 SYSADM or DB2 “BINDADD” and “CREATE IN” authority are needed to run the first sort on each DB2 subsystem.

For example, the userid has been granted the security privileges required to create “PACKAGES” and “PLAN” that other jobs will use, as follows:

GRANT BINDADD TO userid;

GRANT CREATE IN COLLECTION SY14PK8I TO userid;

GRANT CREATE IN COLLECTION SY14PK8E TO userid;

If you don’t want to use the default DB2 options to bind our SYNCSORT packages and plan, you can manually do the binding by using DBRM members which are included with your MFX installation files.

To bind our SYNCSORT packages and plan with options that are preferred at your site, review, modify, and submit member SS31BN89 from the sample JCL library. Member SS31BN89 is for users on DB2 version 8 and later versions of DB2.   

If you have a secured environment, the PLAN SY14PLV8 must be granted EXECUTE authorization for all users if the plan is not granted PUBLIC.   

STEP 19: ACCEPT the MFX Functions   

Modify and submit member SS31ACPT from the sample JCL library to ACCEPT the MFX functions.