X3270 REST

This library might be interesting for all the people that want to replace their legacy DDE or HLLAPI code and are willing to use x3270 client software. X3270.Rest is a wrapper for the standard x3270 HTTP REST interface.

Installation

You can either download and compile the binaries or just make use of the existing NuGet package. Hit

Install-Package X3270.Rest

in the command line and you're done.

Sample Implementation

Create the API Client

The heart of X3270.Rest is an API client. x3270 offers three different choices to access the REST interface:

• Text - Offers basic access to the terminal mask.
• Status Text - Offers the same as Text with an additional output of the status line.
• JSON - Not implemented yet. Because Text is the same as Status Text with less information and JSON is not yet implemented, only the Status Text interface was wrapped so far. To use it just create a corresponding Status Text API Client like so:

private readonly StatusTextApiClient apiClient = new StatusTextApiClient("http://localhost", 6001);

This line assumes that you have a running x3270 terminal that was started with -httpd switch on Port 6001:

wc3270 -httpd 6001 +S -utf8 "test.wc3270"

In this example UTF8 was turned on and a session with the name test was used.

Use the API Client

Once you brought up the API client you can remote control the x3270 terminal with ease:

// Check the connection status first
var response = await this.apiClient.CheckConnectionStatus().ConfigureAwait(false);
if (response.ErrorText != string.Empty)
   throw new Exception("Ups, something went terribly wrong!");
// Get the screen in ASCII representation
var ascii = await this.apiClient.Ascii().ConfigureAwait(false);
// Check the content
if (ascii.PayLoad.ToAsciiMatrix()[15][10] == "u")
{
   // Press "Enter"
   await this.apiClient.Enter().ConfigureAwait(false);
}

Make Use of the Status Line

Every successful command execution of StatusTextApiClient returns the status line in form of properties:

var response = await this.apiClient.Ascii().ConfigureAwait(false);
if (response.KeyboardState != "U")
{
   // Do something if the keyboard state is not equal to "Unlocked".
}

Cancellation Support

Every command supports cancellation.

var cts = new CancellationTokenSource(10000); // Ten seconds timeout
var response = await this.apiClient.Ascii(null, cts.Token).ConfigureAwait(false);

Error Handling

X3270.Rest also covers exceptions that come along the way.

try
{
   // Try to send a key where you maybe shouldn't ...
   await this.apiClient.Key('+').ConfigureAwait(false);
}
catch (RequestException ex)
{
  Console.WriteLine($"An error occured: {ex.Message}");
  Console.WriteLine($"HTTP status code: {ex.HttpStatusCode}\nInternal error code:{ex.ErrorCode}");
}

Commands

A list of supported commands and how you can execute not supported commands is explained here