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 IBM i platform offers a number of integration options including PHP, Java, WebSphere, specialized lightweight web service containers, FTP, SMTP / emails, DB2 interfaces, data queues, integrated file systems - IFS, as well as number of products offered by IBM and Third party vendors. The main benefit of using "native" options such as Program Calls and Data Queues is that IBM i development team does not have to learn another language or purchase and support another technology in order to build integration layer, and can easily communicate with external systems using only traditional development tools.
Program Call is the most straightforward and low code option for exposing IBM i business logic as a reusable asset. The IBM i connector enables direct program calls from Mule application, passing parameters into the program and receiving the results back in real time.
Data queues are native IBM i objects designed primarily for inter-process communications. They are lightweight persistent queues that support processing by a key, FIFO or LIFO. The majority of integration use cases can be implemented with the pair of request and response Data Queues. Source system places a message to request data queue and waits for acknowledgement message on response data queue. The target system receives and processes a message from the request data queue then places the acknowledgement to the response data queue.
The IBM i connector makes it easy to build Mule code that talks to IBM i applications. Infoview Systems also built the IBM i ‘Web Transaction Framework’ that makes it very fast and easy to develop IBM i code that communicates with Mule.
Prerequisites
The connector is designed to work with IBM i objects (programs, service programs, data queues and commands) and therefore this document assumes you are familiar with IBM i operational and development environments and tools.
This document assumes you are familiar with Mule, Anypoint Connectors, and Anypoint Studio.
This document describes implementation examples within the context of Anypoint Studio, Mule ESB’s graphical user interface, and, in parallel, includes configuration details for doing the same in the XML Editor.
Dependencies
-
Access to IBM i server
-
Mule Enterprise runtime or Anypoint Studio
Compatibility Matrix
Application/Service | Version |
---|---|
Mule Runtime |
4.1 or higher |
Anypoint Studio |
7.1 or higher |
IBM i / OS400 |
V5R4 or higher |
Installing and Configuring
Installation instructions
To install the connector open the pom.xml
file in the project
root folder, and add the following dependencies and repositories:
<dependency>
<groupId>com.infoview.mule</groupId>
<artifactId>as400-connector</artifactId>
<version>2.1.0</version>
<classifier>mule-plugin</classifier>
</dependency>
<dependency>
<groupId>com.license4j</groupId>
<artifactId>license4j-runtime-library</artifactId>
<version>RELEASE</version>
</dependency>
<repository>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</releases>
<id>license4j-runtime-library</id>
<name>License4J Runtime Library Maven Repository</name>
<url>http://www.license4j.com/maven/</url>
<layout>default</layout>
</repository>
After that you should be able to find AS400 connector in the Mule Pallete window.
The IBM i connector requires a license key from Infoview to enable access to specific IBM i system(s). The connector license must be installed into $MULE_HOME/conf folder for on-prem runtimes, or included into application archive that will be deployed to CloudHub. Please contact Infoview Systems IBM i Connector support team at (734) 293-2160 or via email mule400@infoviewsystems.com
In addition to Infoview license, the connector can only run on Mulesoft Enterprise runtimes.
IBM i server configuration and requirements
-
IBM i must have ports 449, 8470, 8472, 8475 and 8476 accessible from Mule runtime.
-
IBM i must have *CENTRAL, *DTAQ, *RMTCMD, *SIGNON and *SRVMAP host servers running in the QSYSWRK subsystem.
-
IBM i user ID must be authorized to perform the operations on the intended IBM i objects
-
If there’s an additional security software that locks down the remote execution functionality, the IBM i user ID defined for connector configuration must be allowed to execute remote calls
Configuring the IBM i Connector
To use the IBM i connector in your Mule application, you must configure global IBM i Connection Strategy element that can be used by all the IBM i connectors in the application
Follow these steps to configure IBM i connector in a Mule application:
-
Click the Global Elements tab at the base of the canvas, then click Create.
-
In the Choose Global Type menu, use the filter to locate and select AS400 Config, then click OK.
-
Configure the parameters according to the table below.
Parameter Description Mandatory Default Value Name
Enter a name for the configuration so it can be referenced later by the
config-ref
parameter in the flow.Optional
AS400_Config
URL
Enter the IBM i endpoint
Required
—
UserID
Enter the username that can connect to IBM i.
Required
—
Password
Enter the password for the above IBM i.
Required
—
IASP
Enter the IASP name.
Optional
—
LibraryList
Enter a comma separated list of libraries (if any) that needs to be added to the library list for Command call execution
Optional
—
secureConnection
When True, the connector will try to establish secure SSL / TLS connection with IBM i endpoint.
Optional
False
-
Click OK to save the global connector configurations.
-
Return to the Message Flow tab in Studio.
Connector Operations
The IBM i 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 |
---|---|
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 IBM i command call. |
Program Call |
Execute IBM i program or Service program procedure. |
Configuring the IBM i Data Queue Listener (Message Source)
-
Drag the Read data queue component onto the Message Source area of the flow and select it to open the Properties Editor console.
-
Configure these connector parameters:
Field Description Mandatory Default Display Name
Enter a unique label for the connector in your application.
Optional
Read data queue
Connector Configuration
Select the global IBM i connector element that you just created.
Required
—
Data Queue
Enter Data Queue name.
Required
—
Library
Enter Data Queue library name.
Required
—
Key
Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter ' '.
Optional
—
Key Search Type
Must be specified for keyed data queues. For reading any message from data queue, enter Greater or Equal.
Optional
Empty
Keep messages in Queue
Ensure it is unchecked.
Required
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
Optional
—
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.
Optional
*LIBL
Polling period
Time between message reads, ms. Can be used as crude throttling configuration
Optional
1
Number of consumers
Number of Data Queue Listener threads.
Optional
4
If message is received from the data queue, message text will be placed into payload and message key (if any) will be saved into #[attributes.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 IBM i Data Queue Reader (Message Processor)
-
Drag the Read data queue processor component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.
-
Configure these connector parameters:
Field Description Mandatory Default Display Name
Enter a unique label for the connector in your application.
Required
Read data queue processor
Connector Configuration
Select the global IBM i connector element that you just created.
Required
—
Data Queue
Enter Data Queue name.
Required
—
Library
Enter Data Queue library name.
Required
—
Key
Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter
' '
.Required
—
Key Search Type
Must be specified for keyed data queues. For reading any message from data queue, enter Greater or Equal.
Required
Empty
Keep messages in Queue
Ensure it is unchecked unless the intent is to leave the message in the queue after reading.
Required
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
Optional
—
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.
Optional
*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 #[attributes.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 IBM i Data Queue Writer
-
Drag the Write data queue component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.
-
Configure these connector parameters:
Field Description Mandatory Default Display Name
Enter a unique label for the connector in your application.
Optional
Write data queue
Connector Configuration
Select the global IBM i connector element that you just created.
Required
—
Data Queue
Enter Data Queue name.
Required
—
Library
Enter Data Queue library name.
Required
—
Data Entry
Enter Data Queue Message Text.
Optional
—
Key
Must be specified for keyed data queues and blank for non-keyed data queues. For reading any message from data queue, enter
' '
.Optional
—
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
Optional
—
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.
Optional
*LIBL
Configuring the IBM i Command Call
-
Drag the Command call component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.
-
Configure these connector parameters:
Field Description Mandatory Default Display Name
Enter a unique label for the connector in your application.
Optional
Command call
Connector Configuration
Select the global IBM i connector element that you just created.
Required
—
Command
Enter IBM i command.
Optional
#[payload]
Configuring the IBM i Program Call and Service Program Procedure Call
-
Drag the Program call component onto the Message Flow area (other than message source) and select it to open the Properties Editor console.
-
Configure these connector parameters:
Field Description Mandatory Default Display name
Enter a unique label for the connector in your application.
Optional
Program call processor
Connector Configuration
Select the global IBM i connector element that you just created.
Required
—
Program or Service Program name
Enter the program or Service Program name.
Required
—
Program library
Enter the library name.
Required
—
Service Program Procedure Name
Enter the name of service program procedure.
Optional
—
Procedure Returns Value
Indicator if the service program procedure returns a value.
Optional
False
Thread safe
Indicator if the program is thread safe.
Optional
False
Parameters
List of definitions and value references of program parameters.
Optional
None
There are several limitations for Service Program procedure call, imposed by the IBM i (AS400) external Service Program call API (QZRUCLSP):
-
Max 7 parameters are allowed (each parameter can be data structure or array of data structures)
-
If the procedure returns a value, it must be an integer
-
-
In the case when it’s need to run program with arguments, the Parameters property must be set to
Expression
orEdit inline
, and list of definitions and value references of program parameters must be specified.Field Description Mandatory Default Parameter name
Enter a unique label for the program parameter
Required
—
Data type
Select the IBM i data type.
Required
Empty
Length
Parameter length, bytes
Optional
0
Decimal positions
Decimal points
Optional
0
Usage
In / Out / Inout
Required
Empty
Count
For array parameters, number of elements in the array
Optional
1
Data structure element
Nested parameter definitions for each data structure element
Optional
None
Parameter value
Enter the parameter value.
Optional
—
Use Cases
The following two common use cases address the majority of IBM i integration requirements:
-
IBM i process calls external function
-
External function calls IBM i process
For more details and code samples refer to connector demos.
IBM i process calls external function
This use case is implemented using a pair of keyed data queues.
-
IBM i 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
-
Mule receives the request from data queue, processes a request, then places reply with the same key into response data queue
External function calls IBM i 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
-
More IBM i technical articles, source code samples and how-to’s refer to Infoview Blog
-
Mulesoft Legacy Modernization webinar featuring IBM i connector