Configuring AS400 PCML Connector Operations

Prior knowledge on using PCML to call programs on the AS400 server, XPCML definitions and AS400 Connection Pools are required to follow this documentation.

To use the AS400 PCML connector, add the <pcml.init> element in your configuration before carrying out any of the AS400 PCML operations. This will create an AS400 instance in the mediation flow which can later be used for accessing programs on the AS400 server.

Secure Vault is supported for encrypting all parameters in the connector. Refer Working with Passwords on integrating and using Secure Vault.

init

<pcml.init>
	<systemName>AS400_SystemName</systemName>
	<userID>MyUserID</userID>
	<password>MyPassword</password>
</pcml.init>

Properties

systemName: The name of the AS400 system that you need to connect to.
userID: The user ID to use when connecting to the AS400 system.
password: The password to use when connecting to the AS400 system.

Add the PCML source files with the extensions listed below into the ESB registry:

File Extension(Case Ignored)	File Type
.pcml , .pcmlsrc	PCML Source File
.xpcml , .xpcmlsrc	XPCML Source File

The PCML files can later be referred by the connector using the registry path of the resource.
Serialized PCML files are not supported.

Add the PCML files as a registry resource in ESB registry using one of the following methods:

The connector uses the IBM JTOpen library for all its operations. Copy the jt400.jar to <ESB_HOME>/repository/components/lib folder. You can download the IBM JTOpen library from here.

Using an AS400 Connection Pool

The connector also supports creating AS400 connections using a connection pool and this can be declared in the init operation.

init with connection pool declaration

<pcml.init>
	<systemName>AS400_SystemName</systemName>
	<userID>MyUserID</userID>
	<password>MyPassword</password>
	<pool.poolName>MyConnectionPool</pool.poolName>
	<pool.maxConnections>50</pool.maxConnections>
	<pool.maxInactivity>30000</pool.maxInactivity>
	<pool.maxLifetime>600000</pool.maxLifetime>
	<pool.maxUseCount>-1</pool.maxUseCount>
	<pool.maxUseTime>300000</pool.maxUseTime>
	<pool.runMaintenance>true</pool.runMaintenance>
	<pool.threadUsed>true</pool.threadUsed>
	<pool.cleanupInterval>300000</pool.cleanupInterval>
    <pool.pretestConnections>true</pool.pretestConnections>
</pcml.init>

Properties

pool.poolName: The name used to uniquely identify a connection pool.
pool.maxConnections: The maximum number of connections.
pool.maxInactivity: The maximum time in milliseconds of inactivity before an available connection is closed.
pool.maxLifetime: The maximum life in milliseconds for an available connection.
pool.maxUseCount: The maximum number of times a connection can be used before it is replaced in the pool.
pool.maxUseTime: The maximum time in milliseconds a connection can be in use before it is closed and returned to the pool.
pool.runMaintenance:Indicates whether the maintenance thread is used to clean up expired connections.
pool.threadUsed: Indicates whether threads are used for communicating with the host servers and for running maintenance. The default value is true.
pool.cleanupInterval: The time interval in milliseconds for running the maintenance daemon. Default value is 300000 milliseconds.
pool.pretestConnections: Indicates whether connections are pretested before they are allocated to requesters.

Each AS400 connection pool is mapped against a given pool name and stored within the ESB memory. A new connection pool will only be created if a connection pool with the given pool name does not exist. If a connection pool with the given pool name does exist, the connector uses the existing pool. Connection pools are stored within a single ESB node and are not distributed among the cluster.
All pool related parameters will not take effect unless pool.poolName is defined.
When using the connection pools in ESB, the first request that comes into the mediation flow will create the AS400 connection pool and use it. Every subsequent request will use the created connection pool for getting connections.

After using a connection from the connection pool, it is mandatory to return the connection back to the pool. The connection can be returned to the pool by using a call operation or by using a returnPool operation.

Setting Socket Properties for the AS400 Connection

The connector allows setting socket properties for the AS400 connection. These properties can be used depending on the use case and to prevent the AS400 connection timing out.

init with socket properties

<pcml.init>
	<systemName>AS400_SystemName</systemName>
	<userID>MyUserID</userID>
	<password>MyPassword</password>
	<socket.keepAlive>false</socket.keepAlive>
	<socket.loginTimeout>10000</socket.loginTimeout>
	<socket.receiveBufferSize>87380</socket.receiveBufferSize>
	<socket.sendBufferSize>16384</socket.sendBufferSize>
	<socket.soLinger>0</socket.soLinger>
	<socket.soTimeout>15000</socket.soTimeout>
	<socket.tcpNoDelay>false</socket.tcpNoDelay>
</pcml.init>

Properties

socket.keepAlive: Value for SO_KEEPALIVE socket option.
socket.loginTimeout: The timeout value in milliseconds when creating a new socket connection.
socket.receiveBufferSize: Value in bytes for SO_RCVBUF socket option.
socket.sendBufferSize: Value in bytes for SO_SNDBUF socket option.
socket.soLinger: Value in seconds for SO_LINGER socket option.
socket.soTimeout: Value in milliseconds for SO_TIMEOUT socket option.
socket.tcpNoDelay: Value for TCP_NODELAY socket option.

All above properties are optional. When using socket properties with AS400 connection pools, the socket properties are applied to the connection pool directly.

Performing operations

Now that you have connected to the AS400 server, use the information in the following topics to perform various operations with the connector.

Debugging the Connector

Refer Setting Up Logging in ESB to enable or disable logs related to the connector.

All Java classes related to this connector resides within the org.wso2.carbon.connector.pcml package. These classes can be used to enable logs for the connector.