Getting Started

The Software AG PI Adapter for EntireX consists of the PI Adapter for EntireX itself and EntireX components. See Installing Software AG PI Adapter for EntireX for details.

The PI Adapter for EntireX is fully integrated into the SAP Exchange Infrastructure via the PI Adapter Framework. The server components have to be installed on the legacy platform to ensure efficient communication with mainframe applications.

This document provides information on getting started with the Software AG PI Adapter for EntireX. It covers the following topics:


Installing the Components of the PI Adapter for EntireX

The following components must be installed on your system:

graphics/xi_components.png

Using the Components of the PI Adapter for EntireX

Before running a PI scenario, the respective Communication Channel needs to be set up with several parameters. See Configuring on SAP PI for details on configuring the sender and receiver adapter. XMM files are used to define mapping between PI message format and RPC-based data-format. These are specific to the message type. The XMM file location also has to be specified in the Communication Channel.

The XMM file is generated fully automatically by the EntireX Workbench. Refer to the EntireX Documentation for details.

Creating a Mainframe Integration Scenario

The following sections outline two typical integration scenarios. The first scenario illustrates a receiver PI Adapter with a receiving mainframe application. The second scenario shows the opposite case with respect to the direction of communication: A message is invoked by a mainframe application using a sender PI Adapter.

Integration Scenario I: Mainframe as Receiver

After having installed the components of the PI Adapter for EntireX, you can begin creating legacy integration scenarios. This section will serve as a preliminary guide to your enterprise-class integration with SAP PI systems:

Start of instruction setTo configure scenario I

  1. Generate the definition file (IDL).

  2. Wrap schema definition (XSD) with SAP PI external definition.

  3. Create a communication channel using configuration definition (XMM).

  4. Incorporate both objects (XSD and XMM) into your SAP PI integration scenario.

  5. Start the server components on the mainframe.

  6. Start and test your legacy integration scenario.

graphics/xi_components2.png

The major steps will be described in greater detail in the following section.

The RPC messages are defined with an Interface Description Language (IDL). You can automatically generate the IDL files used for your integration scenarios from the application's source. The IDL can be reused for editing and regeneration if desired. Every SAP PI Message needs a message type definition. Likewise, to be able to effectively talk to the server component, the PI Adapters need to be configured with message type information (XMM). Both types of definitions can be generated from the legacy application's interface definitions (IDL).

For the PI, the message is described with an XML Schema Definition (XSD). This XSD has to be wrapped by an SAP PI External Definition object. Once wrapped in an External Definition, the message type is known to SAP PI.

As previously stated, the PI Adapters also need message-type information. To be able to map the XML message payload to the RPC-based format effectively, XMM files are used. These XMM files are referred to in the Communication Channels.

Start of instruction setGenerate the necessary files for scenario I

  • The EntireX Workbench is used to generate the files. After some basic settings have been made and the desired sources have been selected, three types of files are generated:

    1. IDL - for the RPC message definition

    2. XMM - an XML mapping file needed for the adapter

    3. XSD - XML Schema Definition of the message type

    The SAP PI External Definition will subsequently be used by the Message Interface objects of your integration scenario. The configured Communication Channel and the Definition allow you to define your scenario in detail.

    The server on the mainframe needs to be started to forward incoming requests to your application server program. In this manner, the server program can be offered as a service.

Integration Scenario II: Mainframe as Sender

For the mainframe-as-sender scenario, the connection from a client running on the mainframe, to the SAP PI is provided.

After having built your client application and installed the server components, you can begin creating Legacy Integration scenarios. This section will serve as a preliminary guide to configuring a client program that integrates with SAP PI:

Start of instruction setTo configure scenario II

  1. Generate message type definition files (IDL).

  2. Create a Communication Channel using configuration definition (XMM).

  3. Incorporate both objects (XSD and XMM) into your SAP PI integration scenario.

  4. Generate and install the client.

  5. Start the server components on the mainframe.

  6. Start and test your legacy integration scenario.

Most of the steps needed are identical to those in the first scenario. Therefore, only the differences will be covered in detail in the following sections.

As in the first scenario, RPC messages are defined with an Interface Description Language (IDL). Here, the message type will be taken from PI message type descriptions. This means that a different source will be used to generate the IDL. You can generate IDL from XML Schema Definitions (XSD) or, depending on your requirements, you can use a variety of sources such as DTDs, Web Service Descriptions (WSDL) or a sample XML document.

It is common when working with PI to describe best effort PI message interfaces with two XSD files: one for the message and one for the message response. Subsequently, the best way to generate IDL is by using these two XML schema definitions as input.

As described in the first scenario, users generate IDL and the XMM file. The XML mapping file will again be used in the Communication Channel settings. Since PI already knows the message interface through the XSD files, your SAP PI integration scenario can be fully described.

For a client interface, you now have to generate the related client adapter together with the related services. The generated files are transferred to the mainframe using ftp, for instance. The new members should now be compiled and linked.

Add the related RPC service to the attribute file of the EntireX Broker before starting the server components on the mainframe.

Users can write their own client program or adapt an existing one. The client programs written in mainframe languages can actually be docked. Once the client program has been written and compiled, it is ready to run, and the new integration scenario can be tested.