Developing COBOL Servlets

Programming Guides : Servlets & CGI : Developing COBOL Servlets

Developing COBOL Servlets

Note - the approach described here is deprecated. Veryant recommends the EIS solution as best practice to create COBOL Servlets. See COBOL Servlet option (OOP) for details.

The process for developing a COBOL servlet can be very similar to that for developing a CGI program. However, it really depends on what the HTML, Javascript or other Web programming code requires.

Simple COBOL Servlet

Here is a simple COBOL servlet that takes a CGI form field, NAME, as input and sends an HTML response with "Hello NAME" as output:

*> Sample servlet that takes a NAME field and outputs "Hello <NAME>"

class-id. Sample           as "Sample" inherits HttpServlet.

configuration section.

repository.

  class HttpServlet         as "javax.servlet.http.HttpServlet"

  class HttpServletRequest  as "javax.servlet.http.HttpServletRequest"

  class HttpServletResponse as "javax.servlet.http.HttpServletResponse"

  class ServletOutputStream as "javax.servlet.ServletOutputStream"

  .

*> Object Methods

identification division.

object.

procedure division.

*> doPost: Invoked when a POST type request occurs

identification division.

method-id. doPost            as "doPost" override.

data division.

working-storage section.

77 name-field                pic x any length.

77 out                       object reference ServletOutputStream.

linkage section.

77 req                       object reference HttpServletRequest.

77 res                       object reference HttpServletResponse.

procedure division using req res.

main.

   try

      set out to res:>getOutputStream()

   catch exception

      goback

   end-try.

   set name-field to req:>getParameter"("NAME").

   try

      out:>println('<html>' as string)

      out:>println('<head>' as string)

      out:>println('<title>Sample</title>' as string)

      out:>println('</head>' as string)

      out:>println('<body>' as string)

      out:>print('Hello ' as string)

      out:>print(name-field as string)

      out:>println('</body>' as string)

      out:>println('</html>' as string)

   catch exception

      continue

   end-try.

end method.

end object.

Basic Structure of the COBOL Servlet Class

As you can see from the example above, object oriented COBOL (OOCOBOL) syntax is used to make the COBOL servlet class. There are 5 characteristics of this class that are common in servlets designed to replace CGI programs:

1.

The servlet class "inherits" javax.servlet.http.HttpServlet which allows it to plug-in to any standard servlet container (i.e. web server that supports servlets)

2.

It defines a doPost method override which takes as parameters the HttpServletRequest and HttpServletResponse object references. Servlets can also override the doGet method, or can override both doPost and doGet. These correspond to the GET and POST CGI methods. For example, doPost will be called if the HTML has <FORM method="post" ... >. For more information about get and post see the "Form submission method" section of the W3C HTML specification at:

http://www.w3.org/TR/html4/interact/forms.html#h-17.13.1.

3.

The servlet class invokes the HttpServletResponse getOutputStream method to save the ServletOutputStream object in a variable named "out".

4.

It invokes the HttpServletRequest getParameter method to get the value of the CGI field.

5.

And finally it invokes the ServletOutputStream print and println methods to send the output back to the client.

NOTE - It may be desirable to put all of the OOCOBOL syntax in the COBOL servlet class alone and have the COBOL servlet class CALL other COBOL subprograms that do not have OOCOBOL syntax in them. Or limit the amount of OOCOBOL syntax that is required in the CALLed COBOL subprograms.

Compiling the COBOL Servlet

In order to compile the COBOL servlet, the class path must include a jar file containing the servlet API. This jar file is generally named servlet-api.jar and is located in the servlet container's installation lib directory. servlet-api.jar contains the javax.servlet.* classes.

Using Tomcat 7 add C:\Program Files\Apache Software Foundation\Tomcat 7.0\lib\servlet-api.jar to the class path. For example:

set CLASSPATH=%CLASSPATH%;C:\Program Files\Apache Software Foundation\Tomcat 7.0\lib\servlet-api.jar

iscc Sample.cbl

This will produce a single class file Sample.class that will be "deployed" to the servlet container.

The Web Application

The Servlet 2.4 Specification defines a web application as a collection of servlets, JSP pages , HTML documents, and other web resources which might include image files, compressed archives, and other data. A web application may be packaged into an archive or exist in an open directory structure.

Our simple COBOL servlet might be deployed in a web application with the following directory structure and files:

webapps/SampleServlet/

index.html

WEB-INF/

web.xml

classes/

Sample.class

lib/

There are two files to create in addition to the COBOL servlet class; 1) index.html test page and 2) WEB-INF/web.xml deployment descriptor

index.html Test Page

This is a test web page used to test the servlet. You may also put any kind of web content in this page for users to see if they try to access the servlet directly through its URI.

WEB-INF/web.xml Deployment Descriptor

The WEB-INF/web.xml file contains all information the servlet container needs to know about the servlet.

A web.xml file will look something like the following:

<!DOCTYPE web-app

    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>



    <servlet>

      <servlet-name>SampleServlet</servlet-name>

      <servlet-class>Sample</servlet-class>

    </servlet>



    <servlet-mapping>

      <servlet-name>SampleServlet</servlet-name>

      <url-pattern>/blue</url-pattern>

    </servlet-mapping>



    <filter>

      <filter-name>CobolFilter</filter-name>

      <display-name>CobolFilter</display-name>

      <description>CobolFilter</description>

      <filter-class>com.iscobol.web.IscobolFilter</filter-class>

    </filter>



    <filter-mapping>

      <filter-name>CobolFilter</filter-name>

      <url-pattern>/*</url-pattern>

    </filter-mapping>



  <listener>

   <listener-class>

    com.iscobol.web.IscobolSessionListener

   </listener-class>

  </listener>

</web-app>

The above web.xml file can be copied and used to test any COBOL servlet. It is only necessary to edit the <servlet> and <servlet-mapping> elements.

NOTE - The com.iscobol.web.IscobolFilter Class

The purpose of the com.iscobol.web.IscobolFilter class is to link the COBOL programs with the Servlet session so that the same instance of a COBOL program will get used each time it is called in a particular session. In other words, The IscobolFilter class makes sure that each request from a particular user session will use the same COBOL thread context. The COBOL thread context applies only to traditional COBOL programs that have PROGRAM-ID. It does not apply to COBOL object classes that have CLASS-ID instead of PROGRAM-ID.

For example, when a particular web browser causes a servlet to invoke COBOL PROG1, the next time that same web browser session causes the servlet to invoke it, PROG1 will have the same working-storage values and file states as PROG1 left them on the previous call.

Of course, when converting CGI programs at first you probably will want the servlet to CANCEL the program after the CALL so that the behavior will match the older stateless CGI behavior. But if you want to take advantage of the servlet stateful session life-span you can do so by removing the CANCEL.

> Sample servlet that takes a NAME field and outputs "Hello <NAME>" class-id. Sample as "Sample" inherits HttpServlet. configuration section. repository. class HttpServlet as "javax.servlet.http.HttpServlet" class HttpServletRequest as "javax.servlet.http.HttpServletRequest" class HttpServletResponse as "javax.servlet.http.HttpServletResponse" class ServletOutputStream as "javax.servlet.ServletOutputStream" . > Object Methods identification division. object. procedure division. *> doPost: Invoked when a POST type request occurs identification division. method-id. doPost as "doPost" override. data division. working-storage section. 77 name-field pic x any length. 77 out object reference ServletOutputStream. linkage section. 77 req object reference HttpServletRequest. 77 res object reference HttpServletResponse. procedure division using req res. main. try set out to res:>getOutputStream() catch exception goback end-try. set name-field to req:>getParameter"("NAME"). try out:>println('<html>' as string) out:>println('<head>' as string) out:>println('<title>Sample</title>' as string) out:>println('</head>' as string) out:>println('<body>' as string) out:>print('Hello ' as string) out:>print(name-field as string) out:>println('</body>' as string) out:>println('</html>' as string) catch exception continue end-try. end method. end object.

set CLASSPATH=%CLASSPATH%;C:\Program Files\Apache Software Foundation\Tomcat 7.0\lib\servlet-api.jar iscc Sample.cbl

webapps/SampleServlet/ index.html WEB-INF/ web.xml classes/ Sample.class lib/

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> <!-- The following servlet element defines a servlet called SampleServlet. The Java class of this servlet is named Sample --> <servlet> <servlet-name>SampleServlet</servlet-name> <servlet-class>Sample</servlet-class> </servlet> <!-- The following servlet-mapping maps the servlet called SampleServlet (see the servlet element) to a url-pattern of "blue". The url-pattern is used when requesting this servlet, for example: http://host:port/blue. --> <servlet-mapping> <servlet-name>SampleServlet</servlet-name> <url-pattern>/blue</url-pattern> </servlet-mapping> <!-- The following filter associates COBOL programs with servlet sessions so that the same instance of a COBOL program will get used each time it is called in a particular session. --> <filter> <filter-name>CobolFilter</filter-name> <display-name>CobolFilter</display-name> <description>CobolFilter</description> <filter-class>com.iscobol.web.IscobolFilter</filter-class> </filter> <!-- The following filter-mapping maps the filter called CobolFilter (see the filter element) to a url-pattern of "/" so that every request to http://host:port will be passed through CobolFilter --> <filter-mapping> <filter-name>CobolFilter</filter-name> <url-pattern>/</url-pattern> </filter-mapping> <!-- The following listener allows to correctly close correctly every file connector executable instance when the servlet terminates --> <listener> <listener-class> com.iscobol.web.IscobolSessionListener </listener-class> </listener> </web-app>

NOTE - The com.iscobol.web.IscobolFilter Class The purpose of the com.iscobol.web.IscobolFilter class is to link the COBOL programs with the Servlet session so that the same instance of a COBOL program will get used each time it is called in a particular session. In other words, The IscobolFilter class makes sure that each request from a particular user session will use the same COBOL thread context. The COBOL thread context applies only to traditional COBOL programs that have PROGRAM-ID. It does not apply to COBOL object classes that have CLASS-ID instead of PROGRAM-ID. For example, when a particular web browser causes a servlet to invoke COBOL PROG1, the next time that same web browser session causes the servlet to invoke it, PROG1 will have the same working-storage values and file states as PROG1 left them on the previous call. Of course, when converting CGI programs at first you probably will want the servlet to CANCEL the program after the CALL so that the behavior will match the older stateless CGI behavior. But if you want to take advantage of the servlet stateful session life-span you can do so by removing the CANCEL.

Please share your comments on this manual or on any
Veryant product documentation with the email button at the top left