JT400 Extension Pack for IBM i

Green Screens JT400 Extension Pack - is a module on top of JT400 improving usage of JT400 ProgramCall class by helping to map IBM i program parameters and response formats.

We were not happy with PCML approach as neither with writing a lot of manual specific code required for calling IBM i program, so we developed our own engine based on Java Dynamic Proxy and InvocationHandler technology.

Calling IBM i programs have 3 main elements

Program itself to call
Program parameter format
Program response data format

Base principle is to create 2 Java POJO classes, first one describing program call parameters and second one describing response data format. Classes will use special annotations as instructions to data types, sizes and value order for parameters or positions for data format. Optionally, we can create a helper interface for JT400Program as code will look cleaner when used later.

Take for example IBM i QDCRDEVD Api program which will return terminal workstation instance information. Terminal instance is found by display device name and data output in one of supported formats.

Instead of writing a large XML file or writing a lot of boilerplate code, imagine you can do something like this...

final QDCRDEVD params = QDCRDEVD.build(DEVD0100.class, "QPADEV0001");
final IQDCRDEVD program = IQDCRDEVD.create(as400);
final DEVD0100 res = program.call(params, DEVD0100.class);
		
System.out.println(res);
System.out.println(res.getDeviceName());

If a program call was unsuccessful, JT400Excepion is thrown automatically retrieving IBM i error message or list of JT400 AS400Messages just as in JT400 ProgramCall class, but this time in a much cleaner way more streamlined with standard Java behavior.

Let's create a program helper interface first.

public interface IQDCRDEVD extends IJT400Program<QDCRDEVD> {

	public static IQDCRDEVD create(final AS400 as400) {
		return JT400ExtFactory.createProgram(as400, IQDCRDEVD.class);
	}

}

Even we can use JT400Program directly, this little helper will allow us to initialize proxy instance in a much cleaner readable format like this.

final IQDCRDEVD program = IQDCRDEVD.create(as400);

Instead of writing PCML definition files, one can create plain Java POJO class for parameters like this example for QDCRDEVD program.

@JT400Program(
		library = "QSYS", 
		program = "QDCRDEVD", 
		arguments = 5,
		formats = {
			DEVD0100.class,
			DEVD0600.class,
			DEVD0300.class
		})
public class QDCRDEVD implements IJT400Params {

	@Id(0) @Output 
	@JT400Argument(type = AS400DataType.TYPE_BYTE_ARRAY)
	ByteBuffer receiver;

	@Id(1) @Input
	@JT400Argument(type = AS400DataType.TYPE_BIN4)
	int length;
	
	@Id(2) @Input 
	@JT400Argument(length = 10, type = AS400DataType.TYPE_TEXT)
	String formatName;

	@Id(3) @Input 
	@JT400Argument(length = 10, type = AS400DataType.TYPE_TEXT)
	String deviceName;
	
	@Id(4) @Input @Output
	@JT400Argument(type = AS400DataType.TYPE_BYTE_ARRAY)
	ByteBuffer errorCode;
}

If you follow the QDCRDEVD Api link on IBM web site, the structure shown above will look familiar. It should be enough self-explanatory, so further explanation is probably not needed.

One more additional feature is the possibility to define partial data format definitions for returned data. Usually, returned data from IBM i API's are byte array. It is quite simple to create a converter builder based on Java class format definition like this one.

@JT400Format(length = 1124)
public class DEVD0600 extends DEVD0100 {

	@JT400Format(offset = 892, length = 10)
	protected String jobName;
	
	@JT400Format(offset = 902, length = 10)
	protected String userName;
	
	@JT400Format(offset = 912, length = 10)
	protected String jobNumber;

	@JT400Format(offset = 918, length = 10)
	protected String currentMessageQueue;

	@JT400Format(offset = 928, length = 10)
	protected String currentMessageQueueLibrary;

	@JT400Format(offset = 877, length = 15)
	protected String ipAddress;
}

Original DEVD0600 format structure is much larger with much more data, but we defined only those we are interested in. This will reduce development time. Look at @JT400Format annotations and compare them with DEVD0600, mapping is straightforward.

Library is open sourced under MIT license is freely available. To get complete source code from our GitHub repository, simply follow this link Green Screens JT400 Extension Pack.

Also, check out Part 4 of our QuarkEngine tutorial where we present how to use JT400 extension pack as a web service.