Skip to content

How it Works

In the Web Services Perspective, the user selects a Source File, which contains separate ENTRY points, (which can contain separate Linkage Sections), for performing functions associated with the POST, GET, PUT, and DELETE functions.

To prepare the source file as a Web Service in the COBOL-IT Web Services Perspective, the user performs the following:

  1. Select a COBOL-IT Setup Script.

  2. Select a Source file from the Developer Studio Project.

  3. Generate an XSD file from the Source file. This process parses the program, and records the names of the entry points, and for each entry point, the linkage section items. This information is stored in an XML format.
    Note that this parsing process can be done at the command line, using the command:
    > cobc -linkage-desc=[programname].xsd [programname].cbl

  4. Select a Templates Folder. This folder will store default templates that are used, as well as customized templates created by the user.

  5. After the XSD file is generated, it is parsed, and COBOL-IT mapping can be done. On the mapping interface, the user associates an entry point that has been recorded in the XSD file with one of the functions, POST, GET, PUT, DELETE.

  6. The user saves the mappings, and then generates a Bridge Program.

  7. Depending on the environment, the user runs a script in which the Bridge Program and web service program are compiled together. When using the xbind solution, the programs are compiled with the -b compiler option to create a single shared object. When using the Apache Web Server solution, the programs are compiled to create an executable and the executable is copied into the cgi-bin directory of the Web Server.

  8. In our samples, we use Firefox to run HTML files, with different characteristics for the xbind and Apache web server solutions. In both cases, you can run POST, GET, PUT, or DELETE functions, and view the data passing from the Client to the Server, and back to the Client, with information provided during the transaction.

Open the Web Services Perspective

From the Open Perspective dialog screen, select COBOL-IT Web Services. Click OK to open the COBOL-IT Web Services Perspective.

Open Perspective

Setup the Environment

Setup script

Select the cobol-it-setup shell script in the bin directory of your COBOL-IT installation.

Setup Script

Source file

Select a source file from your project directory. In our example, we are using holidays.cbl, for which the source is included in Appendix A.

Source File

*.xsd file

Click on the Generate button or use the Browse button to locate and select the .xsd file. The xsd file will be generated and parsed in your Project Folder. During the parsing, entry-points will be detected and fields in the Entry mapping interface will be populated.

Generate xsd File

The xsd file

xsd File

Templates dir

In our project, we have added a folder called templates. In the Settings interface, use the Browse button to locate the Templates Folder, and select it. Templates are used to generate the Bridge Program. When you generate a Bridge Program, you will have the option to select one of the default templates, and your selection will be stored in the Templates Folder. You may also store customized templates in your Templates Folder, and will be able to select them for use in generating your Bridge Program.

Templates

The COBOL-IT Web Services Toolbar

Toolbar

Reset Icon Reset Settings

The Reset Settings function has the effect of clearing all of the Settings and Entry-mapping selections. If you have changed the linkage section in one of the entry points in your source file, but have not regenerated an XSD file, or if you have made modifications to your Entry-mapping, but have not generated a new Bridge Program, they you can get in a situation where some of the elements of your solution are out of sync. It is important to be aware of the dependencies between the different elements in the Web Services Perspective. There are times when best practice is to clear the Settings, and re-enter the different fields.

Clear Mapping Icon Clear Mapping

When you have entered all of your Settings, and made your mapping choices, and SAVE'd your mapping choices, you will see that the WSV file has been created in your project directory. The WSV file contains all of the mapping choices you have made, laid upon the information in the XSD file. This information is used in both the generation of the Bridge Program, and the generation of the input strings. The Clear Mapping function keeps the Settings intact, but removes all of the current mappings that you have made. Reset your mappings, and SAVE them, to generate a new WSV file.

Show Structure I-O Messages Icon Show Structure I-O Messages Icon

The Show Structure I-O messages interface opens the interface for generating Input Strings. In the Input Message area, you should validate the program name of the COBOL-IT Web Service, and the Entry Point for which you are generating an input string. The interface allows you to overwrite the int castings with integers, and the char* castings with character strings. When you have completed this exercise, click on the Copy input message button to copy the data to the Clipboard. Then, Click OK to close the dialog window. In our samples, we create empty textfiles to hold our input strings, and store them in the Project.

Copy Input Message

Save Icon Save

The Save button has the effect of SAVE'ing all of your Mappings in a WSV file that is stored in your project.

Generate Bridge Program Icon Generate Bridge Program.

Select the Generate Bridge Program button to open a drop-down box, displaying default templates, and customized templates that are stored in the templates folder.

After you have made your selection, you will see the default name and location of the generated program, which you may change or accept. The default name and default program-id of the generated program is the name of the COBOL-IT Web Service program, pre-pended with an “x”.

Bridge Program Location

Entry Mapping

The Entry Mapping interface consists of two dropdown boxes. The left-most dropdown box lists the names of the entry points in the COBOL-IT Web Service program. The right-most dropdown box lists the names of the functions, POST, GET, PUT, DELETE. It is necessary to match the name of an entry point to the name of a function, in order to generate the input string that can provide access to that function.

In our sample program, there are 5 entry points:

Entry Point Description
holidays representing the PROCEDURE DIVISION entry point.
postholiday representing ENTRY 'postholiday' USING hol-linkage.
getholiday representing ENTRY 'getholiday' USING hol-linkage.
putholiday representing ENTRY 'putholiday' USING hol-linkage.
deleteholiday representing ENTRY 'deleteholiday' USING hol-linkage.

Entry Mapping

In our sample program, there are 4 ENTRY statements, which contain code that is designed to perform the associated service:

Entry Statement Service
postholiday Performs an OPEN OUTPUT, and a WRITE.
getholiday Performs an OPEN INPUT, and a READ.
putholiday Performs an OPEN I-O, a READ and a REWRITE.
deleteholiday Performs an OPEN I-O, a READ and a DELETE RECORD.

Use the left-most Entry mapping dropdown box to select the name of the entry point in the program. Use the right-most Entry mapping dropdown box to select the function with which that ENTRY statement should be associated.

Entry Mapping Output

Update, Save the Mapping Interface for each function

As you associate an ENTRY point with a function, the COBOL-IT mapping for that ENTRY statement is displayed. The Cast and IO functions are pre-filled with defaults, which can be changed. The Save button is on the Settings Toolbar. When you save your Entry mappings, a file with extension .wsv is generated into your Project Folder. This file is used in the generation of the Bridge Program. As a result, you must first Save your settings, then generate your Bridge Program.

Save Mapping Interface

The .wsv file

The .wsv file contains all of the mappings you have saved.

       <MODEL sourceFile="/root/data/RECTools/devstudio/CDS203-0930/workspace/xproject1/holidays.cbl" 
       xsdModel="/root/data/RECTools/devstudio/CDS203-0930/workspace/xproject1/holidays.xsd">
              <ENTRY name="postholiday" function="Post">
                     <FIELD name="hol-linkage">
                            <FIELD name="hol-rec">
                                   <FIELD name="hol-id" cast="int" io="Input-Output"/>
                                   <FIELD name="hol-name" cast="char*" io="Input-Output"/>
                                   <FIELD name="hol-dt">
                                          <FIELD name="hol-wkday" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-mon" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-day" cast="int" io="Input-Output"/>
                                          <FIELD name="hol-yr" cast="int" io="Input-Output"/>
                                   </FIELD>
                                   <FIELD name="hol-cur-dt" cast="char*" io="Input-Output"/>
                            </FIELD>
                            <FIELD name="hol-io-msg" cast="char*" io="Input-Output"/>
                     </FIELD>
              </ENTRY>
              <ENTRY name="getholiday" function="Get">
                     <FIELD name="hol-linkage">
                            <FIELD name="hol-rec">
                                   <FIELD name="hol-id" cast="int" io="Input-Output"/>
                                   <FIELD name="hol-name" cast="char*" io="Input-Output"/>
                                   <FIELD name="hol-dt">
                                          <FIELD name="hol-wkday" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-mon" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-day" cast="int" io="Input-Output"/>
                                          <FIELD name="hol-yr" cast="int" io="Input-Output"/>
                                   </FIELD>
                                   <FIELD name="hol-cur-dt" cast="char*" io="Input-Output"/>
                            </FIELD>
                            <FIELD name="hol-io-msg" cast="char*" io="Input-Output"/>
                     </FIELD>
              </ENTRY>
              <ENTRY name="putholiday" function="Put">
                     <FIELD name="hol-linkage">
                            <FIELD name="hol-rec">
                                   <FIELD name="hol-id" cast="int" io="Input-Output"/>
                                   <FIELD name="hol-name" cast="char*" io="Input-Output"/>
                                   <FIELD name="hol-dt">
                                          <FIELD name="hol-wkday" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-mon" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-day" cast="int" io="Input-Output"/>
                                          <FIELD name="hol-yr" cast="int" io="Input-Output"/>
                                   </FIELD>
                                   <FIELD name="hol-cur-dt" cast="char*" io="Input-Output"/>
                            </FIELD>
                            <FIELD name="hol-io-msg" cast="char*" io="Input-Output"/>
                     </FIELD>
              </ENTRY>
              <ENTRY name="deleteholiday" function="Delete">
                     <FIELD name="hol-linkage">
                            <FIELD name="hol-rec">
                                   <FIELD name="hol-id" cast="int" io="Input-Output"/>
                                   <FIELD name="hol-name" cast="char*" io="Input-Output"/>
                                   <FIELD name="hol-dt">
                                          <FIELD name="hol-wkday" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-mon" cast="char*" io="Input-Output"/>
                                          <FIELD name="hol-day" cast="int" io="Input-Output"/>
                                          <FIELD name="hol-yr" cast="int" io="Input-Output"/>
                                   </FIELD>
                                   <FIELD name="hol-cur-dt" cast="char*" io="Input-Output"/>
                            </FIELD>
                            <FIELD name="hol-io-msg" cast="char*" io="Input-Output"/>
                     </FIELD>
              </ENTRY>
       </MODEL>

Generate Bridge Program

It is only necessary to generate a single Bridge Program for the multiple mappings that have been made. It is necessary, however, to generate separate Bridge Programs for the xbind solution and Apache Web Server solution.

As you drop down the Generate Bridge Program combo box, you will see the two default templates described at the top, and the customized templates, stored in the Templates Folder below them. In our sample, we are selecting the template which is designed to accept the incoming data in linkage, as is required when using xbind. The Bridge Program generator suggests a default name and location in which the program is generated. The default location is the Project Folder. The default name prepends an “x” to the name of the COBOL-IT Web Service program.

Click Save to generate the Bridge Program in the Project Folder.

Bridge Program Generation

Refresh your Developer Studio Project

When using the Remote System Explorer, a remote project may need to be refreshed to display new files added. To refresh your project, right-click on the project name in the Developer Studio and select the Refresh function. Your project’s artifacts now include the generated xsd file, the wsv file generated after the mapping was completed and saved, and the Bridge Program (xholidays.cbl).

Refresh Project

A view of your COBOL-IT Web Services Project

A number of new files have been added to your Web Services Project.

Note

When using the Remote System Explorer, right-click on the Project Folder, and select the Refresh function to make sure that your view of the folder is fully refreshed.

Filename Description
holidays.cbl The original COBOL-IT Web Service source file
holidays.so Created during the compilation that generated the XSD file
holidays.xsd Created in the Settings interface with the Generate (*.xsd) function
holidays.wsv Contains mapping information. Generated with the Save function on the Settings toolbar
xholidays.cbl The generated Bridge Program

Project View

Back to top