Connecting BEA AquaLogic Service Bus with i5/OS and OS/400 Applications
Pages: 1, 2

XPCML

XPCML is the Extensible Program Call Markup Language, an XML language defined by IBM. XPCML documents contain the necessary information to call an i5/OS program, pass parameters, and receive results. Here is a fragment of an XPCML document to call the "Retrieve user Information" program (QSYRUSRI):

<program name="program" path="/QSYS.lib/QSYRUSRI.pgm">

 <parameterList>

  <structParm name="receiver" passDirection="out" struct="usri0100"/>

  <intParm name="receiverLength" type="int" length="4" usage="input"

   init="128"/>

  <stringParm name="format" passDirection="in" length="8">

   USRI0100

  </stringParm>

  <stringParm name="profileName" passDirection="in" length="10">

   *CURRENT

  </stringParm>

  <intParm name="errorCode" passDirection="in">0</intParm>

 </parameterList>

</program>

The document includes the program name and the list of parameters. Parameters can be of simple types or complex structures defined in the same document.

IBM provides a mechanism to invoke i5/OS programs using XPCML through the Toolbox for Java. ALSB and the ifiveos transport leverage this technique to perform direct calls to i5/OS programs. The declarative nature of XPCML integrates beautifully with ALSB and how messages are handled with XQuery.

Within the proxy service, an XPCML message needs to be created and populated with the input parameters to the i5/OS program. The name of the program is specified in the path attribute of the program element. It is important to set the name attribute of the program element to the value program, as shown below:

<program name="program" path="/QSYS.lib/QSYRUSRI.pgm">

Once the response is returned from the business service as an XPCML document, the proxy service can extract the relevant information using XQuery. The Proxy will transform the XPCML document to the format defined in the Proxy interface, as represented in Figure 3.

XPCML document exchanges between the proxy and business service
Figure 3. XPCML document exchanges between the proxy and the business service

An Example

Let's select an i5/OS system program, "List Job Information" QWCRSSTS, to illustrate how to make a program call directly from ALSB. To keep it simple, we are going to create a proxy service that doesn't take any parameters, calls the i5/OS Business Service, extracts the system name, and returns it to the caller.

We are going to assume that the ifiveos transport is already installed and configured and that a business service is already configured to connect to the i5/OS server. Please refer to the CodeShare link at the end of the article for detailed instructions. In the instructions you will see that one of the parameters of the i5/OS business service is the hostname or IP address of the i5/OS host, as shown in Figure 4:

A simple transport configuration for the business service
Figure 4. A simple transport configuration for the business service

The proxy service's message flow contains just a route node to the i5/OS business service, as shown in Figure 5.

Proxy Service's message flow

Figure 5. The proxy service's message flow

The route node is simply a call to the i5/OS business service, as shown in Figure 6.

Route to i5/OS Business Service
Figure 6. The route to the i5/OS business service

Prior to route the call to the business service, we change the body variable to include the XPCML message containing the i5/OS program call description. The new body passed to the business service is listed below:

<soap-env:Body>

<xpcml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

       xsi:noNamespaceSchemaLocation="xpcml.xsd" version="4.0">

  <struct name="SSTS0100">

    <intParm name="bytesAvailable" passDirection="out"/>

    <intParm name="bytesReturned" passDirection="out"/>

    <stringParm name="currentDateTime" passDirection="out" length="8"/>

    <stringParm name="systemName" passDirection="out" length="8"/>

    <intParm name="usersCurrentlySignedOn" passDirection="out"/>

    <intParm name="usersTempSignedOff" passDirection="out"/>

    <intParm name="usersSuspendedBySystem" passDirection="out"/>

    <intParm name="usersSuspendedByGroupJobs" passDirection="out"/>

    <intParm name="usersSignedOffWithPrtOutWait" passDirection="out"/>

    <intParm name="batchJobsWaitingForMessages" passDirection="out"/>

    <intParm name="batchJobsRunning" passDirection="out"/>

    <intParm name="batchJobsHeldWhileRunning" passDirection="out"/>

    <intParm name="batchJobsEnding" passDirection="out"/>

    <intParm name="batchJobsWaitingToRun" passDirection="out"/>

    <intParm name="batchJobsHeldOnQueue" passDirection="out"/>

    <intParm name="batchJobsOnHeldQueue" passDirection="out"/>

    <intParm name="batchJobsOnUnassignedQueue" passDirection="out"/>

    <intParm name="batchJobsEndedWithPrtOutWait" passDirection="out"/> 

  </struct>

 

<program name="
                        
program" path="/QSYS.lib/QWCRSSTS.pgm">

<parameterList>

    <structParm name="receiver" passDirection="out" struct="SSTS0100"/>

    <intParm name="receiverLength" passDirection="in">80</intParm>

    <stringParm name="format" passDirection="in" length="8">SSTS0100</stringParm>

    <stringParm name="statusStat" passDirection="in" length="10">*NO     </stringParm>

    <intParm name="errorCode" passDirection="in">0</intParm>

  </parameterList>

</program>

 

</xpcml>

</soap-env:Body>

                      

Note again that the name attribute of the program element needs to be set to program.

In the response action we just need to extract the system name returned from the XPCML, which, in turn, was returned from the business service. Using XQuery, we will transform the XPCML into the XML to be returned by the proxy service and assign it to the body variable. Here is the XQuery used:

 

<soap-env:Body>

 <ifiv:getSystemNameResponse xmlns:ifiv="http://ifiveos">

<ifiv:return>

 {$body/xpcml/program/parameterList/structParm/stringParm[@name="systemName"]/text()}

</ifiv:return>

 </ifiv:getSystemNameResponse>

</soap-env:Body>

Now we can test the proxy with the console. Figure 7 shows the result.

Response Document after the XQuery is executed
Figure 7. Response document after the XQuery is executed

Under the Hood

This section in the article is just for those interested in knowing how the direct integration between ALSB and i5/OS is implemented.

The integration is made possible by the ifiveos transport, which supports outbound synchronous calls from ALSB to i5/OS programs, written in RPG, COBOL, and other languages. Figure 8 summarizes the components in the architecture.

Components in the new architecture
Figure 8. Components in the new architecture

The highlighted components are:

  • The proxy service is the public interface of the service provided by ALSB to the clients.
  • The business service is the definition of the enterprise system—in our case, the i5/OS server where the programs reside. The definition includes the physical address of the server, the account used to log in, and some other parameters.
  • The ifiveos transport is an extension of ALSB built using the ALSB Transport SDK. It provides connection management between ALSB and i5/OS.
  • Toolbox for Java is an IBM library to access i5/OS resources using Java. It provides an XML language (XPCML) and a programming interface to call programs on remote systems.
  • Host servers are part of the basic components of i5/OS, providing remote access to the system from clients. Host servers use TCP/IP protocols.
  • i5/OS programs and commands, written in RPG, COBOL, or C, can be described and called using XPCML through the stack presented here.

Here are the color codes used in the diagram:

  • Green - programs
  • Blue - configuration artifacts
  • Red - infrastructure components
  • Gray - platforms

In addition to the benefits described in previous sections, this architecture shows how two well designed products can be integrated using standards like XML. In particular, this integration has been possible thanks to the following features:

  • ALSB provides several convenient abstractions (for example, transport, binding), includes the Transport SDK, and is XML/XQuery-centric. It is designed for interoperability.
  • i5/OS provides XPCML and a Java API to invoke programs remotely using XPCLM documents.

The integration is native and non-intrusive because it leverages the interfaces that are already present in each platform.

Finally, the ifiveos transport is an example of how to extent ALSB to support interoperability with systems and protocols other than the eight that come with the product. Other transports are also available on Dev2Dev's CodeShare.

Conclusion

AquaLogic Service Bus can connect directly to i5/OS and call RPG and COBOL programs through the ifiveos transport. With this approach there is no need for intermediary application servers to expose i5/OS programs as Web services. ALSB connects directly to i5/OS and exposes those programs as services to clients in any transport and binding supported by ALSB (for example, Web services, JMS, XML/HTTP), with the added value of an Enterprise Service Bus.

The architecture described here does not require any coding, is configuration driven, and is based on XML (XPCML) and XQuery.

References

  • BEA AquaLogic Service Bus product center on Dev2Dev
  • The ifiveos ALSB Transport for i5/OS and OS/400 code sample can be downloaded from CodeShare
  • The IBM Toolbox for Java is necessary for this solution
  • JTOpen is an open-source version of the IBM Toolbox for Java

Paco Gómez is senior principal systems engineer at BEA Systems where he has been helping customers architecting solutions since 1999.