Working with Call Operation in AS400

The call operation can be used to access a program in the AS400 server.

Configuring ESB

The input parameters stated in the PCML file needs to be filled out prior to calling a program. The connector uses the SOAP body in the mediation flow to fill out the input parameters of the PCML file. To achieve this we can use a PayloadFactory mediator. See the following structure for setting the input parameters from within the ESB configuration:

<payloadFactory>
  <format>
    <pcml:pcmlInputs xmlns:pcml="pcml">
      <pcml:pcmlInput 
			qualifiedName=""	<!-- The fully qualified name for the input parameter (Required attribute) -->
				indices="">		<!-- The indices value for the input parameter to support arrays (Optional attribute) -->
        	myInputValue		<!-- The value for the input parameter -->
      </pcml:pcmlInput>
	  <!-- Examples -->
      <pcml:pcmlInput qualifiedName="MyProgram.MyInput1">myInputValue1</pcml:pcmlInput>
      <pcml:pcmlInput qualifiedName="MyProgram.MyInput2">myInputValue2</pcml:pcmlInput>
      <pcml:pcmlInput qualifiedName="MyProgram.MyInput3" indices="1,3,6">myInputValue3</pcml:pcmlInput>
    </pcml:pcmlInputs>
  </format>
  <args/>
</payloadFactory>

Properties

qualifiedName: Required - The qualified name of an input parameter of the PCML program.
indices: The position of the input parameter when it comes to supporting arrays.
myInputValue: The value for the input parameter.

Call Operation

<pcml.call>
    <programName>MyProgram</programName>
    <pcmlFileLocation>conf:/pcml/my-pcml-file.pcml</pcmlFileLocation>
    <pcmlInputs xmlns:pcml="pcml">{//pcml:pcmlInputs}</pcmlInputs>
    <pool.returnPoolName>MyConnectionPool</pool.returnPoolName>
</pcml.call>

Properties

programName: Required - The name of the program that you need to call.
pcmlFileLocation: Required - The location of the file in the registry.
pcmlInputs: Required - The XML representation of the input parameters for the program.
pool.returnPoolName: The name of the pool to which the AS400 connection should be returned to once the program call is finished.

The pool.returnPoolName parameter returns the AS400 connection back into the connection pool. This is demonstrated in Sample 2 below.

Alternatively, the returnPool operation can be used to return the connection back into the pool.

Once the program call is successful, the connector converts the output PCML to XPCML format and sets it as the SOAP body in the mediation flow. An XPCML is similar to a PCML file but instead of defined data, it collapses the PCML output into one XML structure. Refer here for more information on XPCML and its structure compared to PCML.

Sample configurations

Sample 1

Let's assume that there is an RPG program in an AS400 server that performs an addition when two input values are provided. Following will be the PCML source file that is required for this program:

PcmlNumberAddition.pcml

<pcml version="4.0">
  <program name="Addition" path="/QSYS.LIB/%LIBL%.LIB/ADDITION.PGM">
     <data name="inputValue1" type="int" length="4" usage="input" />
     <data name="inputValue2" type="int" length="4" usage="input" />
     <data name="outputValue" type="int" length="4" usage="output" />
  </program>
</pcml>

This PCML file needs to be stored as /_system/config/pcml/PcmlNumberAddition.pcml resource in the ESB registry.

Following is a sample request sent to the ESB for adding two given numbers:

<p:add xlmns:p="http://services.samples">
  <p:request>
    <p:value1>5</p:value1>
    <p:value2>10</p:value2>
  </p:request>
</p:add>

Following is a sample proxy service that is used to connect to AS400 with the init operation and uses the call operation:

<proxy name="additionService" startOnLoad="true" trace="disable" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <inSequence>
            <pcml.init>
                <systemName>AS400_SystemName</systemName>
                <userID>MyUserID</userID>
                <password>MyPassword</password>
            </pcml.init>
            <payloadFactory media-type="xml">
                <format>
                    <pcml:pcmlInputs xmlns:pcml="pcml">
                        <pcml:pcmlInput qualifiedName="Addition.inputValue1">$1</pcml:pcmlInput>
                        <pcml:pcmlInput qualifiedName="Addition.inputValue2">$2</pcml:pcmlInput>
                    </pcml:pcmlInputs>
                </format>
				<args>
					<args xmlns:m0="http://services.samples" expression="//m0:value1"/>
					<args xmlns:m0="http://services.samples" expression="//m0:value2"/>
				</args>
            </payloadFactory>
            <pcml.call>
                <programName>Addition</programName>
                <pcmlFileLocation>conf:/pcml/PcmlNumberAddition.pcml</pcmlFileLocation>
                <pcmlInputs xmlns:pcml="pcml">{//pcml:pcmlInputs}</pcmlInputs>
            </pcml.call>
            <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </target>
</proxy>

Once the call is successful, the PCML output will be converted to an XPCML with the following response :

<<?xml version="1.0" ?>
<xpcml version="6.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation='xpcml.xsd' >
	<program name="Addition" path="/QSYS.LIB/%LIBL%.LIB/ADDITION.PGM">
		<parameterList>
			<intParm name="inputValue1" passDirection="in">5</intParm>
			<intParm name="inputValue2" passDirection="in">10</intParm>
			<intParm name="outputValue" passDirection="out">15<intParm>
		</parameterList>
	</program>
</xpcml>

Sample 2

Following is a sample proxy service that is used to connect to AS400 with the init operation and uses the call operation to return the AS400 connection back into the connection pool:

<proxy name="additionService" startOnLoad="true" trace="disable" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <inSequence>
            <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>
            </pcml.init>
            <payloadFactory media-type="xml">
                <format>
                    <pcml:pcmlInputs xmlns:pcml="pcml">
                        <pcml:pcmlInput qualifiedName="Addition.inputValue1">$1</pcml:pcmlInput>
                        <pcml:pcmlInput qualifiedName="Addition.inputValue2">$2</pcml:pcmlInput>
                    </pcml:pcmlInputs>
                </format>
				<args>
					<args xmlns:m0="http://services.samples" expression="//m0:value1"/>
					<args xmlns:m0="http://services.samples" expression="//m0:value2"/>
				</args>
            </payloadFactory>
            <pcml.call>
                <programName>Addition</programName>
                <pcmlFileLocation>conf:/pcml/PcmlNumberAddition.pcml</pcmlFileLocation>
                <pcmlInputs xmlns:pcml="pcml">{//pcml:pcmlInputs}</pcmlInputs>
                <pool.returnPoolName>MyConnectionPool</pool.returnPoolName>
            </pcml.call>
            <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </target>
</proxy>

Using the pool.returnPoolName parameter within the call operation will return the AS400 connection back into the connection pool.