IToolkit.IBMi 0.0.5-beta

IToolkit for .NET

A .NET port of the Node.js itoolkit — an XMLSERVICE wrapper for IBM i (AS/400).

Compatible with:

• .NET Framework 4.8
• .NET 10+

Project Structure

├── IToolkit.sln
├── src/
│   └── IToolkit/               ← library
│       ├── Connection.cs
│       ├── ConnectionOptions.cs
│       ├── CommandCall.cs
│       ├── ProgramCall.cs
│       ├── ParameterConfig.cs
│       └── Transports/
│           ├── ITransport.cs
│           ├── TransportFactory.cs
│           ├── TransportOptions.cs
│           ├── HttpTransport.cs   ← REST/CGI transport
│           ├── SshTransport.cs    ← SSH transport
│           └── OdbcTransport.cs   ← ODBC transport
└── tests/
    └── IToolkit.Tests/         ← xUnit unit tests

Getting Started

Build

dotnet build

Run Tests

dotnet test

Transports

Note – ODBC on .NET 10+: the System.Data.Odbc NuGet package (8.0.0) is included automatically via the project file. IBM i Access Client Solutions must be installed on the machine running the application.

Usage

CL Command (SSH transport)

using IToolkit;
using IToolkit.Transports;
using System.Xml.Linq;

var conn = new Connection(new ConnectionOptions
{
    Transport = "ssh",
    TransportOptions = new TransportOptions
    {
        Host     = "myibmi",
        Username = "myuser",
        Password = "mypassword"
    }
});

conn.Add(new CommandCall(new CommandCallConfig
{
    Type    = "cl",
    Command = "RTVJOBA USRLIBL(?) SYSLIBL(?)"
}));

string xmlOutput = await conn.RunAsync();

// Parse with System.Xml.Linq
var doc = XDocument.Parse(xmlOutput);
Console.WriteLine(doc);

Service Program Function Call (REST transport)

using IToolkit;
using IToolkit.Transports;

var conn = new Connection(new ConnectionOptions
{
    Transport = "rest",
    TransportOptions = new TransportOptions
    {
        Url      = "http://myibmi:80/cgi-bin/xmlcgi.pgm",
        Username = "myuser",
        Password = "mypassword"
    }
});

// Call cos() from QSYS/QC2UTIL2
var program = new ProgramCall("QC2UTIL2", new ProgramCallOptions
{
    Lib  = "QSYS",
    Func = "cos"
});

program.AddParam(new ParameterConfig  { Type = "8f", Value = "0", By = "val" });
program.AddReturn(new ParameterConfig { Type = "8f", Value = "" });

conn.Add(program);
conn.Debug(true);   // print XML to stdout

string xmlOutput = await conn.RunAsync();

var doc = System.Xml.Linq.XDocument.Parse(xmlOutput);
var returnValue = doc.Descendants("data").Last().Value;
Console.WriteLine($"cos(0) = {returnValue}");  // 1

Service Program Function Call (SSH transport)

This example calls a custom service program MYLIB/MATHSRV that exposes an ADD function accepting two 4-byte integers and returning their sum.

using IToolkit;
using IToolkit.Transports;
using System.Xml.Linq;

var conn = new Connection(new ConnectionOptions
{
    Transport = "ssh",
    TransportOptions = new TransportOptions
    {
        Host     = "myibmi",
        Username = "myuser",
        Password = "mypassword"
    }
});

// Call ADD(*int 4, *int 4) returns *int 4  from MYLIB/MATHSRV
var program = new ProgramCall("MATHSRV", new ProgramCallOptions
{
    Lib  = "MYLIB",
    Func = "ADD"
});

// Input parameters (passed by reference by default)
program.AddParam(new ParameterConfig { Type = "4i0", Value = "10" });
program.AddParam(new ParameterConfig { Type = "4i0", Value = "32" });

// Return value
program.AddReturn(new ParameterConfig { Type = "4i0", Value = "" });

conn.Add(program);

string xmlOutput = await conn.RunAsync();

// Parse the result — the return value is the last <data> element
var doc = XDocument.Parse(xmlOutput);
string result = doc.Descendants("data").Last().Value;
Console.WriteLine($"ADD(10, 32) = {result}");  // 42

Common XMLSERVICE data types:

ODBC Transport

var conn = new Connection(new ConnectionOptions
{
    Transport = "odbc",
    TransportOptions = new TransportOptions
    {
        Host     = "myibmi",
        Username = "myuser",
        Password = "mypassword",
        XsLib    = "QXMLSERV"      // default
    }
});

Or with a DSN:

TransportOptions = new TransportOptions { Dsn = "MY_DSN" }

Custom / Testable Transport

public class MyTransport : IToolkit.Transports.ITransport
{
    public Task<string> CallAsync(TransportOptions opts, string xml)
    {
        // your implementation
        return Task.FromResult("<myscript/>");
    }
}

var conn = new Connection(new MyTransport(), new TransportOptions());

API Reference

Connection

CommandCall

new CommandCall(CommandCallConfig)

CommandCallConfig:

ProgramCall

new ProgramCall(string program, ProgramCallOptions?)

ParameterConfig

License

MIT — see LICENSE.

Inspired by the Node.js itoolkit project by IBM.