Install Toad IBM DB2 z/OS Components

Follow these instructions to install Toad IBM DB2 z/OS Components on your IBM DB2 subsystem:

Note: Toad for z/OS IBM DB2 Components version number has been updated to 7.4 to reflect changes connected with the installation wizard. If you have version 7.2 previously installed on you z/OS subsystems you can carry on using them and do not need to re-install.

1. Connect to DB2 z/OS database.
2. Right-click the subsystem you want to install the components on and select Install Toad Components.

   

3. Complete the Specify the z/OS DB2 Subsystem page. Identify the subsystem on which you are installing the z/OS components. Review the following for additional information:

   Field	Description
   Subsystem ID	Enter the SSID for the DB2 subsystem on which you are installing the z/OS components. This should be the actual SSID, not an alias, for the subsystem.
   User ID	Enter your User ID.
   Password	Enter your password.
   DB2 exit library	Enter the fully qualified name of the DB2 exit library.
   DB2 load library	Enter the fully qualified name of the DB2 load library.

4. Complete the Specify Workload Manager (WLM) Environments for Toad page.

   Provide the names of the single-tasking and the multi-tasking WLM application environments used by IBM DB2 stored procedures and functions (These procedures and functions, in turn, are used by Toad for DB2). You can enter up to 32 characters for application environment names.

   Notes:

   • The two WLM application environments you specify must be reserved for exclusive use by Toad products, such as Toad for IBM DB2. Do not attempt to specify pre-existing WLM environments that are used for other applications.
   • The wizard allows up to 32 characters for an application environment name.
   • The multi-tasking WLM application environment must have at least 2 TCBs.

5. Complete the Provide Parameters for Creating the Toad Database page. Enter the following information to create the database required by the z/OS components. This database is created in the subsystem where you are installing the z/OS components.

   Note: This database must be reserved for exclusive use by Toad DB2 products, such as Toad for IBM DB2.

   Field	Description
   Subsystem	(Read-only) The SSID for the DB2 subsystem on which you are installing the z/OS components.
   Storage group	Enter the name of the storage group for the database objects.
   Tablespace bufferpool	Enter the name of the bufferpool for tablespaces in the database.
   Index bufferpool	Enter the name of the bufferpool for the indexes in the database.
   DB2 CLI collection ID	Specify the identifier of the collection used when the DB2 installation job DSNTIJCL was run. If you do not know this collection ID, consult your systems programmer.
   DB2 CLI plan name	Specify the name of the plan used when the DB2 installation job DSNTIJCL was run. If you do not know the plan name, consult your systems programmer.

6. Complete the Specify High Level Qualifiers (HLQs) for Toad z/OS Datasets page. Provide the high-level qualifier for the temporary datasets on the mainframe to which the installation files will be transferred initially and provide the high-level qualifier for the permanent location of the Toad IBM DB2 z/OS Components files once the installation JCL is executed on the mainframe.
7. Complete the Customize the JCL Job Card page. Edit it according to the z/OS remote server.
8. Complete the Customize Files for Transfer to the z/OS Subsystem page. Enter the local path and directory where you want the installation process to generate and temporarily store customized installation files on the Toad client machine.
9. Review Customization Results on the following page.

10. Complete the Transfer Toad Files to the z/OS Server page. Enter the IP address of the Target Server and click Next.

    Note:

    • You can skip the FTP transfer and transfer the files manually.

    

11. Complete the FTP Sign-on page. Review the following for additional information:

    Field	Description
    FTP Connection	Select the FTP connection from the list.
    Server address	Enter the IP address to which the files are transferred.
    Server port	Enter the server port.
    Username	Enter the mainframe user ID under which FTP transfers the files from the local directory on the Toad client machine to the temporary location on the mainframe.
    Password	Enter the password associated with this user ID.
    FTP files to the mainframe	Select this option to have the wizard installation process transfer the files from the temporary local directory on the Toad client machine to the temporary mainframe location. (The temporary mainframe location is identified by the high-level qualifier you specified for temporary datasets.) Note: The installation process uses the default Windows FTP program.
    Do not FTP files to the mainframe	Select this option if you intend to manually transfer the files from the temporary local directory on the Toad client machine to the temporary location on the mainframe.

12. Review FTP Results on the following page.
13. On the Review Finishing Installation Tasks page, review the README file stored in the local directory specified for the file transfer. This README file contains instructions for the additional tasks that must be performed on the mainframe to complete the z/OS components installation.
14. Select View remaining installation tasks at wizard completion. This README file contains instructions for the additional tasks you must perform on the mainframe to complete the z/OS components installation.

15. The wizard performs its tasks:

    • If you selected FTP files to the mainframe, the wizard generates the customized installation files in the temporary local directory on the Toad client machine, transfers all required installation files to the temporary datasets on the mainframe, and then closes.
    • If you selected Do not FTP files to the mainframe, the wizard generates the customized installation files at the temporary local directory on the Toad client machine and then closes.

    The README file containing the instructions needed to complete the installation on the mainframe is displayed. (If you did not specify to view the README file, locate the file in the subsystem _ID directory in the location you specified for Temporary Local Directory or in the Plugins\DB2\ZOS directory at your Toad for DB2 installation location.)

16. To complete the installation, perform the appropriate next step:
    • If you selected FTP files to the mainframe, follow the instructions in the README file to complete the installation on the mainframe.
    • If you selected Do not FTP files to the mainframe, you must manually transfer both certain files in the Plugins\DB2\ZOS directory at your Toad for IBM DB2 installation location and specific files stored at the temporary local location specified for Temporary local directory. See Manual Transfer of the z/OS Component Installation Files for more information. After the files are transferred, you are directed to perform the tasks described in the README to complete the installation on the mainframe.

Manual Transfer of the z/OS Component Installation Files

Why Manually Transfer the Installation Files?

The Toad IBM DB2 z/OS Components Installation wizard uses the default Windows FTP program to transfer the z/OS components installation files automatically from your Toad client machine to temporary datasets on the mainframe. However, you might need to transfer these files yourself for various reasons, such as:

• Windows FTP is not available.
• The wizard’s attempt to transfer the files failed.
• You selected the Do not FTP files to the mainframe option in the wizard.

Perform the Transfer Manually

The process of manually transferring the z/OS components installation files from the Toad client machine to the mainframe involves two main tasks:

• Manually allocating four temporary datasets on the mainframe
• Populating these datasets using a normal 3270 emulation product that supports TSO IND$FILE transfer

To transfer the z/OS components installation files manually

1. Using ISPF option 3.2, allocate the following datasets on the mainframe, where temphlq is the temporary high-level qualifier for the datasets:

   Dataset	Type	Allocation Specifications
   temphlq.LOADXMI	Sequential	recfm=fb,recsize=80,blksize=3120,space=(cyl,(25,15))
   temphlq.QCINST	Sequential	recfm=fb,recsize=80,blksize=3120,space=(trk,(10,5))
   temphlq.JCLLIB	PDS	recfm=fb,recsize=80,blksize=3120,space=(trk,(10,10,5))
   temphlq.QSMSG	Sequential	recfm=vb,recsize=1028,blksize=6144,space=(trk,(10,10))

   Note:temphlq.JCLLIB must be a partitioned dataset.

2. Use IND$FILE in binary mode to transfer the fileQuestDB2product_install\plugins\db2\zos\loadlib.xmi to temphlq.LOADXMI.

   Note: The QuestDB2product_install value is the directory where the Toad for DB2 client (or another Toad IBM DB2 product) is installed on your Windows machine. The temphlq value is the high-level qualifier for the temporary mainframe datasets you allocated. References to these variables are also found in steps that follow.

3. Use IND$FILE in ASCII mode to transfer the file QuestDB2product_install\plugins\db2\zos\qs.msg to temphlq.QSMSG.

4. Use IND$FILE in ASCII mode to transfer the following files from temp_local_directory\subsystem_id on your Toad client machine to the appropriate members of temphlq.JCLLIB.

   Note:temp_local_directory is the value you provided for Temporary local directory in the wizard to identify the temporary staging location for certain customized installation files on the Windows machine. The subsystem_id value is the SSID you specified in the wizard to identify the IBM DB2 subsystem on which you installing the z/OS components. The temphlq is the high-level qualifier for the temporary mainframe datasets you allocated. References to these variables are also found in steps that follow.

   Windows File Name	Dataset Member Name
   QPDSNAT	temphlq.JCLLIB(QPDSNAT)
   QCIVP	temphlq.JCLLIB(QCIVP)
   single_tasking_WLM_environment_name	temphlq.JCLLIB(single_tasking_WLM_environment_name)
   multi-tasking WLM environment_name	temphlq.JCLLIB(multi-tasking WLM environment_name)

   Note:single_tasking_WLM_environment_name and multi_tasking_ environment_name are the names of the WLM environments you specified in the wizard.

5. Use IND$FILE in ASCII mode to transfer the file temp_local_directory\subsystem_id\QCINST to temphlq.QCINST.
6. On the mainframe, run temphlq.QCINST. Use the instructions explained in the README file (located in temp_local_directory\subsystem_id or in QuestDB2product_install\plugins\db2\zos) to complete the installation process.

Appendix A: Objects Created by the Installation

The Toad IBM DB2 z/OS Components installation creates the following objects on the mainframe.

The Toad IBM DB2 z/OS Components installation creates the following objects on the mainframe.

Mainframe Objects

The z/OS components installation creates the following mainframe objects on your z/OS system. You need these objects to enable full Toad for IBM DB2 functionality for your IBM DB2 subsystem.

Note: The permhlq value is the high-level qualifier for the permanent datasets created by the installation.

IBM DB2 Objects

The installation process creates the following IBM DB2 for z/OS objects:

Appendix B: Edit QCIVP

This appendix describes how to customize the installation verification program QCIVP.

This appendix describes how to customize the installation verification program QCIVP.

Purpose of QCIVP

After the Toad IBM DB2 z/OS Components Installation wizard finishes its tasks, you must perform additional tasks on the mainframe to complete the installation. The last of these mainframe tasks is to run QCIVP, a mainframe installation verification program. QCIVP verifies that the IBM DB2 CLI has been installed and bound. It also runs a sample of the components’s procedures and functions and then writes the output to the QSPRINT message file.

Where QCIVP Resides

The dataset member permhlq.JCLLIB(QCIVP) contains the JCL for running QCIVP. This dataset is created during the z/OS components installation process you perform on the mainframe.

How to Run QCIVP

The instructions for running QCIVP, as well as for performing all other tasks required to complete the installation on the mainframe, are found in the README file for the Toad IBM DB2 z/OS Components installation. This README file is found in either location:

• The subsystem _ID directory in the location you specified for Temporary Local Directory in the Toad IBM DB2 z/OS Components Installation wizard
• The Plugins\DB2\ZOS directory under your Toad for DB2 installation directory.

Reasons for Editing QCIVP

Before running QCIVP, you might need to edit the program it if any of the following situations is valid:

• You want to enable application tracing while QCIVP is running so that a series of trace messages are written to a user-supplied file for every call to a CLI function for that job.
• In situations where two or more DB2 subsystems share the same exit library (and therefore share a common DSNHDECP member in the library), the default subsystem ID in DSNHDECP matches one of the subsystem IDs, but not the others. You need a mechanism for providing the correct IBM DB2 subsystem ID for connection to the subsystems whose IDs do not match the default SSID in DSNHDECP. You can accomplish this by coding a DSNAOINI override in QCIVP.

Edit QCIVP

Use the appropriate procedure to edit QCIVP:

• Turn on application tracing. See Enable Application Tracing for more information.
• Turn off application tracing.See Disable Application Tracing for more information.
• Turn on application tracing and change the default IBM DB2 SSID. See Enable Application Tracing and Change the Default DB2 SSID for more information.
• Change the default IBM DB2 SSID without turning on application tracing. See Change the Default DB2 SSID Without Enabling Application Tracing for more information.

Enable Application Tracing

Use the following procedure to edit QCIVP to enable application tracing for the duration of the QCIVP job.

Note: Enabling tracing for QCIVP does not affect the long-term results obtained from the WLM procedures.

To enable application tracing

1. Open permhlq.JCLLIB(QCIVP) in an ISPF EDIT session (where permhlq is the high-level qualifier for the permanent location where the z/OS component was installed).

2. Type NUM OFF at the EDIT session command line to turn off sequence numbering.

   Note: If you fail to turn sequence numbering off, errors can occur. Be aware that you might need to turn sequence numbering off each time you edit QCIVP.

3. Add the following cards to QCIVP:

   

4. Save your changes to QCIVP.
5. Exit the ISPF EDIT session.
6. Confirm that sequence numbering is truly turned off by opening permhlq.JCLLIB(QCIVP) in another ISPF EDIT session. There should be no sequence numbers in columns 73-80 for lines appearing between //DSNAOINI and the //* line.
7. Confirm that your square brackets translated correctly:
   1. Type FIND X ‘AD’ ALL in the command line, and press Enter.
   2. Make sure the FIND command locates all the left brackets.
   3. Type FIND X ‘BD’ ALL in the command line, and press Enter.
   4. Make sure the FIND command locates all right brackets.
   5. If FIND failed to located even one bracket, type HEX ON in the command line, press Enter, and then make the appropriate edits in HEX mode.
8. Save your changes to QCIVP.

Disable Application Tracing

Use the following procedure to edit QCIVP to disable application tracing for the duration of the QCIVP job.

To disable application tracing

1. Open permhlq.JCLLIB(QCIVP) in an ISPF EDIT session (where permhlq is the high-level qualifier for the permanent location where the z/OS component was installed).

2. Type NUM OFF at the EDIT session command line to turn off sequence numbering.

   Note: If you fail to turn sequence numbering off, errors can occur. Be aware that you might need to turn sequence numbering off each time you edit QCIVP.

3. Edit the following card to set APPLTRACE to zero, as shown in the following figure:

4. Save your changes to QCIVP.
5. Exit the ISPF EDIT session.
6. Confirm that sequence numbering is truly turned off by opening permhlq.JCLLIB(QCIVP) in another ISPF EDIT session. There should be no sequence numbers in columns 73-80 for lines appearing between //DSNAOINI and the //* line.
7. Confirm that your square brackets translated correctly:
   1. Type FIND X ‘AD’ ALL in the command line, and press Enter.
   2. Make sure the FIND command locates all the left brackets.
   3. Type FIND X ‘BD’ ALL in the command line, and press Enter.
   4. Make sure the FIND command locates all right brackets.
   5. If FIND failed to located even one bracket, type HEX ON in the command line, press Enter, and then make the appropriate edits in HEX mode.
8. Save your changes to QCIVP.

Enable Application Tracing and Change the Default DB2 SSID

Use the following procedure both to enable application tracing and to change the IBM DB2 SSID from the default value in the DSNHDECP to the actual IBM DB2 SSID for the subsystem on which you are installing the z/OS components.

To enable application tracing and change the default IBM DB2 SSID

1. Open permhlq.JCLLIB(QCIVP) in an ISPF EDIT session (where permhlq is the high-level qualifier for the permanent location where the z/OS component was installed).

2. Type NUM OFF at the EDIT session command line to turn off sequence numbering.

   Note: If you fail to turn sequence numbering off, errors can occur. Be aware that you might need to turn sequence numbering off each time you edit QCIVP.

3. Add the following cards to QCIVP, replacing all occurrences of XXXX with the appropriate non-default DB2 SSID:

4. Save your changes to QCIVP.
5. Exit the ISPF EDIT session.
6. Confirm that sequence numbering is truly turned off by opening permhlq.JCLLIB(QCIVP) in another ISPF EDIT session. There should be no sequence numbers in columns 73-80 for lines appearing between //DSNAOINI and the //* line.
7. Confirm that your square brackets translated correctly:
   1. Type FIND X ‘AD’ ALL in the command line, and press Enter.
   2. Make sure the FIND command locates all the left brackets.
   3. Type FIND X ‘BD’ ALL in the command line, and press Enter.
   4. Make sure the FIND command locates all right brackets.
   5. If FIND failed to located even one bracket, type HEX ON in the command line, press Enter, and then make the appropriate edits in HEX mode.
8. Save your changes to QCIVP.

Change the Default DB2 SSID Without Enabling Application Tracing

Use the following procedure to change the IBM DB2 SSID from the default value in the DSNHDECP to the actual IBM DB2 SSID for your subsystem without enabling application tracing.

To change the default DB2 SSID without enabling application tracing

1. Open permhlq.JCLLIB(QCIVP) in an ISPF EDIT session (where permhlq is the high-level qualifier for the permanent location where the z/OS component was installed).

2. Type NUM OFF at the EDIT session command line to turn off sequence numbering.

   Note: If you fail to turn sequence numbering off, errors can occur. Be aware that you might need to turn sequence numbering off each time you edit QCIVP.

3. Add the following cards to QCIVP, replacing all occurrences of XXXX with the appropriate non-default DB2 SSID:

4. Save your changes to QCIVP.
5. Exit the ISPF EDIT session.
6. Confirm that sequence numbering is truly turned off by opening permhlq.JCLLIB(QCIVP) in another ISPF EDIT session. There should be no sequence numbers in columns 73-80 for lines appearing between //DSNAOINI and the //* line.
7. Confirm that your square brackets translated correctly:
   1. Type FIND X ‘AD’ ALL in the command line, and press Enter.
   2. Make sure the FIND command locates all the left brackets.
   3. Type FIND X ‘BD’ ALL in the command line, and press Enter.
   4. Make sure the FIND command locates all right brackets.
   5. If FIND failed to located even one bracket, type HEX ON in the command line, press Enter, and then make the appropriate edits in HEX mode.
8. Save your changes to QCIVP.