Overview

The COBOL-IT Web Services Perspective in the Developer Studio provides a platform that allows the user to convert a COBOL-IT Web Service program into a callable Web Service. The RESTful Web Service functions, POST, GET, PUT, and DELETE, map well to common COBOL operations. A single COBOL program can have entry points mapped to each of these functions.

In our samples, we will be using indexed files as the target of the COBOL operations.

Function	File
RESTful Web Service function	COBOL operation
POST	OPEN [OUTPUT/I-O FILE], WRITE
GET	OPEN [INPUT FILE], READ
PUT	OPEN [I-O FILE], REWRITE
DELETE	OPEN [I-O FILE], DELETE RECORD

The COBOL-IT Web Services Perspective provides two outputs which allow the COBOL-IT Web Service program to be converted into a callable Web Service. These are the INPUT STRING, and the BRIDGE PROGRAM. The COBOL-IT Web Services Perspective supports three different configurations, the Wildfly Application Server Configuration, the Apache Web Server Configuration and the xbind configuration.

The Apache Web Server Configuration

In the Apache Web Server Configuration, the Bridge Program is executed from within a script located in the cgi-bin folder of the Web Server.

In our example, the shell is identified as:

form action=http://localhost/cgi-bin/xholidays41.sh in the html file executing on the client. The shell script is required because COBOL-IT must be able to locate the license file, and the COBOL-IT environment must be setup.

The WildFly (JBoss) Configuration

In the WildFly Application Server Configuration, the Bridge Program is executed from within a script located in the … folder of the Application Server.

In our example, the shell is identified as:

form action=http://… in the html file executing on the client. The shell script is required because COBOL-IT must be able to locate the license file, and the COBOL-IT environment must be setup.

The xbind Configuration

In the xbind Configuration, the Bridge Program is executed directly by the xbind listener.

In our example, the listener is launched from a shell script ./xbind 9735 xholidays & and identified as:

form action="http://localhost:9735" in the html file executing on the client. The shell script is required because COBOL-IT must be able to locate the license file, and the COBOL-IT environment must be setup.

The BRIDGE PROGRAM

The COBOL-IT Web Services Perspective uses templates to generate the bridge program, which can be customized. The default templates that are provided correspond to the two different configurations supported for COBOL-IT Web Services. Note that the MESSAGE is the INPUT-STRING, which has been URL-encoded.

Template	Application
sysin_bridge_template.xml	Apache Web Server configuration - ACCEPTS MESSAGE from SYSIN
xbind_bridge_template.xml	xbind configuration - MESSAGE passed through Linkage

The generated bridge program is designed to decode the URL-encoded string, and call the appropriate entry-point. In our sample COBOL-IT Web Service Program, there are four entry-points, called postholiday, getholiday, putholiday, and deleteholiday. Each of the entry-point requires that an INPUT STRING be generated for it. Then, in our samples, we will see how that INPUT STRING is, first encoded, by the Client, then decoded by the Bridge program, which will then CALL the appropriate Entry point in the COBOL-IT Web Service Program.

The INPUT STRING

The INPUT STRING is generated in XML format, and includes such information as the name of the COBOL-IT Web Service Program, the name of the entry-point in the COBOL-IT Web Service Program that is to be CALL’ed, and the parameter names in the USING clause for the CALL’ed entry point, with values, where applicable. When populating a record for purposes of a WRITE, all fields might contain values. In an indexed file, when retrieving a record, for purposes of a READ, a REWRITE, or a DELETE, only the KEY field is required.

A sample INPUT STRING for a POST in holidays.cbl, with ENTRY postholiday USING hol-linkage.

<PROGRAM name="holidays"><ENTRY name="postholiday"><PARAM name="hol-linkage"><hol-linkage><hol-rec><hol-id>0</hol-id><hol-name>Christmas</hol-name><hol-dt><hol-wkday>Wednesday</hol-wkday><hol-mon>December</hol-mon><hol-day>25</hol-day><hol-yr>2019</hol-yr></hol-dt><hol-cur-dt>char*</hol-cur-dt></hol-rec><hol-io-msg>char*</hol-io-msg></hol-linkage></PARAM></ENTRY></PROGRAM>

The COBOL-IT Web Service Program Entry Points

REWRITE PARA?

The key elements, for purposes of generating the INPUT STRING and the Bridge Program are the Entry-points. A quick examination of the way our sample COBOL-IT Web Service Program is constructed shows INCOMPLETE TEXT? . In simplified terms, the program CALLs the entry point using the linkage section, which consists of the elements of the holiday record, and at the end, an io-message, which conveys the file status result of the key operation. Each of these entry-points must have its own INPUT STRING generated for it, as the INPUT STRING contains the name of the entry point to be called.

       PROCEDURE DIVISION.
      *
       ENTRY 'postholiday' USING hol-linkage.
       OPEN OUTPUT holidaysIX.
       WRITE holiday-record.
       MOVE holiday-io-msg TO hol-io-msg.
       CLOSE holidaysIX.
       GOBACK.
      *
       ENTRY 'getholiday' USING hol-linkage.
       OPEN INPUT holidaysIX.
       READ holidaysIX KEY IS holiday-name.
       MOVE holiday-io-msg TO hol-io-msg
       CLOSE holidaysIX.
       GOBACK.
      *
       ENTRY 'putholiday' USING hol-linkage.
       OPEN I-O holidaysIX.
       READ holidaysIX KEY IS holiday-name.
       REWRITE holiday-record.
       MOVE holiday-io-msg TO hol-io-msg.
       CLOSE holidaysIX.
       GOBACK.
      *
       ENTRY 'deleteholiday' USING hol-linkage.
       OPEN I-O holidaysIX.
       READ holidaysIX KEY IS holiday-name.
       DELETE holidaysIX RECORD.
       MOVE holiday-io-msg TO hol-io-msg.
       CLOSE holidaysIX.
       GOBACK.
      *
       UPDATE-HOL-IO-MSG.
       INITIALIZE hol-io-msg.
       STRING "HOLIDAY-STATUS:" DELIMITED BY SIZE,
       holiday-status DELIMITED BY SIZE,
       INTO holiday-io-msg.
      *