Premium

Introduction

The purpose of Mule IBM AS/400 connector is to enable IBM i (AS/400) integrations with other components.

The IBM AS/400 was first introduced in 1988 and evolved into a very stable modern all-purpose integrated solution that requires little or no management. The system is able to run core line of business applications securely and predictably, focusing on quality of service and availability and offering a compelling total cost of ownership for integrated on-premises solutions. IBM made several changes to the server and OS name (iSeries, System i, IBM i, Power Systems for i) but most still refer to it as AS/400.

The majority of IBM i integration use cases can be grouped into exposing back-end business logic as REST APIs, and consuming external APIs directly from IBM i programs. The IBM i AS/400 connector makes it easy to call IBM i programs, pass parameters, and get the response back directly from Mulesoft flows with no work or products required on the back-end. Infoview Systems also built the AS/400 ‘Web Transaction Framework’ that makes it very fast and easy to implement "outbound" integrations, where IBM i programs must call external APIs in real time.

Prerequisites

The connector is designed to work with AS/400 objects (programs, service programs, data queues and commands) and therefore this document assumes you are familiar with AS/400 operational and development environments and tools.

This document assumes you are familiar with Mule, Anypoint Connectors, and Anypoint Studio Essentials. To increase your familiarity with Studio, consider completing one or more Anypoint Studio Tutorials. Further, this page assumes that you have a basic understanding of Elements in a Mule Flow and Mule Global Elements.

Dependencies

  • Access to AS/400 server

  • Mule Enterprise runtime or Anypoint Studio

Compatibility Matrix

Application/Service Version

Mule Runtime

3.6.0 or higher

IBM i / OS400

V5R4 or higher

Installing and Configuring

Installation instructions

  1. In Anypoint Studio, navigate to Help → Install New Software

    installation1

  2. In a "Work with" pull-down menu, select Anypoint Connectors update site

    installation2

  3. Expand Certified and navigate to AS400 connector. Alternatively, type as400 in the filter field.

    installation3

  4. Select AS400 connector and press Next then proceed with installation screen flow, accept the license agreement and complete the installation.

To use the AS/400 connector in a production environment, you must have either an Enterprise license to use Mule or a CloudHub Starter, Professional, or Enterprise account. In addition, you will need to obtain a license key from Infoview to enable access to specific AS/400 system(s), and install license file into $MULE_HOME/conf folder of all runtimes or include the license file into application archive that will be deployed to CloudHub. Please contact Infoview Systems AS/400 Connector support team at (734) 293-2160 or via email mule400@infoviewsystems.com

Updating From an Older Version

Every time an updated version of a connector is released, Anypoint studio displays a popup in the bottom right corner of your system with the following message: Updates Available.

To upgrade to the newer version of the AS/400 connector:

  1. Click the popup and check for the available updates.

  2. Select the AS/400 connector version x.0.0 check box and click Next.

  3. Follow the instructions provided by the user interface.

  4. Restart Studio when prompted. After restarting, if you have several versions of the connector installed, Mule asks you for the version of the connector to use.

AS/400 server configuration and requirements

  • AS/400 must have ports 449, 8470, 8472, 8475 and 8476 (as well as 9470, 9472, 9475 and 9476 for secure connections) accessible from Mule runtime.

  • AS/400 must have *CENTRAL, *DTAQ, *RMTCMD, *SIGNON and *SRVMAP host servers running in the QSYSWRK subsystem.

Maven configuration for AS/400 Connector

For the Maven based Mule projects, the pom.xml must include the following:

Add the inclusion of connector dependencies to the build plugin:

<build>
  <plugins>
    <plugin>
      <groupId>org.mule.tools.maven</groupId>
      <artifactId>mule-app-maven-plugin</artifactId>
      <version>${mule.tools.version}</version>
      <extensions>true</extensions>
      <configuration>
                  <copyToAppsDirectory>true</copyToAppsDirectory>
      <inclusions>
                      <inclusion>
                          <groupId>org.mule.modules</groupId>
                          <artifactId>as400-connector</artifactId>
                      </inclusion>
                  </inclusions>
              </configuration>
    </plugin>
</build>

Add the connector dependency:

<dependency>
      <groupId>org.mule.modules</groupId>
      <artifactId>as400-connector</artifactId>
      <version>1.1.2</version>
</dependency>

Configuring the AS/400 Connector

To use the AS/400 connector in your Mule application, you must configure global AS/400 Connection Strategy element that can be used by all the AS/400 connectors in the application (read more about Global Elements.)

Follow these steps to configure AS/400 connector in a Mule application:

  1. Click the Global Elements tab at the base of the canvas, then click Create.

  2. In the Choose Global Type menu, use the filter to locate and select AS/400, then click OK.

  3. Configure the parameters according to the table below.

    global_config
    Parameter Description Default Value

    Name

    Enter a name for the configuration so it can be referenced later by the config-ref parameter in the flow.

    URL

    Enter the AS/400 endpoint

    UserID

    Enter the username that can connect to AS/400.

    Password

    Enter the password for the above AS/400.

    IASP

    Provide IASP name

    LibraryList

    Enter a comma separated list of libraries (if any) that needs to be added to the library list for Command call execution

    SecureConnection

    Check this box for communicating with IBMi over TLS

    false

    Socket Timeout

    Max socket timeout value (in milliseconds) for the AS400 connection

    60000

    Connection Retries

    Number of connection retries internally within AS400 connector configuration before the exception is raised to Mulesoft runtime and connection management

    3

    Connection TTL

    Connection Active Time (Time to Live), 0 - no limit.

    0

  4. Keep the Pooling Profile and Reconnection tabs with their default values.

  5. Click OK to save the global connector configurations.

  6. Return to the Message Flow tab in Studio.

Connector Operations

The AS/400 connector is an operation-based connector, which means that when you add the connector to your flow, you need to configure a specific operation the connector is intended to perform. The connector supports the following operations:

Operation Description

Program Call (Processor)

Direct IBM i program call or Service Program Procedure call from Mulesoft flow

Read Data Queue (Message Source)

Perpetually listen for new messages arriving to specific data queue

Read Data Queue (Processor)

Read messages from specific data queue as part of Mule flow

Write to Data Queue

Write messages to data queue

Command Call

Execute AS/400 command call

Executing direct program call

Please refer to http://www.infoviewsystems.com/2017/10/11/how-to-build-an-ibm-i-as400-api-in-15-minutes/ for detailed description and sample source code of the program call.

In order to call Service Program Procedure, just specify the Service Program library, name and exported procedure name in the program call parameters.

Configuring the AS/400 Data Queue Listener (Message Source)

  1. Drag the AS/400 connector onto the Message Source area of the flow and select it to open the Properties Editor console.

  2. Configure the connector parameters:

    Field Description Default

    Display Name

    Enter a unique label for the connector in your application.

    AS/400 (Streaming)

    Connector Configuration

    Select the global AS/400 connector element that you just created.

     — 

    Operation

    Select Data Queue Listener

     — 

    Data Queue

    Enter Data Queue name

     — 

    Library

    Enter Data Queue library name

     — 

    Key

    Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter ' '

     — 

    Key Search Type

    Must be specified for keyed data queues. For reading any message from data queue, enter Greater or Equal

     — 

    Keep messages in Queue

    Ensure it is unchecked

    false

    Format File Name

    Optional parameter allows treating data queue entry as an externally defined data structure. When defined, the connector will dynamically retrieve the record format from the the specified IBMi file, and parse the received data queue entry into the map of field name / value pairs. The connector will perform the type conversion, supporting all types such as packed, date / time etc

     — 

    Format File Library

    When format file is specified, the format file library can also be specigied, otherwise the format file will be located based on the connection library list.

    *LIBL

    Polling period

    Time between message reads, ms. Can be used as crude throttling configuration

    1

If message is received from the data queue, message text will be placed into payload and message key (if any) will be saved into #[message.inboundProperties['as400.dataqueue.key']]

The output payload format depends on whether the external data format. When the format file has been specified, the output is a Map, where keys are format field names, and the values represent the data for each field. When no format file has been specified, the data queue entry will be returned as a String.

Configuring the AS/400 Data Queue Reader (Message Processor)

  1. Drag the AS/400 connector onto the Message Flow area (other than message source) and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    read_config
    Field Description Default

    Display Name

    Enter a unique label for the connector in your application.

    AS/400

    Connector Configuration

    Select the global AS/400 connector element that you just created.

     — 

    Operation

    Select Read Data Queue

     — 

    Data Queue

    Enter Data Queue name

     — 

    Library

    Enter Data Queue library name

     — 

    Key

    Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter ' '

     — 

    Key Search Type

    Must be specified for keyed data queues. For reading any message from data queue, enter Greater or Equal

     — 

    Keep messages in Queue

    Ensure it is unchecked unless the intent is to leave the message in the queue after reading

    false

    Format File Name

    Optional parameter allows treating data queue entry as an externally defined data structure. When defined, the connector will dynamically retrieve the record format from the the specified IBMi file, and parse the received data queue entry into the map of field name / value pairs. The connector will perform the type conversion, supporting all types such as packed, date / time etc

     — 

    Format File Library

    When format file is specified, the format file library can also be specigied, otherwise the format file will be located based on the connection library list.

    *LIBL

If message is received from the data queue, message text will be placed into payload and message key (if any) will be saved into #[message.outboundProperties['as400.dataqueue.key']]

Configuring the AS/400 Data Queue Writer

  1. Drag the AS/400 connector onto the Message Flow area (other than message source) and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    write_config
    Field Description Default

    Display Name

    Enter a unique label for the connector in your application.

    AS/400

    Connector Configuration

    Select the global AS/400 connector element that you just created.

     — 

    Operation

    Select Write Data Queue

     — 

    Data Queue

    Enter Data Queue name

     — 

    Library

    Enter Data Queue library name

     — 

    Data Entry

    Enter Data Queue Message Text

     — 

    Key

    Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter ' '

     — 

    Format File Name

    Optional parameter allows treating data queue entry as an externally defined data structure. When defined, the connector expects the JSON string to be passed as Data Queue Entry. The connector will dynamically retrieve the record format from the the specified IBMi file, parse the JSON string passed into the processor, into a binary byte array that can be interpreted on IBM i side as a data structure. The JSON string must have a list of elements with element name matching the format file column name, and associated value. The connector will perform the type conversion, supporting all types such as packed, date / time etc

     — 

    Format File Library

    When format file is specified, the format file library can also be specigied, otherwise the format file will be located based on the connection library list.

    *LIBL

    DQ Entry Length

    Max DQ Entry Length. When specified and greater than 0, the parameter value will be truncated to fit the max length

    0

    DQ Key Length

    Max DQ Key Length. When specified and greater than 0, the parameter value will be used (instead of dynamically retrieving it from DQ definitions on the server)

    0

Configuring the AS/400 Command Call

  1. Drag the AS/400 connector onto the Message Flow area (other than message source) and select it to open the Properties Editor console.

  2. Configure these connector parameters:

    command_call_config
    Field Description Default

    Display Name

    Enter a unique label for the connector in your application.

    AS/400

    Connector Configuration

    Select the global AS/400 connector element that you just created.

     — 

    Operation

    Select Command Call

     — 

    Command

    Enter AS/400 command

     — 

Use Cases

The following two common use cases address the majority of AS/400 integration requirements:

  • AS/400 process calls external function

  • External function calls AS/400 process

For more details and code samples refer to connector demos.

AS/400 process calls external function

This use case is implemented using a pair of keyed data queues.

  1. AS/400 program places request data and unique transaction key into request data queue then waits for response from Mule (or other external process) with the same key

  2. Mule receives the request from data queue, processes a request, then places reply with the same key into response data queue

External function calls AS/400 process

This is the reverse of the previous use case - Mule places requests to data queue and AS400 listener program processes the requests and places the output to response data queue.

See Also