Web Services with MANASYS Jazz and Micro Focus

Disclaimer: This material is written by and represents the opinions of Jazz Software Ltd. The use of Micro Focus examples in this and related Help pages do not imply any contractual relationship between Micro Focus and Jazz Software, nor that Micro Focus supports or recommends Jazz.

The previous chapter dealt with classical CICS programs, communicating with 3270 screens as in the initial video in the classical CICS series. In this chapter we develop Web Services that provide data from VSAM and DB2 records through REST (JSON) or SOAP (WSDL) messages. The process is: -

1. We generate a Jazz program from Jazz Workbench, [JazzGen], choosing Logic/Web Service. We create a Jazz web service program, using either JSON or WSDL message formats, and accessing VSAM and/or DB2 data. The message formats and program may be simply generated by following the dialog, or we may add our own logic by editing the Jazz message and program.

2. When we’re ready we click [Process] to check the Jazz program and generate COBOL from it. The project button, [TstSQL] in our examples, turns green.

3. [TstSQL] takes us to the related MFED COBOL project, where we add the COBOL to the project, and compile it.

4. We add a service interface, and generate the .wsbind and .wsdl or .json objects. The binding file, JSPG2.wsbind or WSPGA.wsbind, is moved to \loadlib\subfolder

5. After restarting the related server we are able to test our program.

This process will be illustrated with two examples, JSPG2 which is a REST update program providing enquiry, update, add and delete functions for Employee records from a DB2 database, and WSPGA which is a SOAP enquiry program, returning the data of a VSAM record as a WSDL message,. There are only minor differences between SOAP(WSDL) and REST(JSON), so they are described together below. Whichever type of service you are writing, this whole document is relevant to you unless the text specifically says that you can skip a section.

First we must ensure that MANASYS Jazz is configured to create web services for MFED (Micro Focus Enterprise Developer)

Configuring MANASYS and MFED to Work Together with Web Services

As usual we configure the Jazz workbench so that it creates objects into the libraries used by the MF COBOL project. A Micro Focus COBOL project called TSTSQL has been defined, and configured to create CICS Web Services and perhaps to use SQL. Using SQL is only necessary if, like me, you’re using DB2 or another SQL database. Jazz has been configured to share its generated COBOL, COBOL Copy Book, JZL, and BMS (3270 screen layout) folders with the COBOL project:-

Example Programs, and Creating Test Data

Two example programs are used through this Users’ Guide chapter, JSPG2 and WSPGA. JSPG2 uses a table from the IBM-supplied Sample database, but for WSPGA you’ll need a test file, Custf. If you’re going to duplicate this test for your own training, you’ll need this test file. Click JazzUGTestFiles1.htm to find out how to create Custf.

Generating Web Service Programs WSPGA and JSPG2

Creating a Jazz web service is similar to creating any other program. We start with the JazzGen dialog, selecting Logic/Web Service: -

Choose WSDL to communicate with SOAP messages, choose JSON to communicate with REST messages. Which to choose? This is a good place to start: Understanding SOAP and REST Basics And Differences. Whatever choice you make is remembered and will be your default until you chose the alternative.

Jazz will set the default program name to either WSPG1 or JSPG1, depending on this choice. Change the program name if you want something else. In this case I’ve chosen WSDL and set program name to WSPGA. I also checked [ ] replace because I’d already created a program called WSPGA.

The service name will default to MyWSv for WSDL services, and MyJSv for JSON services. You’ll usually leave this unchanged for the project, and each program you create will be another operation within the service.

URL details.

This describes where your test service will be found. Information from this panel plus the program name will be used to derive the URL that you will use to test the service, or to invoke it with an INVOKE statement.

If Jazz has been configured to access a SQL database, then we can check [ ] Use Database xxxx and name a table from the database. We’ve left this unchecked and give the name of a VSAM file, Custf, that we want to retrieve. As soon as we enter some text here some more controls appear: -

WSPGA is to provide enquiry, not update, so we leave [ ] Update unchecked, and fill in a number of records to be returned. We can choose which fields from Custf we want to return in the response message. For WSPGA we’ll leave the default of “All Fields” so that all of the CustF fields are returned. Other options are Keys, which will return Account and Name as these are the two key fields, and Select which initiates a selection dialog from which we choose which fields we want.

Click [Finish].

Program JSPG2

Whereas WSPGA was a VSAM enquiry communicating with WSDL, JSPG2 is a DB2 update program communicating with JSON. It is generated with: -

Differences to WSPGA:

1. We’ve checked JSON.

2. The URL panel includes a link @Swagger, and the port value is different. Other URL details are the same: we expect that if you are developing both types of service within the same project then they’ll be tested from different ports at the same location. You can of course change any of this data.

3. We’ve checked Use Database sample. The database name (and connection information) are given in the SQL tab of Configuration.

4. We checked Update

5. Employee has an EXISTS relationship with another table. This causes an extra dialog step.

Generating Web Services with EXISTS Relationships

The definition of EMPLOYEE.WORKDEPT includes EXISTS DEPARTMENT.DEPTNO, meaning that to be valid, values of EMPLOYEE.WORKDEPT must be found as values of DEPARTMENT.DEPTNO: -

COPY Department;

DEFINE EMPLOYEE SQL DATA(

…

WORKDEPT CHAR(3) CAPS DKEY 'XEMP2' EXISTS DEPARTMENT.DEPTNO,

…

Because of this, if you create or update an EMPLOYEE record the program will check the DEPARTMENT record to see check that you’ve given a valid EMPLOYEE.WORKDEPT value. You may also want to use related data, such as the department name, so a Select Data dialog appears: -

Select the field(s) from DEPARTMENT that you want, and they will be added into the web service output message. In this example we’ve selected only DEPARTMENT.DEPTNAME.

@Swagger

Click @Swagger and you can see (and edit) the template from which Swagger compliant JSON definitions are is created. See Appendix: Swagger Definitions to learn more about Swagger definitions, and Test JSPG2 to see an example of using these to test your web service.

Jazz Web Service Message

On clicking [Finish] the next thing we see is a Jazz workbench with an initial container definition for us to edit. Jazz creates container definitions with three records, a control record that gives the names of the input and output messages, and the two messages. Here is the message for WSPGA: -

*# Last Updated by JAZZUSR at 20/05/2020 9:49:01 AM

*# You may edit this definition: right-click the 'WEBSERVICE' keyword of the PROGRAM statement.

COPY Custf;

COPY TYPES;

DEFINE MyWSv-WSPGA SYSTEM DATA([Not in COBOL

INPUT VARCHAR(6) VALUE 'IWSPGA',

OUTPUT VARCHAR(6) VALUE 'OWSPGA',

MType CHAR(4) VALUE 'WSDL',

URL VARCHAR(41) VALUE 'http://localhost:5482/cics/services/WSPGA');

DEFINE IWSPGA SERVICE INPUT DATA(

JZ-Custf-Skip SMALLINT VALUE 0,

Custf GROUP,

Account CHAR(6) ASSIGN CustF.Account, [KEY

Name CHAR(30) ASSIGN CustF.Name, [DKEY

END GROUP);

DEFINE OWSPGA SERVICE OUTPUT DATA(

ERROR VARCHAR(80),

JZ-Custf-ReadTo SMALLINT VALUE 0,

JZ-Custf-NbrReturned SMALLINT VALUE 0,

JZ-Custf-ReturnCode LIKE Types.ReturnCode,

Custf (10(OWSPGA.JZ-Custf-NbrReturned)) GROUP,

Account LIKE CustF.Account ASSIGN CustF.Account,

Region LIKE CustF.Region ASSIGN CustF.Region,

District LIKE CustF.District ASSIGN CustF.District,

Name LIKE CustF.Name ASSIGN CustF.Name,

SalesThisMonth LIKE CustF.SalesThisMonth ASSIGN CustF.SalesThisMonth,

SalesYTD LIKE CustF.SalesYTD ASSIGN CustF.SalesYTD,

Billingcycle SMALLINT ASSIGN CustF.Billingcycle,

DateCommenced LIKE CustF.DateCommenced ASSIGN CustF.DateCommenced,

END GROUP);

It contains three DEFINE statements. The first provides information that is occasionally needed by MANASYS Jazz, but is present primarily because any Jazz COPY book must contain a DEFINE naming a record with the same name as the copy book. With TYPE(SYSTEM) it won’t be generated into the COBOL. The 2^nd and 3^rd DEFINE statement define the input and output records. Because they may use LIKE to ensure that message fields have the same formats as their corresponding fields (for example in Custf), and ASSIGN making the relationships explicit, COPY statements ensure that the referenced definitions are always available.

We don’t need to edit this, so simply click [Exit].

For web service JSPG2 the message contains more fields, in particular the input record contains a function code and fields that might be updated. We can’t implement CICS-style pseudo-locking by saving a copy of the record initially read in COMMAREA and comparing this when the record is re-read for update as everything must be in the input record, so Jazz implements equivalent logic with a Checksum. We’ll discuss this later.

*# Last Updated by Jazzusr at 30/01/2022 9:55:38 am

*# You may edit this definition: right-click the 'WEBSERVICE' keyword of the PROGRAM statement.

COPY EMPLOYEE;

COPY TYPES;

DEFINE MyJSv-JSPG2 SYSTEM DATA([Not in COBOL

INPUT VARCHAR(6) VALUE 'IJSPG2',

OUTPUT VARCHAR(6) VALUE 'OJSPG2',

MType CHAR(4) VALUE 'JSON',

Template CHAR(8) VALUE '@JSF1Upd',

URL VARCHAR(41) VALUE 'http://localhost:9003/cics/services/JSPG2');

DEFINE IJSPG2 SERVICE INPUT DATA(

Function CHAR(1) CAPS CODES(E:Enquiry,U:Update,A:Add,D:Delete) VALUE Enquiry,

JZ-EMPLOYEE-Skip SMALLINT VALUE 0 RANGE(0:999),

JZ-EMPLOYEE GROUP,

EMPNO CHAR(6) ASSIGN EMPLOYEE.EMPNO,

FIRSTNME CHAR(12) ASSIGN EMPLOYEE.FIRSTNME,

MIDINIT CHAR(1) ASSIGN EMPLOYEE.MIDINIT,

LASTNAME CHAR(15) ASSIGN EMPLOYEE.LASTNAME,

WORKDEPT CHAR(3) ASSIGN EMPLOYEE.WORKDEPT,

PHONENO CHAR(4) ASSIGN EMPLOYEE.PHONENO,

HIREDATE CHAR(9) ASSIGN EMPLOYEE.HIREDATE,

JOB CHAR(8) ASSIGN EMPLOYEE.JOB,

EDLEVEL CHAR(7) ASSIGN EMPLOYEE.EDLEVEL,

SEX CHAR(1) ASSIGN EMPLOYEE.SEX,

BIRTHDATE CHAR(9) ASSIGN EMPLOYEE.BIRTHDATE,

SALARY CHAR(15) ASSIGN EMPLOYEE.SALARY,

BONUS CHAR(15) ASSIGN EMPLOYEE.BONUS,

COMM CHAR(15) ASSIGN EMPLOYEE.COMM,

CURRENCY CHAR(3) ASSIGN EMPLOYEE.CURRENCY,

DEPTMGR CHAR(5) ASSIGN EMPLOYEE.DEPTMGR,

Checksum CHAR(40),

END GROUP);

DEFINE OJSPG2 SERVICE OUTPUT DATA(

Error VARCHAR(80),

JZ-EMPLOYEE-ReadTo SMALLINT VALUE 0,

JZ-EMPLOYEE-NbrReturned SMALLINT VALUE 0,

JZ-EMPLOYEE-BrowseCount SMALLINT VALUE 0,

JZ-EMPLOYEE (1) GROUP,

JZ-EMPLOYEE-ReturnCode LIKE Types.ReturnCode,

EMPNO LIKE EMPLOYEE.EMPNO ASSIGN EMPLOYEE.EMPNO,

FIRSTNME LIKE EMPLOYEE.FIRSTNME ASSIGN EMPLOYEE.FIRSTNME,

MIDINIT LIKE EMPLOYEE.MIDINIT ASSIGN EMPLOYEE.MIDINIT,

LASTNAME LIKE EMPLOYEE.LASTNAME ASSIGN EMPLOYEE.LASTNAME,

WORKDEPT LIKE EMPLOYEE.WORKDEPT ASSIGN EMPLOYEE.WORKDEPT,

PHONENO LIKE EMPLOYEE.PHONENO ASSIGN EMPLOYEE.PHONENO,

HIREDATE LIKE EMPLOYEE.HIREDATE ASSIGN EMPLOYEE.HIREDATE,

JOB LIKE EMPLOYEE.JOB ASSIGN EMPLOYEE.JOB,

EDLEVEL LIKE EMPLOYEE.EDLEVEL ASSIGN EMPLOYEE.EDLEVEL,

SEX LIKE EMPLOYEE.SEX ASSIGN EMPLOYEE.SEX,

BIRTHDATE LIKE EMPLOYEE.BIRTHDATE ASSIGN EMPLOYEE.BIRTHDATE,

SALARY LIKE EMPLOYEE.SALARY ASSIGN EMPLOYEE.SALARY,

BONUS LIKE EMPLOYEE.BONUS ASSIGN EMPLOYEE.BONUS,

COMM LIKE EMPLOYEE.COMM ASSIGN EMPLOYEE.COMM,

CURRENCY LIKE EMPLOYEE.CURRENCY ASSIGN EMPLOYEE.CURRENCY,

DEPTMGR LIKE EMPLOYEE.DEPTMGR ASSIGN EMPLOYEE.DEPTMGR,

Checksum CHAR(40),

DEPTNAME LIKE DEPARTMENT.DEPTNAME ASSIGN DEPARTMENT.DEPTNAME FKEY EMPLOYEE.WORKDEPT,

END GROUP);

As with WSPGA we don’t need to edit, so we simply click [Exit].

Jazz Program Logic

Next we see the logic that Jazz has generated. For WSPGA, our single-table enquiry program: -

Generating COBOL (WSPGA)

We have now generated the Jazz program WSPGA, which is a web service provider returning data from a single table, Custf. As well as the Jazz logic in WSPGA.jzz, we have created message definitions in MySvce-WSPGA. We can get rid of message #263 by clicking [Check] to resolve the inserted COPY statement, or we can click [Process] which checks the program and also generates COBOL. With [Process] the [Job Results] button, in this case labelled [tstsql] as this is the name of the associated Micro Focus COBOL project, turns green: -

Now, within project’s common folder C:\tutorials\tstsql: -

· \Jazz_Programs\WSPGA.jzz is the Jazz program logic

· \Jazz_CopyDefs\MySvce-WSPGA.jzc is the Jazz message format (both input and output)

· \cbl\WSPGA.CBL is the COBOL program logic

· \cpy\IWSPGA.CPY is the COBOL input message

· \cpy\OWSPGA.CPY is the COBOL output message

Click here to see the COBOL generated for program WSPGA.

Now we click the green [tstsql] button to open the Micro Focus COBOL project with Visual Studio, so that we can prepare the program for testing.

Generating COBOL(JSPG2)

As we would expect program JSPG2 has more logic than WSPG1, as it must deal with enquiry, update, add, and Delete: -

*# Last Updated by robertb at 11/3/2019 5:23 p.m.

PROGRAM JSPG2 WEBSERVICE MyJSv CONTAINER DFHWS-DATA DATABASE sample DB2 JSON;

* Single Table Update

COPY JZTrim;

ACCEPT (IJSPG2.Function) MESSAGE OJSPG2.ERROR;

#052 W Item IJSPG2.Function will be validated, but not moved from the input record

CASE (IJSPG2.Function);

WHEN (Enquiry);

ACCEPT (EMPLOYEE.EMPNO = IJSPG2.EMPNO OR EMPLOYEE.WORKDEPT = IJSPG2.WORKDEPT) MESSAGE OJSPG2.ERROR;

GET Employee KEY(EMPLOYEE.EMPNO OR EMPLOYEE.WORKDEPT) SAVESUM OJSPG2.CheckSum-Employee;

#628 W GENERIC assumed for WORKDEPT

END GET Employee RESPOND OJSPG2;

WHEN (Update);

ACCEPT (EMPLOYEE.EMPNO=IJSPG2.EMPNO) MESSAGE OJSPG2.ERROR;

GET Employee KEY(EMPLOYEE.EMPNO) UPDATE CHECKSUM IJSPG2.CheckSum-Employee;

COPY JZSMth;

COPY JZMDays;

COPY JZDTVS;

ACCEPT (IJSPG2.JZ-Employee.*) EXCEPT(EMPLOYEE.EMPNO) MESSAGE OJSPG2.ERROR;

#207 I JZ-Employee.FIRSTNME,JZ-Employee.MIDINIT,JZ-Employee.LASTNAME,JZ-Employee.WORKDEPT,JZ-Employee.PHONENO,JZ-Employee.HIREDATE,JZ-Employee.JOB,JZ-Employee.EDLEVEL,JZ-Employee.SEX,JZ-Employee.BIRTHDATE,JZ-Employee.SALARY,JZ-Employee.BONUS,JZ-Employee.COMM,JZ-Employee.CURRENCY, included in generic assignment

END GET Employee UPDATE RESPOND OJSPG2;

WHEN (Add);

GET Employee FREEKEY CREATE;

#221 E EMPLOYEE.EMPNO used as key field(s). It/they will be set to next available value.

ACCEPT (IJSPG2.JZ-Employee.*) EXCEPT(EMPLOYEE.EMPNO) MESSAGE OJSPG2.ERROR;

END GET Employee CREATE RESPOND OJSPG2;

WHEN (Delete);

ACCEPT (EMPLOYEE.EMPNO=IJSPG2.EMPNO) MESSAGE OJSPG2.ERROR;

DELETE Employee KEY(EMPLOYEE.EMPNO) CHECKSUM IJSPG2.CheckSum-Employee;

END CASE;

REPLY;

The only difference from a SOAP equivalent is that the PROGRAM statement has JSON instead of WSDL. In fact, there is no difference at all in the COBOL that is generated for a web service if the only change is switching between JSON and WSDL. All the differences are in WSBIND, an object which we’ll create shortly, which translates the COBOL-format message definitions to/from either WSDL or JSON.

The logic of this program is essentially the same as a classical CICS VSAM Update, except that SAVESUM replaces SAVECOPY and CHECKSUM replaces CHECKCOPY. See below if you want to understand this.

Click [Process] to create COBOL and other objects. The [Job Results] button ([tstsql]) turns green, and COBOL and other objects are written by Jazz directly into the correct folders within project tstsql, although they are not yet “Included in the project” as far as Visual Studio is concerned.

Click here to see the COBOL generated for program JSPG2.

Now we click the green [tstsql] button to open the Micro Focus COBOL project with Visual Studio, so that we can prepare the program for testing.

SAVESUM/SAVECOPY, CHECKSUM/CHECKCOPY

In a classical CICS program SAVECOPY saves a copy of the record in COMMAREA, and CHECKCOPY compares this copy with the re-read record. If differences are found then the update is abandoned with a message. This standard classical CICS technique avoids the problem of excessive locking which could cause the system to lock up, while ensuring that records are not updated invalidly. However, a web service cannot access a COMMAREA unless this is the message definition, and it would not be a good idea to pass a copy of the original record to the client and have it returned unchanged in the next message. There are two problems, the client might change the “reference copy” causing the update to fail or succeed when it shouldn’t, and also details might have to be disclosed which should be kept hidden.

Compared to a classical CICS program, a web service uses SAVESUM instead of SAVECOPY, and CHECKSUM instead of CHECKCOPY. SAVESUM calculates a hash total (or checksum) according to an algorithm which guarantees a unique encrypted value for each possible value of the input record. This is written into the output record, and returned in the input record for the Update transaction. To perform an update the client copies the checksum field from the enquiry service’s output record to the update service’s input record. In the Update transaction CHECKSUM causes the checksum to be recalculated from the re-read record, and compared with the value returned in the input record. The effect is that if the record has been changed in the meantime by another transaction this change will be detected, and the update rejected, functioning like SAVECOPY/CHECKCOPY in a classical CICS program without disclosing the original record to the web service in a form where it can be read, or changed.

Prepare web service programs for Testing

Introduction

With each new web service program that we write, when we’ve completed our Jazz processes through to [Process] we need to

1. Add the COBOL program into the Tstsql COBOL project, and compile it

2. Create the Binding File and WSDL or JSON objects required by a SOAP or REST web service

3. We may need to prepare our MFED project for Web Service testing.

Add the COBOL Program into the TstSQL COBOL Project.

Clicking the [tstsql] button will have opened the Micro Focus COBOL project in Visual Studio. Now, and for the remainder of this topic, we’re dealing with the Micro Focus Enterprise Developer (MFED) COBOL project.

Although the COBOL program and the copy books for the input and output messages are already in the correct folders, they are not “included in the project” until we add them with Visual Studio. If this is the first time that we’ve created this program (WSPGA or JSPG2), right-click the TstSQL cbl project (not the solution) in Solution Explorer, and click Add/Existing Item. This opens a Windows Explorer dialog. Navigate to \cbl folder, e.g. C:\tutorials\Tstsql\cbl, and click WSPGA.cbl (or JSPG2.cbl). Click [Add]. The object is added into the project. We don’t need to add the \cpy objects: these are necessary for z/OS users, but Jazz generates the record layouts directly into the COBOL without using a COBOL COPY statement, so they’re not needed with Micro Focus. We won’t need to repeat this process if we regenerate the program.

Now that the COBOL program has been added, either right-click the tstSQL project and click Build, or right-click program WSPGA (or JSPG2) and click Compile. Either will compile the program: there should be no errors.

Create the Binding File and Associated Objects

A web service receives and sends data from/to other programs. These programs don’t have to be written in COBOL; in fact, this is unlikely. They probably aren’t running with CICS either, whether in a Micro Focus Enterprise Server or z/OS. Web Services therefore can’t send a COBOL-format record, but must instead convert the COBOL layout into a message in a standard format that the other program will understand. There are two standards, REST messages (described by JSON), and SOAP messages (described by WSDL). Before we can begin testing our COBOL web service program we have to create a description of the message in JSON or WSDL, and an object called a “Binding File” that will convert data between our COBOL layouts and the standard format that can be transmitted and understood by other programs that aren’t necessarily COBOL. With this “plumbing” our program can simply refer to the COBOL layouts and the conversion between these and the standard format is automatic.

In this section we’re using program WSPGA as our SOAP example, and JSPG2 as our REST example.

Binding File Part 1. Create a Service Interface

Right-click the TstSQL project in Solution Explorer, and click Add > New Item

Expand COBOL > Native > Mainframe Subsystem.

Click Service Interface in the centre pane. NB: “Mainframe Subsystem” appears twice, once directly under COBOL, and once under COBOL/Native. If you don’t see “Service Interface”, you’ve clicked the wrong one.

Name the service with the name of your program, e.g. JSPG2 or WSPGA: -

Click [Add]. The form above disappears, to be replaced by the Service Interface form. On this form check CWS-Type (means “CICS Web Service). Choose the appropriate transport type: JSON for JSPG2, SOAP for WSPGA. Choose CICS Channel as Type of Source: -

Click [OK]. xxxxx.svi (JSPG2 or WSPGA) is added to your project (you’ll see it appear in Solution Explorer), and the Interface Mapper is displayed. Four windows are displayed, Input Data Area, Output Data Area, Interface Fields, Reusable Fields, plus a combo box “Operation”. At this stage they’re all blank.

In the Visual Studio menu, click Extensions/Operation/New or (VS2017 Operation/New). If you can’t see “Operation” in the menu, click one of the Interface Mapper windows. The Operation Properties menu appears.

Type a name for your operation, e.g. “JSPG2”, “GetCustf”. It is now my habit to give this the same name as the program (e.g., JSPG2), but as the GetCustf example shows, this is not necessary.

In Select program/copybook, click your program (JSPG2/WSPGA). xxxx(2) and xxxx(3) appear in the input and output data areas below.

Select xxxx(2) for Input, and xxxx(3) for output.

Check that both Create Default Mappings checkboxes are checked.

Sanity check: the names of the input and output messages should be as you expect from the Jazz message definitions: IJSPG2/IWSPGA for input and IJSPG2/OWSPGA for output.

Click [OK]. The Operation Properties form disappears, and details appear in the Interface Mapper windows. Right-click xxxxx.svi (in the list of tabs in Visual Studio’s center panel, not in Solution Explorer) and click Save xxxx.svi. Illustrated here with WSPGA: -

You can now close the .svi window, e.g. WSPGA.svi, as you don’t need it for the next steps.

Binding File Part 2. Generating WSBIND

In Solution Explorer, right-click the .svi (WSPGA.svi or JSPG2.svi), and click Generate WSBind: -

For a REST service three objects are created, input and output descriptions, JSPG2I and JSPG2O, and the binding file, JSPG2.wsbind that will convert between .json and COBOL.

For a SOAP service (WSPGA) a single .wsdl file is created containing both the input and output definitions, plus the binding file that will convert between .wsdl and COBOL.

Generating WSBIND

WSPGA.wsdl

WSPGA.wsbind

WSBIND generation completed successfully.

Solution Explorer will show these new objects: -

Binding File part 3: Move the Binding File

The binding file – WSPGA.wsbind or JSPG2.wsbind – has been generated into the project’s root folder. For example, with my configuration they will be generated into C:\tutorials\TstSQL. However, they need to be in the project’s loadlib folder if you have only one type of service, or a loadlib subfolder if your project has both SOAP and REST services.

If your project is going to have only one type of service, then you don’t need to use a loadlib subfolder. Thus, with my initial testing when I had only one type (SOAP) of service, I would have moved the binding files like this: -
Move WSPG1.wsbind from C:\tutorials\TstSQL to C:\tutorials\tstsql\loadlib\,

Later I had both SOAP and REST services, so I created subfolders
C:\tutorials\tstsql\loadlib\SOAP and
C:\tutorials\tstsql\loadlib\REST,

and I moved all the previous .wsbind files into C:\tutorials\tstsql\loadlib\SOAP. You also need to create separate pipelines for SOAP and REST services, setting their WebSvc Dir to the subfolder, e.g.
$IDE_LOADLIB\SOAP
and $IDE_LOADLIB\REST

To move the binding file use Windows Explorer

· Navigate to the project folder (C:\tutorials\tstsql\),

· Cut and Paste the binding file to the loadlib folder or subfolder

· WSPGA: Cut C:\tutorials\tstsql\WSPGA.wsbind, paste to C:\tutorials\TstSQL\loadlib\SOAP\WSPGA.wsbind

· JSPG2: Cut C:\tutorials\tstsql\JSPG2.wsbind, paste to C:\tutorials\TstSQL\loadlib\REST\JSPG2.wsbind

Binding file Part 4. Build the Project

Back to Visual Studio: build project TstSQL (right-click the project in Solution Explorer, Click Build). It should build without problems.

Now we should be able to test our service – provided that our MFED COBOL project has been correctly set up. We’ll deal with these set-up issues through “troubleshooting” as we come to the relevant situations.

Check that the service (WSPGA or JSPG2) is running

Start (or restart if it’s already running) the MF Server that is associated with project TstSQL. When it’s [re]started, open ESMAC

· Right-click Micro Focus Servers in Server Explorer, click Administration.

· Click [Details] for the running server Ts2SQL.

· Click [ES Monitor and Control]

· ESMAC menu: choose Active Resources, and click [WebSvc]. If you don’t see a [WebSvc] button, see No [WebSvc] button below

· You should see the program – WSPGA or JSPG2 – in the list of services: -

Here the first REST service, JSPG2, is shown associated with pipeline RESTPIPE. WSPGA, as well as several other SOAP services, is associated with PROVPIPE: -

Troubleshooting

1. No [WebSvc] button

You shouldn’t have this problem if you’ve previously tested other web services, even with a different project or server, unless you’ve changed your personal computer since then. Without a WebSvc button you can’t check to see if the service is running. If you have this problem, step through the checks of Issue 1: No [WebSvc], [Pipeline], or [Bundle] buttons

2. If [WebSvc] shows no active services

Step through the checks of Issue 2: No Active Web Service, particularly Cause #3 Pipeline and TCPIP Service not defined

Test Web Services

Now that our services are running, we need a way to invoke them. I tested WSPGA using the free version of SOAPUI, and JSPG2 with ReadyAPI (previously SOAPUI-Pro). If you are using the same software you can go directly to the appropriate section, Test WSPGA or Test JSPG2, but if not you may need to read both sections.

Test WSPGA

Skip to Test JSPG2 if you’re working with REST (JSON) services

We’re now ready to test our service. We need a way of invoking it, which we will do by submitting a SOAP request to a URL
http://localhost:5482/cics/services/WSPGA

We’ll use the free test utility SOAPUI to create a test.

Open SOAPUI, click [SOAP] to create a new request. Give a name, and browse to the .wsdl (which is in our project’s root directory): -

This creates a SOAPUI project. Double-click Request1 to open the request test: -

Replace the “?” with test values (hint: use Find/replace/Replace all to change all the “>?<” with “><”, then supply your test values): -

Click to submit the test. Here’s part of the output, showing 2 of the 10 records returned: -

Test JSPG2

We’re now ready to test our service. We need a way of invoking it, which we will do by submitting a REST request to a URL
http://localhost:9003/cics/services/JSPG2

We’ll use the test utility ReadtAPI (previously called SOAPUI Pro) to create a test. Start ReadyAPI, and click Menu File/New Project. This form appears. Give a project name, and for “URL or File Path” browse to JSPG2.json, which is in our project’s root directory (C:\tutorials\TstSQL\JSPG2.json).

But where did JSPG2.json come from? In Create the binding file and JSON you may remember that the Create WSBIND process created JSPG2I.json and JSPG2O.json, but there was no JSPG2.json. MANASYS Jazz created it for you when you used the Create New Service dialog to generate program JSPG2.jzz, in anticipation of the later existence of the actual record formats JSPG2I and JSPG2O. See Appendix: Swagger Definitions for more information. JSPG2.json is quite short, and contains references to the input and output .json message definitions, so you don’t need to regenerate it if the message formats change.

Now click [Create Project]. ReadyAPI creates a project for you: -

To test program JSPG2, expand the node as far as you can: -

Click Request 1. Choose which request format you want to use – I’ve chosen Form: -

By the way: did you notice that some of the field names are prefixed with “JZ_”? For example “Function” has become “JZ_Function”. This is because this is either because the original name might be invalid in some contexts – Function is a COBOL reserved word – or it is field that Jazz has generated for its own purposes (JZ_Employee_Skip) and so it is given a name that you can’t use.

A basic Jazz update program like JSPG2 expects to start with an enquiry, function E, so we enter values like this, and click the green Send arrow at the top of the request. Note that I removed “string” for the fields that I wanted to leave empty.

The response shows that this reads a record from the database and returns information from it: -

We can continue with further tests, checking that our program handles (returning appropriate messages) invalid data, and can perform the functions of U(pdate), A(dd), and D(elete) correctly. For Update and Delete the Checksum returned in the previous response must be copied into the request, otherwise the program will reject the update request. With ReadyAPI you can design test scripts to run a sequence of transaction: for example copying data from a response into the next request, running test sequences with varying data, and so on. You should consult SmartBear for tutorials about this.

Further Development and Debugging

The initial test has gone smoothly, and the results might be exactly what we want. Or we might want changes – for example returning a different number of records, or selecting the fields that we want to return. Or perhaps there are errors that we need to sort out.

When to Change the COBOL, When to Regenerate from Jazz

We developed our programs through this process: -

1. We generated a Jazz program from Jazz Workbench, [JazzGen], choose Logic/Web Service, and defined the type of service that we wanted.

2. [Process] checked the Jazz program and generated COBOL from it

3. [tstsql] took us to the related MFED COBOL project, where we compiled the generated COBOL

4. We added a service interface, and generated the .wsbind and (.wsdl or .json) objects. xxx.wsbind was moved to …\loadlib\SOAP or …\loadlib\REST

5. After restarting the related MF server we were able to test our program

When you have a problem or want to make a change then you should make the change at the earliest possible stage in this process. For example, if you want to change WSPGA to return a different number of records, or only some of the fields, then it is far easier to regenerate the program from the New Web Service dialog than to change the Jazz program, or change the COBOL. Thus

This is far easier than changing the message definition, or (even worse) changing the COBOL and ensuring that all the related program changes have been made correctly.

Similarly, just checking [ ] Update will create a program that will create a program to update the record. Now repeating the process above you’ll create a SOAP message that is consistent with the new data and function – for example, it will contain a function code and a record digest to manage CICS-style lazy locking, and the program and message formats will consistent and properly documented. The equivalent by changing the COBOL is a lot more work, with many more opportunities for error.

Changing the Jazz Program

Generators like the Web Services dialog are designed to quickly generate a template for the common and basic situations, but they don’t cover all situations. For example you will discover that, unlike a classical CICS program, you have to be very specific with the use of capitals in any CHAR or VARCHAR key field. Thus the previous SOAPUI test worked perfectly with value

but a test with

returned no records. You may want to make your web service to behave more flexibly, accepting any case for Name value, especially as you may not control the logic to be written in the web service requestor and you’ll want to simplify the way in which both developers and end users interact with your service. If the Name field in the file has upper-case data then all you have to do is to re-create the program after adding property CAPS to the field definition: -

DEFINE CustF VSAM DATA(

…

Name CHAR(30) CAPS DKEY 'jazzuser.vsam.custf1',

…

It’s not as simple if the field can contain mixed-case data.

Occasionally Jazz may generate incorrect COBOL code. For example, in the initial development of program WSPGA we found that the COMP field in the output message needed to be generated as COMP-5, otherwise incorrect values were returned. This problem was fixed of course and won’t affect you, but there may be others. In such cases you may have to change the COBOL, but you should inform us so that we can correct Jazz.

Rebinding: When the Message Formats Change

Many program changes don’t affect the message formats. You can make the changes to your Jazz program, regenerate, and recompile the COBOL, and the corrected program will run. But if you’ve previously created a service interface for this program and the message formats might have changed, then you should refresh the service interface and re-create the binding file.

Here I’ve just made some program changes and recompiled program WSPGEM. To ensure that everything is consistent: -

· Visual Studio (COBOL project): In the Solution Explorer window right-click the project and select Refresh Annotations for Services. This displays this dialog

· Click [Auto Select] or select the changed items.

· Click [Refresh]

· Click [Close]

If the message formats have changed you will probably need to regenerate the binding file. Here’s an example: I changed a Jazz rule to make web service input fields have a minimum length of five, and programmed the TRIM routine JZTRIM to recognize special values NULL and SPACE. However now a SOAPUI test failed with message

Function Invalid Code

Using debugging (see below) I saw that my program was picking up the 1 character “E” together with the next four characters: -

Trying to add the blanks with

<wsp:JZ_Function>E </wsp:JZ_Function>

didn’t help: now I got a CICSFault message

CASPI1009E 19/05/30 16:24:35 TS2SQL 000025 XML to data transformation failed. A conversion error (OUTPUT_OVERFLOW) occurred when converting field JZ_Function for WEBSERVICE WSPGEM.

In a situation like this we need to re-generate the web service interface. Here’s how I did this (it may contain more steps than necessary). In this example my SOAP (WSDL) program was WSPGEM, my REST (JSON) program was JSPG2, both in project TstSQL: -

· Visual Studio, Solution Explorer:
WSPGEM: remove WSPGEM.svi, WSPGEM.wsbind*, and WSPGEM.wsdl from the project.
JSPG2: remove JSPG2.svi, JSPG2.wsbind*, JSPG2I.json, and JSPG2O.json from the project.

* .wsbind objects have been moved to the Loadlib. See next step

· Windows Explorer. Remove the program from the loadlib:
WSPGEM: remove WSPGEM.dll and WSPGEM.idy from C:\tutorials\TstSQL\loadlib, and WSPGEM.wsbind* from C:\tutorials\TstSQL\loadlib\SOAP.

JSPG2: Remove JSPG2.dll, JSPG2.idy from C:\tutorials\TstSQL\loadlib, and JSPG2.wsbind from C:\tutorials\TstSQL\loadlib\REST.

* If you are supporting both WSDL and JSON services in this project, then you will have subfolders within …\loadlib. For example, I now put my binding files for WSDL servers into folder C:\tutorials\TstSQL\loadlib\SOAP, and JSON services into C:\tutorials\TstSQL\loadlib\REST. However if you are only supporting a single type of service you are likely to have left the xxxx.wsbind object in the \loadlib folder.

· Now compile the program, refresh annotations, then repeat the steps from Create the Binding File and WSDL to Test WSPGA to create the service interface and associated objects. When you create the service interface, check that you have the version of the record layouts that you expect, e.g. correct record names, with the fields that you expect after your most recent updates.

· Restart the Micro Focus Server

· Regenerate the SOAPUI test. Because the binding file has changed, previous tests may not work.

Another example: I had created a program JSPG2, that was a DB2 Update program. I then deleted this program and the associated objects (JSPG2.svi, JSPG2.JSPG2I.json, JSPG2O.json, and JSPG2.wsbind) from the project and presumably from all the folders. Some time later I created an unrelated program, also called JSPG2, that was a VSAM enquiry. Everything went smoothly and I created the .svi, .json, and .wsbind objects. The record layouts in the program (and IJSPG2.cpy and OJSPG2.cpy) were as expected. I restarted the MF Server, and ESMAC showed me that the REST service JSPG2 was active, so I created a ReadyAPi project to test it. According to ReadyAPI, the INPUT MESSAGE FORMAT WAS THAT FOR THE FIRST VERSION OF THE PROGRAM.

To correct this problem I used Refresh Annotations for Services and went through the process above for program JSPG2, recreating the .svi and other objects. Now my ReadyAPI test worked perfectly.

Stepping Through the Program

Things don’t always work so well. You can diagnose problems by stepping through your generated COBOL program in the COBOL project. Here an example of this process: I’ve recorded how I solved a problem with program WSPG1, which was in COBOL project LOANDEMO. A SOAPUI test had returned a CICSFault result: -

Why is this failing, giving a fault message “Target program WSPG1 failed with abend code ASRA”?

The ESMAC display showed that the web service was activeP and the fact that the SOAPUI test produced any response at all showed that we were sending a message to the program, which it received, and there was a responseP. At least we have the plumbing correct, even if there’s something wrong with our program.

I Googled “CICS Abend ASRA”. This led me to an IBM Knowledge Centre page which said

CICS issues an ASRA abend code when it detects that a program check has occurred within a transaction. Program checks can occur for a wide variety of reasons, but you can find the nature of the error from the program interrupt code in the program status word (PSW). The PSW is used by the machine hardware to record the address of the current instruction being executed, the addressing mode, and other control information. The PSW gives you the address at which the program check occurred, and so it represents a record of the circumstances of the failure.

More information was needed.

2. Open solution CWSProject (which contained the LoanDemo project) in Visual Studio.

3. Double-click the project properties in Solution Explorer

4. In the project properties, click the Debug tab, and set Active Settings to Any

5. In the COBOL web service I put a checkpoint on the first Procedure Division Statement.

(Actually a checkpoint on the first Procedure Division statement is assumed by default, so I didn’t need to do this).

6. Start debugging (Visuals Studio: Click Start, or press F5, or menu Debug/Start Debugging). Respond [Yes] to the message.

7. Issue the SOAPUI request again. The web service starts, and then pauses on the checkpoint. Step through the program with F10 until PERFORM CICS-CheckStatus is reached, then F11 to step into CICS-CheckStatus. Continuing you’ll see that an invalid response code has been returned, throwing program WSPG1 to Abend-Exit. If you had stopped at PERFORM and examined the response variables, you’ll see that JZ-Response has value 110.

· Google tells us that a response of 110 from GET CONTAINER(JZContainerName) occurs when the container name doesn’t exist in the channel. See the IBM Redbook SG247227, CICS Channels and Containers to learn about containers. Jazz had generated the program assuming that the requesting program will have requested the service with the agreed container name, “JZCWSPGA”, but this is not the case with this SOAPUI request.

Jazz was changed to avoid this problem: it was modified to generate code based on the code shown in Example 2.3, page 28, of the IBM Redbook to browse for the container name so that it doesn’t matter what the input container name is. This makes all Jazz-generated web services providers from now on more flexible. Jazz was also changed so that the default container name is DFHWS-DATA, and that this is the name of the output container. This seems to be required by Micro Focus Enterprise Developer, although not by z/OS.

Errors that don’t reach the program

Some errors don’t allow a message to reach our program, so we can’t step through it to find out where the problem is. Here, for example, the service name is wrong: -

For the “plumbing” to work properly, the endpoint name must be exactly correct, including case - “WSPGa” is not the same as “WSPGA” – the XML must be properly formed (try removing one of the tags), and the data must have the correct format. For example, if we try to retrieve record with Account Number = “A” we’ll get this: -

The full CICSFault message is

CASPI1009E 18/08/20 11:17:59 LOANDEMO 000042 XML to data transformation failed. A conversion error (INVALID_CHARACTER) occurred when converting field Account for WEBSERVICE WSPGA.

MANASYS Jazz has been developed to avoid most of these errors. For example, input fields are now generated with format CHAR with assignments to the target field, for example
Account CHAR(6) ASSIGN CustF.Account, [KEY

Now almost any value will reach the program, and the ACCEPT logic handles errors, like give value “A” for a target field defined PIC '999999', properly, producing appropriate error messages.

Appendix: Swagger Definitions

Any web service can be tested with ReadyAPI or your own test utility, but testing JSON services is a lot easier if the service has a definition that complies with the Swagger (or OpenUI) specification. Such a definition uses JSON to describe where to find the service, and BOTH its input and output record definitions, just as WSPGA.wsdl described all this for a SOAP service. Individual definitions like JSPG2I.json describing the input record, and JSPG2O describing the output record were created with the CREATE WSBIND process, but these alone are insufficient for easy testing, although they are sufficient for the service to function provided that you have their formats and know how the service functions.

To facilitate testing MANASYS Jazz creates a Swagger-compliant definition in advance when we create a JSON service. Here’s the New Web Service dialog re-creating JSPG2: -

When we clicked [Finish] this would have created a Jazz definition of the messages, MyJSv-JSPG2.jzc, and the jazz web service JSPG2.jzz. This is processed into COBOL and we created the binding objects JSPG1.wsbind and message descriptions JSPG2I.json and JSPG2O.json. What we probably didn’t notice is that when we created program JSPG2.jzz MANASYS also created JSPG2.json based on the @Swagger template. Here is a copy of JSPG2.json: -

{

"swagger" : "2.0",

"info" : {

"description" : "Test API",

"version" : "1.0.0",

"title" : "Test API, JSPG2"

"paths" : {

"/JSPG2" : {

"post" : {

"description" : "adds a new item",

"consumes" : [ "application/json" ],

"produces" : [ "application/json" ],

"parameters" : [ {

"in" : "body",

"name" : "JSPG2",

"description" : "item to add",

"schema" : {

"$ref" : "JSPG2I.json"

}

} ],

"responses" : {

"201" : {

"description" : "item created",

"schema" : {

"$ref" : "JSPG2O.json"

}

"host" : "localhost:9003",

"basePath" : "/cics/services",

"schemes" : [ "http" ]

}

JSPG2.json contains information like the URL to access the service, the types of messages that it is sent and receives, and references to the definitions of these messages. Initially the message formats don’t exist: they are created later, when we create the binding objects and message descriptions.

The existence of a service definition following the Swagger standard makes it easy to test your program with utilities like ReadyAPI (see example Test JSPG2) and for MANASYS to create service interfaces (see this 3 ½ minute video, and click here to see more detail).

Troubleshooting

As I developed web services with Micro Focus I encountered a number of issues, almost all caused by my own stupidity. Heartfelt thanks to Micro Focus Supportline, especially Maggie Li, Craig Neave, and Jun Fabros, for patiently helping me sort out what was wrong.

General Notes

1. Starting ESMAC

If you’ve forgotten how to do this: In Server Explorer, right-click Micro Focus Servers, and click Administration

This opens the Administration home page. Click [Details] for the started server (in this case CWSDEMO): -

Now click [ES Monitor & Control]: -

2. Micro Focus Server Fault – won’t stop, but doesn’t work

Here Server Explorer shows server TSTSQL started: -

If you try to stop TSTSQL by the preferred method – right-click server TSTSQL, select Stop from the menu – output shows this, and the server remains started.

Stopping TSTSQL ...

CASCF0050S casgate: Console daemon not active, RC = 0015 10:04:38

Failed to connect to region TSTSQL return-code: 1-

Command execution aborted.

Return code: 15

Right-click Micro Focus Servers and select Administration opens Enterprise Server Admin normally. Server TSTSQL seems OK: -

Click [Stop] (recommended) or [Details].

If you click [Details], instead of immediately seeing a Server TSTSQL screen like that above, there will be a pause and then this will be displayed: -

Note the lack of service execution processes. Click [Stop Server].

[Stop] or [Details]/[Stop Server] displays the following. Check Use Force Option and Mark server “Stopped”

Check all three options and click [OK]. Enterprise Server Admin is redisplayed immediately showing server TSTSQL as stopped, and after a short pause this is reflected in the Server Explorer window. It can now be restarted, and shows that everything is normal (for example, all my web services are now running).

Cause

I don’t know what’s causing this, but my suspicion is that it is related to shutting down my Windows laptop and relying on automatic closedown of active applications to close of an active Visual Studio/Micro Focus Enterprise Developer session. I now try to remember to close the Micro Focus Server explicitly if I leave it started when I’m not using it, this seems to avoid this problem. However I haven’t seen this for a long time, so it might have been caused by a fault in Micro Focus Enterprise Developer (MFED) that has been fixed in the upgrades from MFED Version 3 to MFED Version 6

Issue 1: No [WebSvc], [Pipeline], or [Bundle] buttons

If your Enterprise Server is not configured to support CICS Web Services then ESMAC resource displays will include buttons up to [URIMap], but not include [Bundle], [Pipeline], or [WebSvc] which should be the next 3 buttons.

1. Check that your Startup group includes DFHPIPE and DFHWEB: -

ESMAC: select Resources/By Group, click [Startup] => CICS Startup Lists is displayed: -

Click [Details] for your startup list – in my case DEMOSTRT: -

Here we see that DFHWEB and DFHPIPE are already present. If they are not then they can be added by: -

Type DFHWEB into the blank entry at the bottom.

Click [Apply]

You may get error messages when you click [Apply]: -

If so, check that web services are enabled for this server, and fix problems that you find. This may (as in the example below) add DFHTERM and DFHPIPE, [WebSvc] is not present, and it displays a list of programs including the web service that you want to test, and return here.

Else repeat for DFHPIPE: type it into the blank entry at the bottom, and click [Apply]

When you have finished making changes, restart the server

2. Check that Web Services are enabled for this server

In Server Explorer, right-click your running MF Server, and click Show Console Log. This will display the console log in the output window. Scroll to the top of this: -

Here the 10^th message is

190223 09561169 5880 TS2SQL CASSI0017W ES support for CICS WEBSERVICES is disabled. CCSID tables 00037 to Unicode(UCS) not found 09:56:11

This may be because you have never installed the CCSID tables, or because this new server doesn’t have a path to their location. If you have successfully used web services with other servers, then the CCSID tables have been installed, it is the path that is the problem:-

Checking the Project Path

Display Enterprise Server Administration (from Visual Studio/Server Explorer, right-click Micro Focus Servers, click Administration). Or if you already have ESMAC open but on another display, click Home.

Here I had been testing SOAP (=WSDL) web services using server TSTSQLG. I now wanted to test REST (JSON) services, so I was trying to set up server TSTJSON. In this process I encountered Update Error: IO when I tried to add DFHWEB to DEMOSTRT.

Click [Edit] for the server (TSTJSON). Click the MSS tab: -

There is no entry for Resource Definition File Path. It should point to the project folder, so I copied its location (c:\Tutorials\TstSQL) and clicked [Apply]. I restarted server TSTJSON, and re-opened ES Admin and ESMAC. Now I saw the buttons [Bundle] [Pipeline] and [WebSvc], and the startup list included DFHWEB, DFHPIPE, and my own group MANAJAZZ.

Error when Set Resource Definition File Path

When setting up server TSTSQLJ, I copy/pasted the project path as described above, but got this message: -

DF6000E Some or all changes may not have been saved. Error 505 writing to .\.

On restarting the server I found that the entries DFHWEB, DFHPIPE, and MANAJAZZ had been added to the startup list. Now ESMAC, Resources Active shows the Bundle, Pipeline, and WebSvc buttons, [WebSvc] shows active web services.

Installing CCSID Conversion Tables

These MF Help pages explain what CCSID conversion tables are, and how to install them.

CCSID Conversion Tables

To install CCSID tables, open this web page and follow Steps 1 to 5 below.

Step 1. Download cdctables.zip

Click the link cdctables.zip to download it. Copy or move it from the browser’s download folder into folder %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ccsid i.e. C:\Program Files (x86)\Micro Focus\Enterprise Developer\etc\ccsid

Step 2. Open tabindex.txt

The Zip file contains Intro.zip and 6 Package zips, Package1.zip to Package6.zip. For the default CCSID we want tables IBM-37, IBM-437, and 0025901B5. Tabindex.txt, which is in Intro.zip, tells us which package zips we need: -

Step 3. Create Subdirectories

The web page says “For each table you want to install, as a subdirectory to the ccsid directory, create a directory of the same name as the CCSID table filename as specified in the tabindex.txt file.”

With Windows Explorer we create these folders within folder C:\Program Files (x86)\Micro Focus\Enterprise Developer\etc\ccsid

Step 4. Unzip the corresponding files into the appropriate folder

File 002501B5 from Package 4 is unzipped into \002501B5, and files IBM-37 and IBM-437 are unzipped into their respective subfolders. For example, here’s \002501B5: -

Step 5. Restart the MF Enterprise Server

Visual Studio, Server Explorer: Stop and Start server TS2SQL. When it has started Show the Console Log. Now instead of message CASSI0017W we see message CASSI0015I: -

190223 14191966 60972 TS2SQL CASSI0015I ES support for CICS WEBSERVICES is enabled 14:19:19

Once you fix this CCSID issue it should be fixed for all of your COBOL projects, and you won’t need to reload the CCSID tables again. I encountered this problem with my first web service test, and again when I moved to a new laptop.

Issue 2: No Active Web Service

If ESMAC Recources(Active) includes a [WebSvc] button then your server is configured to support web services. If clicking [WebSvc} shows you this, then there is no active web service.

I have encountered 3 reasons for this, although cause 1 may actually be an example of cause 2.

1. basicsoap11provider.xml had been corrupted.

2. Looking in the wrong place for the .xml template

3. Pipeline and TCPIP Service not defined

Cause #1

The first time that this issue was encountered we believed that the cause was that basicsoap11provider.xml had been corrupted. It is supposed to look like this: -

<?xml version="1.0" encoding="EBCDIC-CP-US"?>

<provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline">

<service_handler_list>

</service_handler_list>

<terminal_handler>

<cics_soap_1.1_handler/>

</terminal_handler>

</service>

<apphandler>DFHPITP</apphandler>

</provider_pipeline>

I was sent a new copy which I copied to folder C:\tutorials\XMLCopy. I changed the Config file entry changed to

C:\tutorials\XMLCopy\basicsoap11.xml

Clicked [Apply] => message Update successful

With this change the Verify Web Service step worked correctly.

Cause #2

However, the .xml might not have been corrupted: perhaps the system was looking in the wrong place for the .xml template. In the SOAP Tutorial, in the last step before Verify Resources a CICS pipeline called PROVPIPE is created, as part of group MYCWSPRV: -

Clicking [Details] for PROVPIPE shows: -

Location $IDE_XML_LOC is equivalent to $IDE_PROJECT_LOC\xml. $IDE_PROJECT suggests that there should be a folder \xml within

C:\tutorials\LoanDemo\CICSWebServicesProjectTemplate\loadlib

But Windows Explorer didn’t find such a folder, although there was such a folder directly under CICSWebServicesProjectTemplate.

ESMAC, Active resources, Pipeline =>

[Details] =>

I went back to ESMAC: Resources/by Group, selected group MYCWSPRV, clicked [Details] for PROVPIPE and edited the config file to C:\tutorials\XMLCopy\basicsoap11provider.xml, and clicked [Apply]: -

NB: the LOANDEMO project only had SOAP services. With both SOAP and REST services in project TSTSQL WebSvc Dir would be set to $IDE_LOADLIB\SOAP.

Clicked [Install] =>

Active Resources => [Pipeline] => [Details] =>

I clicked Enabled, then [Apply]. Now Active Resources [Pipeline] =>

And Active Resource [WebSvc] =>

Cause #3 Pipeline and TCPIP Service not defined

With LOANDEMO a group MYCWSPRV was defined. This in turn defines resources CWSTCPIP and PROVIPE to provide the TCPIP Service and the Pipeline that the CICS Web Service requires.

However in project TSTSQL, group MYCWSPRV is not defined in server TS2SQL. We can either define and add it, or add objects like CWSTCPIP and PROVPIPE to group MANAJAZZ. I chose to add to MANAJAZZ. This process is exactly as described in the LOANDEMO tutorial for adding these objects to MYCWSPRV except that the objects are added to MANAJAZZ, and we’ve used C:\tutorials\XMLCopy\basicsoap11provider.xml as the Config file for the pipeline. Cause 3: Detail shows some of the detail of this process.

Once this has been done, server TS2SQL is restarted, and ESMAC, Resources(Active), [WebSvc] now shows: -

Cause 3: Detail

ESMAC, Resources (by Group), [Groups] => shows a list of groups defined for this server TS2SQL.

Click [Details] for group MANAJAZZ: -

Click [TCPIPSv], and define object CWSTCPIP with
            Name: CWSTCPIP
            Description: My TCP/IP Service
            Port no: 5482: -

Click [Add], => message Add successful,

then click [Apply], => message Update Successful

Now click [Pipeline] and define this: -
            Name: PROVPIPE
            Resp Wait: DEFT
            Config file: C:\tutorials\XMLCopy\basicsoap11provider.xml

Click [Add], message Add Successful.

Click [Apply], message Update Successful:-

Issue #3: Everything looks OK from ESMAC, but SOAPUI* tests don’t work.

* You may be using ReadyAPI, Postman, or another test utility, but these can all produce situations like those below.

No doubt there are many more opportunities to mess up, but here’s a few errors that I made: -

3.1: SOAPUI doesn’t respond

Cause 1: I gave the wrong port number, changing the default port to 5483, not the correct value 5482

Cause 2: I had created the service interface as LOANPYM.svi, instead of the correct name of LOANPAYM.svi. The service interface must have the same name as the program that it is invoking.

3.2: SOAPUI responds with a CICSFault error

Case 1. One of my tests returned

The full CICSFault message is

CASPI1010E 19/02/25 21:26:11 CWSDEMO 000039 XML generation failed. A conversion error (INVALID_PACKED_DEC) occurred when converting field principal for WEBSERVICE Loanpaym.

This indicates that the web service is wired up correctly, and the system is trying to pass messages from SOAPUI to the service and back, but there is a problem with the XML. This was caused because I’d incorrectly created the service interface: instead of defining the input message as LOANPAYM(2) and the output as LOANPAYM(3), I’d set both to LOANPAYM(2). Naturally LOANPAYM.wsbind couldn’t convert the output message to the correct format. Problem fixed by deleting and re-creating the service interface, creating the .wsbind and moving it to the \loadlib directory, then restarting the server.

Case 2. Another test returned

CASPI1008E 19/03/27 15:15:41 TS2SQL 000022 XML generation failed because of incorrect input (DATA_STRUCTURE_TOO_SMALL 232) for WEBSERVICE WSPGEM.

Here the cause is not so obvious, but I knew that the request is reaching the program because enquiries were returning valid results, but this update was not. I clicked Start in my Visual Studio MFED COBOL project, and on stepping through the program I found that it was failing when it attempted to execute EXEC SQL UPDATE EMPLOYEE SET … The SQLCode was -530, which is described as

THE INSERT OR UPDATE VALUE OF FOREIGN KEY constraint-name IS INVALID

3.3: Web Sevices and Case

Web services are case sensitive, so in tests – “X” and “x” are different: -

1. Don’t change case. In most of our programming it doesn’t matter if we write “LOANPAYM” or “Loanpaym” or any other combination that spells “loanpaym”. Here it does! For example, if the endpoint is http://localhost:5482/cics/services/LOANPAYM then you won’t find it with … CICS/Services/LOANPAYM or any other case change. Here we’ve written CICS/Services, it should have been cics/services. Similarly, the XML has defined your SOAP message: it probably needs to be <loan:LoanOperation> and variations may not work.

Having developed Classical CICS programs that looked up records by name I was used to just typing “apthorpe” to find a test subject: it came as a surprise to me that <Custf:name>apthorpe</Custf:name> found no records until I entered <Custf:name>APTHORPE</Custf:name>

2. In the request remove ALL question marks. If you don’t want a value, write something like <loan:rate></loan:rate>. If you leave the question mark an error will be caused. I found it convenient to use Replace: -

3. If the web service is not running or you’ve given an incorrect endpoint then you’ll get a response message like

Glossary

.NET	Microsoft’s development framework – a series of support classes used by programs generated with Visual Studio.
ACCT	Not an acronym, but the name of an MFES set up with the MF CICS tutorial.
ASCII	American Standard Code for Information Interchange. The mapping from bytes to characters used by computer manufacturers other than IBM. In ASCII character “A” is represented by hex 41. See also EBCDIC and Unicode. See https://en.wikipedia.org/wiki/ASCII
BMS	Basic Mapping Support. Describes the layout of a 3270-type screen, and provides a program and record layout to translate the COBOL information to/from the display.
CCSID	Means "Coded Character Set Identifier". Your MFES must be set up with at least a minimum list of CCSID’s to support web services in order to be able to convert between different character sets, such as EBCDIC ó ASCII (or Unicode). See https://en.wikipedia.org/wiki/CCSID for a good definition of the concepts involved.
CICS	Customer Information Control System. Part of IBM’s Operating System designed to handle transactions from a large number of on-line users.
CWS	CICS Web Service
EBCDIC	Extended Binary Coded Decimal Interchange Code. The mapping from bytes to characters used by IBM in its mainframe computers. In EBCDIC character “A” is represented by hex “C1”. See also ASCII and Unicode. See https://en.wikipedia.org/wiki/EBCDIC
ESMAC	Enterprise Server Management and Control
FCT	File Control Table. Defines files (and their attributes) that can be accessed by CICS
FTP	File Transfer Protocol. A Protocol to enable a sequential file to be transferred from one computer to another.
IDE	Integrated Development Environment. For example Visual Studio (Microsoft), Eclipse (Open Source)
JSON	JavaScript Object Notation. A lightweight data-interchange format, used in REST services
MF	Micro Focus
MFED	Micro Focus Enterprise Developer
MFES	Micro Focus Enterprise Server
PCT	Program Control Table. Relates a transaction code to a program, e.g. MNU1 initiates program MENU1
PPT	Processing Program Table. Defines programs that may be invoked by transaction id’s in the PCT or by program code. Examples: MENU1, MENU1S (note that a BMS Map is a program).
REST	Representational State Transfer.
SIT	System Initialisation Table. Used by CICS to identify a list of groups to be started.
SOAP	A standard message protocol based on WSDL messages. SOAP stands for “Simple Object Access Protocol”. “Simple” is debatable, “Standard” might have been better.
Unicode	Unicode is a standard that extends ASCII to cover non-English languages, including those like Chinese requiring 2 bytes per character. See https://en.wikipedia.org/wiki/Unicode See also ASCII and EBCDIC.
VS	Visual Studio
VS2017	Visual Studio 2017
WSDL	Web Services Description Language
z/OS	Z-series Operating System. The OS for IBM’s enterprise (mainframe) computers