PreviousInterfacing with Microsoft Transaction Server

Chapter 11: Interfacing with IBM WebSphere

The IBM WebSphere Extended Edition CICS execution environment and the Net Express development environment are closely tied to enable you to use the two together. This chapter describes the support in Net Express for WebSphere, and how you use it.

The section Developing a WebSphere Application explains all you need to know to successfully create a project for a WebSphere application, and to compile, build and deploy your application. The other sections explain more about the built-in support for WebSphere.

You should also refer to your WebSphere documentation.

11.1 Creating a WebSphere Application

Creating a WebSphere application requires additional steps over a standard application:

If you create a WebSphere project in Net Express as described below, Net Express makes it easy for you by automatically handling all of these extra steps.

WebSphere COBOL sources have the extension .ccp. The Net Express project is created using these source files. Although .cbl files are created as part of the build process, you should only ever edit the .ccp files as the .cbl files are regenerated every time the project is rebuilt and any changes you make directly to them will be lost. To help you avoid mistakenly editing the .cbl files, they are marked as read-only when they are created.

Before you start, make sure that the folder opt\cics\bin is on your PATH environment variable to ensure that Net Express can find and run cicstcl.exe to translate .ccp files to .cbl files.

11.1.1 Setting Up Your WebSphere Project

To create a WebSphere project in Net Express:

  1. In Net Express, click File > New > Project. Complete the wizard to create a new empty project.

  2. Right-click on the build pane (left-hand pane in the Project view) and click Add files to project.

  3. In the Files of type selection box, select IBM WSEE/TX Series Program (.ccp).

  4. Select all the WebSphere source files (file extension .ccp) required for this application and click Add.

    Net Express now sets up complete build information for each file, adding essential Compiler directives and creating a DLL from each .ccp.

    You can repeat this step as often as you need, to add other source files. If you add any non-CICS .cbl files, you must manually add the two Compiler directives DATA-CONTEXT and CALL-RECOVERY to the build settings for each program you add. (See steps 9, 10 and 11.)

    If you want to use intermediate code for debugging instead of DLLs, see the section Creating Intermediate Code below.

  5. Click Project > Properties > IDE, enter the environment variable name COBCPY in the Variable field, enter the name of the CICS include folder (usually drive\opt\cics\include) in the Value field, followed by ;%cobcpy%, then click Set.

  6. Now enter the environment variable name LIB in the Variable field, enter the name of the CICS LIB folder (usually drive\opt\cics\lib) in the Value field, followed by ;%lib%, then click Set.

  7. Exit the dialog boxes.

  8. Click Project > Rebuild All to build your application, clearing syntax errors as necessary until it builds successfully. You might get warning messages saying: 
    Not supported for target platform.

    You can ignore these.

In order to be able to debug your application you must add the Compiler directive INITCALL(CBL_DEBUGBREAK) to the build settings for the program you want the debug session to start in.

  1. Right-click the required .cbl file in the build pane, and click Build Settings.

  2. Click the Compile tab, then enter the directive INITCALL(CBL_DEBUGBREAK) immediately before the semicolon (;) in the Directives pane.

  3. Click OK.

To work with WebSphere, the executable files must have the extension .cbmfnt. The following steps define the executable files that need to be renamed, and the folder they should be copied to ready for deploying.

  1. Click Project > Deployment to view the Files selected for deployment dialog box

  2. Click Add to view the Select files for deployment dialog box.

  3. In the Files to be deployed field, either enter the names of the .dll files to be deployed, separating each name from the next with a semicolon (;), or click Browse then locate and select all the files. (Note that no files will appear in the browse list unless you have built the project, as described in step 8.)

  4. In the To location field enter the name of the target folder. (This folder must exist.)

  5. Exit the dialog boxes.

  6. Click Project > Rebuild All. All the files will now be built, then copied and renamed. Subsequent builds will cause the changed files to be copied and renamed.

Your project is now ready to use. You can edit the source files (.ccp), build for debugging and debug your application in the usual way.

11.1.2 Adding Files Via the Source Pool

You can add WebSphere source files (.ccp) via the source pool (right-hand pane in the Project view) now or later. However, when you drag them to the build pane, only the translation step from .ccp to .cbl will be set up for you. You will need to set up the packaging stage (to create DLLs) yourself, as follows.

  1. Right-click in the Source pool and click Add file to source pool.

  2. Select the .ccp file and click Add.

  3. Drag the file into the build pane.

  4. Click OK on the Compiled file type selection dialog box.

  5. Right-click the .cbl file or a selection of .cbl files in the build pane, click Package selected files and click Dynamic Link Library (DLL)

  6. Right-click the .dll file and click Build Settings.

  7. Click the Link tab, click the Category selection box arrow, and click Advanced.

  8. In the field Link with these LIBs enter cicsprcbmfnt.lib.

  9. Click Close.

11.1.3 Creating Intermediate Code

For debugging, you may prefer to create intermediate code (.int) files instead of DLLs. You can do this as follows:

  1. Instead of adding files to the build pane, you must first add all your .ccp files to the source pool, and drag them into the build pane, as described above. This causes the .cbl files generated by the translation to be added to the Source Pool.

  2. Don't follow the step to package as DLLs. Instead, select all the .cbl files that have now appeared in the source pool and drag them into the build pane.

  3. Click OK on the Compiled file type selection dialog box.

  4. You now have two build trees for each .ccp file. In the trees that have a .cbl file at the top, right-click on the .cbl file and click Remove from build type.

  5. Click OK on the Remove From Build Structure dialog box.

  6. For each .cbl file in the build pane, right-click it and click Build settings.

  7. Click the Compile tab, then enter the directives CALL-RECOVERY and DATA-CONTEXT immediately before the semicolon (;) in the Directives pane.

  8. Click OK.

11.1.4 Debugging Your WebSphere Application

Now you have created a project for your WebSphere application, you should follow these steps to start debugging.

  1. In Net Express, click Animate > Settings. Under Miscellaneous on the right of the panel, check Wait for animatable attachment.

  2. Clear the contents of the Start animating at field and click OK.

  3. Click Animate > Start Animating to start debugging.

  4. On the Start Animating dialog box ensure the Executable or program name field is blank, and click OK.

  5. From your WebSphere CICS system, run the transaction in the usual way. When the transaction causes the program with the INITCALL(CBL_DEBUGBREAK) directive to be executed, a messge is displayed.

  6. Click Yes. The debugger in Net Express is activated, and you can start debugging your application.

    (If you don't have Net Express running when you click Yes then the process may appear to hang.)

11.2 WebSphere Support

This section explains some of the details of the support in Net Express for WebSphere applications. You do not need to read or understand this to create WebSphere applications.

The support in Net Express primarily gives:

11.2.1 WebSphere COBOL Storage Management

When a program is compiled with the Compiler directive DATA-CONTEXT and it LINKS to or calls a subroutine, the program works in conjunction with WebSphere to ensure instances of COBOL Working-Storage are unique to each LINK level. The standard WebSphere compilation will automatically compile with DATA-CONTEXT set. There is nothing more for you to do. However if you have a non-CICS COBOL subprogram that is called as part of a transaction execution, you should compile that program with the DATA-CONTEXT directive set in order to ensure that its Working-Storage is managed correctly.

11.2.2 WebSphere COBOL Executable Load

Standard CICS translated programs (started by a transaction code or executed by LINK or XCTL) are executed from the folder specified in the associated PPT entry (PD stanza) or are located via standard WebSphere semantics. Normal COBOL RTS load rules are not used under any circumstances for LINK and XCTL.

11.2.3 Dynamic Loading of COBOL Sub-Programs

COBOL dynamic calls to a COBOL subroutine (those that result in the loading of a new executable) on a CICS platform will first try to resolve the call via a PPT entry (PD stanza). The PPT designated physical module must have an entry point identical to the PPT name. If there is not a matching PPT entry, the COBOL RTS will try to locate the module via its usual rules.

The environment variables can be controlled independently for each WebSphere region, if required, by adding entries to \var\cics_regions\region-name\environment. The current folder for a WebSphere region application server is normally \var\cics_regions\region--name\dumps\dir1.

Note: Any COBOL programs used within a WebSphere environment that have not been translated must have an extension of .cbmfnt, .gnt, or .int in order that the online environment can find them.

11.2.4 COBOL Run-Time System Error Messages

The following new Abend code is displayed when a COBOL Run-Time System error is encountered; for example, index out of range, divide by zero, module not found without CALL-RECOVERY. The text of the COBOL RTS error message is displayed on the console log. 

A583 – Any COBOL RTS error.

11.3 EXTFH interface to SFS

The EXTFH interface to SFS is provided with the WebSphere product and should be used if you want to run batch COBOL applications against the same files as created and updated by the WebSphere online environment.

For full details, see the WebSphere ReadMe.

Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousInterfacing with Microsoft Transaction Server