Enable IBM® Informix® 4GL (I4GL) as a service consumer to leverage and reuse existing Web services and business logic coded in I4GL or other programming languages. Enabling I4GL as a service consumer opens up many possibilities of using I4GL to communicate with any programming language while still enjoying the ease of coding using I4GL.

Share:

Gagan Maheshwari (gagmahes@in.ibm.com), Technical Lead, IBM

Gagan Maheshwari photoGagan Maheshwari is a technical lead at IBM. He has worked on IDS and Informix 4GL (I4GL) as a design and development engineer.



Ramesh Gopal Srinivasan (ramesrin@in.ibm.com), Software Engineer, IBM

Ramesh Srinivasan photoRamesh Srinivasan is a software engineer at IBM. He has worked as part of the Informix team as a developer for the past three years.



Navya Ramachandraiah (navramac@in.ibm.com), Software Engineer, IBM

Navya Ramachandraiah photoNavya Ramachandraiah is a software engineer at IBM. She is a member of the Informix 4GL (I4GL) development team.



29 October 2009

Introduction

Informix 4GL (I4GL) is a rapid development tool that provides easy language support for creating applications for Informix databases. With the introduction of I4GL v7.50, you can publish your I4GL legacy code as a Web service, thus enabling your I4GL applications to be accessed from client applications.

This is the second of two developerWorks articles explaining how to use I4GL v7.50 Web deployment and subscription features. The article "Deploy 4GL functions as Web services" (developerWorks, February 2009) explains how to deploy I4GL functions as Web services, and provides insights into Service-Oriented Architecture (SOA) and I4GL usage in an SOA environment. This article builds upon that information and explains how to subscribe to a Web service using an I4GL subscriber.


I4GL as a service consumer in an SOA environment

Service-Oriented Architecture (SOA) is an architectural style that provides methods for allowing different applications to exchange data with one another. It aims at a loose coupling of services with operating systems, their programming languages, and other technologies with underlying applications.

SOA enablement on I4GL is an innovative attempt to ensure the maximum use of legacy business logic by a wider set of applications within and outside an organization. I4GL v7.50.xC2 (released in December 2008) enabled users to publish their existing business logic written in I4GL as Web services; these Web services can then be consumed by any programming language or application. The v7.50.xC3 (released in May 2009) takes this SOA initiative a step further by enabling consumption of Web services using I4GL.

Prior to v7.50 SOA enablement, I4GL developers were faced with challenges in integrating business logic and applications written in I4GL with other modern applications and languages. In addition, organizations seeking flexibility and inter-operation of code written in multiple languages across diverse locations had only one option—to rewrite the I4GL code using a newer technology.

Figure 1. Architecture of I4GL-SOA subscriber
Diagram of I4GL-SOA subscriber architecture, using boxes and arrows

The I4GL-SOA subscriber architecture relies on a user interface (in other words, W4GL). The users obtain the information of a Web service from a Web service definition file and provide the details in the W4GL interface. The W4GL interface generates and stores all these details in a configuration file. The W4GL interface supplies the configuration file as an input to a back-end script (in other words, W4GLC). The W4GLC tool generates intermediate client code to subscribe to a Web service.


Prerequisites

You must have one of the following platforms to be able to consume Web services using Informix 4GL:

  • HP-IA 11.23 / 11.31 (32/64-bit)
  • Red Hat Enterprise Linux® 4 or 5
  • Solaris 5.9 / 5.10 (32/64-bit)
  • SUSE Linux Enterprise Server 10

Your system must also have the following software:

  • Apache Axis2/C, Version 1.5 (bundled with Informix 4GL C Compiler implementation)
  • Apache Axis2/Java™, Version 1.3.1 (bundled with Informix 4GL C Compiler implementation)
  • IBM Informix Dynamic Server, Versions 10.00, 11.10, or 11.50
  • Informix 4GL 7.50.xC3
  • Java Runtime Environment (JRE) 1.5 or later
  • Perl 5.8.8 or later

Setting the environment

Table 1 outlines the environment variables, which must be set as described:

Table 1. Setting environment variables
Environment variableSet to
AXIS2C_HOME Axis2C installation directory.
INFORMIXDIRLocation where the I4GL product is installed.
PROGRAM_DESIGN_DBSDatabase used for storing Web service definitions entered using the w4gl tool (optional).

If PROGRAM_DESIGN_DBS is not specified by the user, syspgm4gl is used as the default database name. If PROGRAM_DESIGN_DBS is specified, then the relevant tables and schema are created when the w4gl tool is started.
INFORMIXSERVERInformix server name on which the PROGRAM_DESIGN_DBS database is located/created.
INFORMIXSQLHOSTSLocation of the sqlhosts file.
LD_LIBRARY_PATHPath to the shared libraries.
PATHPath to include the location of the executables. This path must include $JAVA_HOME/bin.
JAVA_HOMEJRE 1.5 or later installation location.
DBPATHPath to the compiled form files used by the w4gl tool. It must be set to $INFORMIXDIR/etc.
AXIS_JAR_DIRLocation of .jar files used by AXIS server. These jar files are mandatory for enabling I4GL SOA functionality.
CLASSPATHAbsolute path and name of the jar files needed for I4GL SOA functionality.
DB_LOCALEDatabase locale containing Web service information
CLIENT_LOCALEI4GL client locale (optional).
TERMCAP$INFORMIXDIR/etc/termcap path (optional).

Configuration file

The configuration file contains the details of the Web service definition generated by the W4GL tool. The configuration file example in Listing 1 below is based on the options the options shown in Figures 3 through 5:

Listing 1. w4gl configuration file example
[SERVICE]
   TYPE = subscriber
   I4GLVERSION = 7.50.xC3
   TARGET_DIR  = /tmp/zipcodedemo
   I4GL_FUNCTION = cons_ws_zipcode
   TARGET_FILE = cons_ws_zipcode.c
   [WSDL_INFO]
       WSDL_PATH = /tmp/zipcodedemo
       WSDL_FILE = zipcode_details.wsdl
       WSDL_NAME_SPACE= http://www.ibm.com/zipcode_details
       [FUNCTION]
           SERVICENAME = ws_zipcode
           NAME = zipcode_details
           [INPUT]
               [VARIABLE]NAME = pin TYPE = CHAR(10)[END-VARIABLE]
           [END-INPUT]
           [OUTPUT]
               [VARIABLE]NAME = city TYPE = CHAR(100)[END-VARIABLE]
               [VARIABLE]NAME = state TYPE = CHAR(100)[END-VARIABLE]
           [END-OUTPUT]
        [END-FUNCTION]
    [END-WSDL_INFO]
[END-SERVICE]
Table 2. w4gl configuration file keyword descriptions
Keyword nameDescription
[SERVICE]
…..
[END-SERVICE]
Block containing the set of parameters required to consume a Web service.
TYPE Service operation, either publisher or subscriber.
TARGET_DIR Target directory for the generated source code and object files.
I4GL_FUNCTION Unique user-defined function name containing the auto-generated code to consume a Web service. This is the function that the I4GL developer references in the I4GL program to consume a specified Web service.
TARGET_FILE User-defined filename in which the generated subscriber client code is stored by the tool.
[WSDL_INFO]
….
[END-WSDL_INFO]
Block containing the parameters obtained from the WSDL file for the Web service to be consumed.
WSDL_PATH Directory location of the downloaded WSDL file.
WSDL_FILE WSDL filename containing the Web service details.
WSDL_NAME_SPACE A uniform resource identifier (URI) providing a unique name to associate with the element, attribute, and type definitions in an XML schema, or with the names of elements, attributes, types, functions, and errors in XQuery expressions.
[FUNCTION]
….
[END-FUNCTION]
Block containing the function details to be consumed.
SERVICENAME Service name to be consumed.
NAME Name of the function (operation in WSDL) to be consumed.
[INPUT]
….
….
[END-INPUT]
List of input parameters to the Web service function.
[OUPUT]
….
[END_OUTPUT]
List of output parameters from the Web service function.
[VARIABLE]
….
[END_VARIABLE]
Block containing the variable names and the corresponding data types of input and output parameters of the Web service function.
NAME Keyword identifying input and output variable names as specified in the service definition.
TYPE Keyword identifying input and output data type as specified in the service definition.

The tools

You can use either the w4glc or the w4gl tool to auto-generate the code required to consume a Web service using an I4GL program.

The w4glc tool

This command-line tool is used to generate the code required to establish a connection with the Web service. The w4glc tool expects a configuration file as an input. Advanced I4GL developers familiar with the configuration file syntax may want to use the w4glc tool for faster generation of code.

Listing 2. w4glc syntax
w4glc { [-silent] [-generate] [-compile] } <configuration_file>
  • silent suppresses all the messages from the compiler.
  • generate generates the client source code.
  • compile compiles the generated source code and creates object files.

W4GL tool

As described in the article "Deploy 4GL functions as Web services," the W4GL tool manages data within the program design database. It also provides options to package individual Web services so that services can be relocated to another machine of the same configuration and platform. Once the data is available in the database, the same service can be generated for various platforms using W4GL on those respective platforms.

The W4GL tool also provides the interface to generate configuration files and generates necessary intermediate C language code required for subscribing to a Web service.

The W4GL tool subscriber option menu is displayed in Figure 2:

Figure 2. Hierarchical W4GL tool, subscriber option menu
Diagram of W4GL tool subsriber option menu; Subscribe: Query; Next; Previous; Add: Detail, Variable, Exit; Modify: Detail, Input, Output, Exit; Remove; Detail; Variable; Compile; Exit

Consider the following advantages of using the W4GL tool:


Add a Web service

To subscribe to a Web service, you must first add a Web service definition by selecting Subscribe > Add.

Figure 3 is an example of an Add screen for a Web service named ws_zipcode:

Figure 3. ws_zipcode Web service details
Screenshot of the Add screen for a Web service, where you specify the Web service parameters

The Subscription ID field is a unique identification number generated by the w4gl tool to track the Web service definition.

The detailed descriptions for the other fields can be found in Table 2.

Figure 4 is an example of a Variable screen for the input and output parameters of the ws_zipcode Web service:

Figure 4. Adding Web service input/output parameter details
Screenshot of the Variable screen, showing where you add the Web service input/output parameter details

Generate the configuration file and subscriber client code

Web services information is compiled in a two-step process. In the first step, the w4gl tool creates a configuration file to be used by the w4glc tool. In the second step, the w4glc tool creates the intermediate C language code and compiles it to generate object files in the target directory specified by the user.

Figure 5 is an example of a Subscribe screen used to generate the configuration file:

Figure 5. Configuration file generation
Screenshot of the Subscribe screen, where generate the configuration file

Figure 6 is an example of a Subscribe screen used to generate the client code:

Figure 6. Subscriber client code generation
Screenshot of the Subscribe screen, showing compile the subscriber client code

Call the Web service using an I4GL program

The zipcode_details function is deployed as a Web service called "ws_zipcode":

Listing 3. Sample I4GL code that is deployed as a Web service (soademo.4gl)
FUNCTION zipcode_details(pin)
    DEFINE recdtls RECORD
            pin CHAR(10),
            city CHAR(100),
            state CHAR(100)
        END RECORD, 

        pin CHAR(10),
        sel_stmt CHAR(512); 

    LET sel_stmt= "SELECT * FROM statedetails WHERE pin = ?";
    PREPARE st_id FROM sel_stmt;
    DECLARE cur_id CURSOR FOR st_id;
    OPEN cur_id USING pin;
    FETCH cur_id INTO recdtls.*;
    CLOSE cur_id;
    FREE cur_id;
    FREE st_id; 
    RETURN recdtls.city, recdtls.state
END FUNCTION

The client executable makes the call to invoke the Web service:

Listing 4. Sample I4GL code to consume a 4GL Web service (clssoademo.4gl)
MAIN
    define retVal int;
    let retVal = func_cons_ws_zipcode();
END MAIN

FUNCTION func_cons_ws_zipcode()
    DEFINE recdtls RECORD
                pin CHAR(10),
                city CHAR(100),
                state CHAR(100)
            END RECORD;

    call cons_ws_zipcode("97006") returning recdtls.city, recdtls.state
    DISPLAY "SUPPLIED ZIP CODE: 97006 \n"
    DISPLAY "RESPONSE FROM WEB SERVICE \n"
    DISPLAY " ------------------------- \n"
    DISPLAY " CITY:",state_rec.city
    DISPLAY "\n STATE:",state_rec.state
    return 1
END FUNCTION

Compile the sources to create an executable, and run the executable

The AXIS2/C receives the requests and invokes the Web service ws_zipcode, which then invokes the 4GL function zipcode_details and contacts the IDS server to get the corresponding city name and state name for the zip code.

Listing 5. Syntax
c4gl clsoademo.4gl cons_ws_zipcode.o -o zipcode_client -
I${AXIS2C_HOME}/include/axis2-1.5.0 -L${AXIS2C_HOME}/lib -laxis2_engine -
laxutil -laxis2_axiom

Run the executable (zipcode_client). The return values are communicated back to the client executable.

Listing 6. Syntax
./zipcode_client

SUPPLIED ZIP CODE: 97006
RESPONSE FROM WEB SERVICE 
    -------------------------
    
    CITY:Beaverton
    
    STATE:OR

Conclusion

Enabling I4GL as a service consumer allows you to leverage and reuse existing Web services and business logic coded in I4GL or other programming languages. Enabling I4GL as a service consumer opens up many possibilities of using I4GL to communicate with any programming language while still enjoying the ease of coding using I4GL.

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=439852
ArticleTitle=Consume Web services using Informix 4GL
publish-date=10292009