Tutorial: DSNREXX

Prerequisites

To complete this tutorial, you need the following software in addition to Enterprise Developer:

• IBM's DB2 Database for Linux, UNIX, and Windows (LUW). See Additional Software Requirements for more information. You can download a version of DB2 to use in the tutorial from IBM's website - click here.
• Windows Software Development Kit (SDK) installed for your version of Windows. You can download the Windows 10 SDK from the Windows Dev Center website - click here.

Installing DB2

For the purposes of this tutorial you can install a copy of DB2 Express-C. The following points can help you install DB2 for use in this tutorial:

1. When prompted in the installation setup, select the typical installation type.
2. You do not need to save your settings in a response file, but this may be useful when using DB2 in the future.
3. Use the default installation directory.
4. Leave the default settings when you select the IBM SSH server installation folder and startup option.
5. Always secure your DB2 administration server with a strong password.
6. You do not need to configure the DB2 instances, use the default instance configuration.

Creating a DB2 LUW sample database

Catalog the sample database as an ODBC data source

If your sample database has not been cataloged as an ODBC data source, then perform the following steps:

1. From your Windows desktop, click Start or use the shortcut keys Ctrl+Esc. In the search field, type ODBC.
2. In the search results list, select ODBC Data Source Administrator (32-bit) or ODBC Data Sources (32-bit), depending on your version of Windows.

   This opens the 32-bit version of the ODBC Data Source Administrator tool.

3. Click System DSN tab.
4. Click Add.

   This opens the Create New Data Source dialog box.

5. Click IBM DB2 ODBC DRIVER.
6. Click Finish.

   This opens the ODBC IBM DB2 Driver - Add dialog box.

7. In the Data source name field, type SAMPLE
8. In the Database alias list, select the SAMPLE database.
   • Optionally, in the Description field, type a description for your data source.
9. Click OK.
10. On System DSN tab, click SAMPLE, and then click Configure.
11. Specify the user ID and password to connect to the database, then click Connect.
12. Click OK twice.

Create an ODBC XA switch module

1. Start an Enterprise Developer command prompt (32-bit) by clicking Run as administrator.
2. Change to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
3. Enter build odbc
   Note: Make a note of the switch module name created, it is used in subsequent steps.

Create the project's workspace

1. Create the working directory on your machine, for example C:\Users\Public\REXXSAMPLE.
2. Create a Test1 subdirectory.

Import the sample MSS project

To import the sample Mainframe Subsystem (MSS) project:

1. Start Enterprise Developer for Eclipse.
2. When prompted for a workspace, specify the path created above C:\Users\Public\REXXSAMPLE
3. Click Launch.
4. On the Welcome page, click Open Team Developer Perspective.
5. Click File > Import.

   This opens the Import dialog box.

6. Expand General, and click Existing Projects into Workspace.
7. Click Next.
8. On the Import Projects page, click Browse next to Select root directory.
9. Choose %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\SQL\OpenESQL\DSNREXX\Test1
10. Click Select Folder.
11. In the Projects list, check Test1.
12. Check Copy projects into workspace.
13. Click Finish.

Create an MSS-enabled Enterprise Server

Now you want to create an enterprise server region with MSS for JCL use:

1. In Application Explorer view, right-click the Test1 project.
2. Click New > Enterprise Server.
   This opens the New Enterprise Server dialog box.

   Note: If you are prompted with an Enterprise Server Sign On dialog box, click OK without specifying any sign-on details. This is a standard security dialog box. Also, if prompted to disable password recovery, click No.
3. Select the parent Directory Server, click Default [127.0.0.1:86]
4. In the Name field, type REXX32
5. Click Browse next to the Template field.
6. In the Select template file dialog box, click JCLTemplate.
7. Click Open.
8. In the Associate with projects field, check Test1.
9. Click Finish.

Add an XA resource for REXX procedures pointing to the DB2 LUW SAMPLE database

Now that the enterprise server region is created, you need to set up an XA resource:

1. Open the Server Explorer view located in the same tabbed view as Application Explorer.
2. In Server Explorer, right-click Local [localhost:10086].
3. Click Open Administration Page.

   This opens the Enterprise Server Common Web Administration (ESCWA) interface in your default Web browser.

4. In ESCWA, click Native.
5. In the navigation pane, click Directory Servers > Default.
6. Click REXX32
7. Click General > XA Resources.
8. Click * New.

   This opens the XA Resource Configuration dialog box.

9. In the ID field, type DB2T
10. In the Name field, type REXXPROC
11. In the Module field, type the location and name of the ODBC XA switch module created in the earlier steps, for example:

    C:\Program Files (x86)\Micro Focus\Enterprise Developer\src\enterpriseserver\xa\ESODBCXA.dll

    Note: When specifying the location and name of the ODBC XA switch module, do not enter an environment variable such as %ProgramFiles(x86)%. Ensure that you use an expanded path.
12. In the Open string field, type DSN=SAMPLE

    Where SAMPLE is the Data source name specified in the ODBC Data Source Administrator.

    • You may need to add the ID and PASSWORD if connecting to a remote database. See Generic one-phase commit for ODBC xa_open string for more information.
13. Click Save.

See To define an XA resource (XAR) for an enterprise server region for more information.

Configure the program paths for data set catalog

You need to specify the JES program paths so that Enterprise Server automatically finds the application files that it needs to run:

1. In ESCWA, click JES > Configuration.
2. In the JES Program Path field, leave the default value unchanged, $IDE_LOADLIB.
3. In the System Catalog field, type C:\Users\Public\REXXSAMPLE\Test1\catalog.dat
4. In the Default Allocated Dataset Location field, type C:\Users\Public\REXXSAMPLE\Test1
5. In the System Procedure Library field, leave the default value unchanged, SYS1.PROCLIB
6. Click Apply.

Start the enterprise server region

1. In Server Explorer, expand Local [localhost:10086] > Default [127.0.0.1:86].
2. Right-click REXX32, and then click Start.
   Note: The Enterprise Server Sign On dialog box might prompt you to provide connection details for the server. This is a standard security dialog box. Click OK without specifying any sign-on details. Also, if prompted to disable password recovery, click No.
   • If you receive a Windows Security Alert for the MF Communications Process, click Allow access.

Alternatively:

1. In ESCWA, click General > Control.
2. Click Start.

Catalog the directories that have the REXX procedures

You need to specify the catalog file that holds details of the data sets required by the JCL job that run in an enterprise server region. To do this you need to create a Dynamic PDS. See Dynamic PDSs for more information.

1. In Server Explorer, expand Local [localhost:10086] > Default [127.0.0.1:86], right-click REXX32.
2. Click Show Catalog.
3. Click (Add data set entry).

   The New Catalog dialog box is displayed.

4. In the DS Name field, type USER.TEST.EXEC
5. In the Physical File field, type C:\Users\Public\REXXSAMPLE\Test1\Scripts
6. From the DS Org field, select PO.
7. From the RECFM field, select LSEQ.
8. Check Dynamic PDS.
9. In the PDS Extensions field, type rex
10. Click OK.

To run the JCL job

1. In Application Explorer view, expand the project to show the Test1.jcl file.
2. Right-click the Test1.jcl file, and then click Submit JCL to associated Server.
3. Open the Console view to verify that the job has been submitted.

View the spool output

You can check the result of submitting the JCL job by viewing the spool:

1. In Server Explorer, expand Local [localhost:10086] > Default [127.0.0.1:86].
2. Right-click REXX32.
3. Click Show Spool.
4. Double-click REXXTEST.

   A new tab displays the details of the job.

5. In the DD Entries, select one of the SYSPRINT entries to display further details in the SYSPRINT Details and SYSPRINT Display sections.
   For example, the following message or similar is displayed for STEP10:

                                                                                                                              
   DROPPING REXTEST1 TABLE                                                                                                               
   INSERTING DATA                                                                                                                        
   PREPARING S1                                                                                                                          
   FETCHING DATA                                                                                                                         
   TEST PASSED  -33329.3333                                                                                                              
   INSERTING DATA USING INSQLDA                                                                                                          
   PREPARING S3                                                                                                                          
   FETCHING DATA USING OUTSQLDA                                                                                                          
   TEST PASSED  -33329.3333