Invoke MiSys Equation API From .NET

Introduction

This article explains how to invoke MiSys Equation API (or any AS/400 program in general) through IBM i Access
for Windows component. The code is about calling an RPG compiled program (or
any OS/400 command) on IBM AS/400 iSeries server from .NET application

Background

MiSys Equation is the core banking system at one of my client, hosted on an iSeries server. we
need to expose Equation API/commands as .NET Services for any application to consume them regardless of the platform.
BizTalk and WCF is the platform for our middleware SOA implementation. IBM iSeries Access to Windows is a library from IBM to connect to iSeries application over TCP protocol.
This walk through describes how to expose MiSys Equation functionality as .NET library. we need to build a WCF or BizTalk service on top of this library method to expose it as web service.

Code Walk through

1. Install IBM iSeries Access to Windows. Also check for service packs
at this URL

http://www-03.ibm.com/systems/i/software/access/windows/casp.html

2. Create a new Console Application project in Visual Studio

3. Add Project Reference to cwbx.dll ActiveX from C:\Program Files
(x86)\IBM\Client Access\Shared

4. Add the attached API.cs file to your project

5. Now, we are going to connect to iSeries. we need to provide iSeries Server IP/Name, User Name and Password to connect.

//code snippet from attached API.cs

AS400System as400 = new AS400SystemClass()

Program program = new Program(); // iSeries Program (PGM)  

as400.Define("10.10.10.10"); //Server Name/IP
program.system  = as400;
program.system.UserID =User;
program.system.Password = Password;

as400.Connect(cwbcoServiceEnum.cwbcoServiceRemoteCmd);
//Connect to execute Remote commands only

6. Once we are connected to iSeries, we need to initialize
liability(context) with Equation application. This context specifies to which Equation application instance we are going to connect, as there could be multiple application instances running on the server.
Parameters.Append() is used to defined the parameters and their length. All the parameters will be passed as a Byte array and the response will be a Byte array as well.

program.LibraryName = "KAPBASELIB";
program.ProgramName = "KAPUNLIBL"; 

StringConverter stringConverter = new StringConverterClass();
ProgramParameters parameters = new ProgramParametersClass();

parameters.Append("Env", cwbrcParameterTypeEnum.cwbrcInput, 3);
parameters.Append("A1", cwbrcParameterTypeEnum.cwbrcInput,4); 

parameters["Env"].Value = stringConverter.ToBytes("DEV");//Equation Instance
parameters["A1"].Value = stringConverter.ToBytes("*DFT");//default value 

program.Call(parameters);

7. Next step is to define and assign values to In and Out parameters and call Equation
API. you need to consult MiSys Equation Journal File Documentation to check for parameters length and whether they are Input or Output parameters

program.ProgramName = "H46HMR";//Inquiry API Wrapper
ProgramParameters parameters = new ProgramParametersClass();

SetInParameter(ref parameters, "EPGM",10, "H68EER");//Bal Inq Function identifier
SetInOutParameter(ref parameters, "DSAIF",3000, "00001xxxxx"); //Account No. 

program.Call(parameters);

8. Final step is to parse the response received from Equation. As you can see in the above code, DSAIF is input/output parameter and will have the response from Equation in the form of Byte array. we need to parse the byte array through StringConverter helper method

_response.Bytes = parameters[2].Value;

StringConverter stringConverter = new StringConverterClass();
stringConverter.Length = 0; // Use all bytes in source byte array to build string
string str = stringConverter.FromBytes(_response.Fields["HZCUN"].Value);

Points of Interest

couple of points worth noting

1. Input and Output parameters are Byte array. i.e. you need to take
care of order of parameters when using parameters.append()

2. use StringConverter, PackedConverter helper methods to convert
from Byte array to string

see the attached zip file for a sample implementation for Account
Balance Inquiry API.

Thanks to Joe Rattz for this article, which was starting point for me.