Direct access to IBM i host programs is by way of the JTOpen toolkit, which determines what program types are supported. Details on that toolkit are here: JTOpen (http://jt400.sourceforge.net/).
When you deploy code that requires use of the toolkit, the EGL deployer places the JTOpen jar file (org.jtopen_0.8.1.jar) in the WebContent/WEB-INF/lib folder.
In either case, when you deploy your code outside of the IDE, you might need to add the JTOpen jar file as a resource in the server classpath.
As in service access, the main annotations in the EGL proxy function are Resource, which tells "where" the backend code resides, and a second annotation that tells "what more" is required by the EGL generator. The "what more" annotation for IBM i is IBMiProgram.
One runtime effect of referencing a resource binding is that you gain the performance benefits of using a connection from the AS400 connection pool.
When you include a using clause, the coded detail overrides the Resource annotation. If the using clause references a different deployment-descriptor entry, you still gain the performance benefits of using a pooled connection. However, the using clause might represent a connection that you define in your code; and in that case, you typically do not use a pooled connection, but rely on the AS400 connection object that is available in the JTOpen toolkit.
In general, a Rich UI application uses an asynchronous version of the call statement to get enterprise data from a service. In relation to an IBM i program, the application calls a public proxy function that is defined in an EGL Service type.
The objects expected by the host are based on fixed-size types, whereas many EGL types are variably sized. You handle the difference by annotating the variably sized objects.
The annotations you specify are in the eglx.jtopen.annotations package, with annotation type names that of the form Structxxxx. The xxxx part of an annotation type name correspond to a class name in the JTOpen com.ibm.as400.access.AS400Datatype package.
To determine which annotations to specify, refer to the table shown later, along with the Javadoc for the com.ibm.as400.access.AS400Datatype classes.
function GETRECA(CUST CUST[] inout, EOF string inout, COUNT decimal (2,0) inout) { @ExternalName{value="MyHostProc"}, @Resource{uri = "binding:file:EGLDDFile#MyConnection"}, @IBMiProgram { programName = "GETREC", libraryName = "/QSYS.LIB/VARLABXX.LIB/", isServiceProgram=true, parameterAnnotations = [ @AS400Array{elementCount = 10}, @AS400Text{length = 1}, null ] } } end
The ExternalName annotation is optional. It holds the name of the IBM i procedure and defaults to the name of the EGL proxy function.
The Resource annotation is optional. It provides a default value; specifically, a reference to a binding that is defined in the EGL deployment descriptor. See the earlier "Development overview" section for details about the different implications of a local and remote call. Also note that any value specified in the library field of the deployment descriptor entry replaces the library field in the IBMiProgram annotation, which is the primary annotation that structures the call.
You can specify both details on the programName field; in the current example, the field value would be "/QSYS.LIB/VARLABXX.LIB/GETREC". In any case, the EGL runtime code appends a file extension to the value of the programName field: .SRVPGM for service programs, .PGM for called programs.
The data-conversion annotations cause the use of converters that are found in the following JTOpen package: com.ibm.as400.access. The EGL annotation is similar to the Java class name: the annotation name begins with "Struct" and ends with a substring such as "Bin4." The use of the more general "Struct" substring in place of "AS400" facilitates the future use of System z or other backend code.
If you do not set a value for the parameterAnnotations field, the defaults are used for every parameter.
Record Example //Convert using the default StructBin4 f1 int; //After the host program call, f2 is resized using the data returned in f3 f2 int[]{@StructArray{elementCount = 10, returnCountVariable = f3}}; //A fixed text with a length 2 characters using the default encoding f3 string{@StructText{length = 2}}; //Convert a number to a StructDecFloat f4 number?{@StructDecFloat{length = 34}}; //Convert using the default StructPackedDecimal f5 decimal(10,2); //Convert using the StructZonedDecimal f6 decimal(10,4){@StructZonedDecimal{}}; end
If that Record type included a record, you would not specify an annotation for the included record, but might specify annotations for the fields in that record.
You write a call statement to invoke the EGL proxy function. A using clause, if present, refers to a connection. If a using clause is not present in the call statement or if the call statement is in a Rich UI application, the proxy function must reference a deployment descriptor entry.
Program TestSimpleProgram //On IBM i, only service programs support a return function MyHostProcedure(p1 string, p2 string)RETURNS(INT) { @Resource{ uri = "binding:someEntry" }, @IBMiProgram{ programName = "/QSYS.LIB/VARLABXX.LIB/GETREC", isServiceProgram= true, parameterAnnotations = [@StructText{length = 10}, @StructText{length = 10}] } } end function main() end end
cust Customer; result Int; myString String = "abc"; try call MyHostProcedure(myString, cust) returns (result); onexception(exception AnyException) //handle exception end
Here is an alternative call, which provides binding detail that overrides the binding detail, if any, that is specified in the proxy function:
cust Customer; result int; myString String = "abc"; conn IBMiConnection? = Resource.getResource("binding:someOtherConnection"); try call MyHostProcedure(myString, cust) using conn returns (result); onexception(exception AnyException) //handle exception end
cust Customer; result int; myString String = "abc"; try call MyHostProcedure(myString, cust) using Resource.getResource("binding:someOtherConnection") as IBMiConnection returns (result); onexception(exception AnyException) //handle exception end
cust Customer; result int; myString String = "abc"; conn IBMiConnection? = getMyDefinedConnection(); try call MyHostProcedure(myString, cust) using conn returns (result); onexception(exception AnyException) //handle exception end
externalType JTOpenConnections type JavaObject private constructor(); static function getAS400ConnectionPool()returns(AS400ConnectionPool); end
For details on that function, see the JTOpen documentation for the AS400ConnectionPool object.
You can set a variety of fields in the EGL deployment descriptor entry. The type of each entry is AS400Connection, which is compatible with the IBMiConnection type that is used in the code examples.
You can use the fields in the deployment descriptor to override default behavior. In addition, you can set annotations on a field or parameter that is being passed to the proxy function, and that annotation overrides all other settings.
This value overrides the default date format, which is com.ibm.as400.access.AS400Date.FORMAT_ISO. The format specifies a separator character, but that character can be overridden; for details, see dateSeparator.
This value overrides the date separator that is specified in the dateFormat field value.
This value overrides the default encoding, which is obtained from the CCSID value of the AS400 connection.
This value overrides the default time format, which is com.ibm.as400.access.AS400Time.FORMAT_ISO. The format specifies a separator character, but that character can be overridden; for details, see timeSeparator.
This value overrides the date separator that is specified in the timeFormat field value.
This value overrides the default time zone, which is obtained from the timezone value of the AS400 connection.
For more detail on what input is valid, see the annotation-specific entries in the next section.
EGL type | EGL annotation | Annotation fields |
---|---|---|
bigint | StructBin8 (the default) or StructUnsignedBin4. | |
bytes (not yet supported) | StructArray | For a non-parameterized bytes type:
|
date | StructDate |
|
decimal | StructPackedDecimal; StructZonedDecimal; or StructDecFloat. | For a non-parameterized decimal type:
See the paragraph after this table. |
float | AS400Float8 (the default). | |
Handler types | No annotation. Conversion is controlled by the AS400Structure Java class. | |
int | StructBin4 (the default) or StructUnsignedBin2. | |
List types | StructArray (the default). You must specify the annotation if you need to use any of the annotation fields. None of those fields has a default value. For examples, see a later section. |
|
Record types | No annotation. Conversion is controlled by the AS400Structure Java class. | |
string | StructText (the default). | For a non-parameterized string type:
For any string type:
See the paragraph after this table. |
smallfloat | StructFloat4 (the default). | |
smallint | StructBin2 (the default), StructBin1, or StructUnsignedBin1. | |
time | StructTime (the default). |
|
timestamp | StructTimestamp (the default). The conversion to an IBM i timestamp format is in accordance with the Java FORMAT_DEFAULT field in the following class: com.ibm.as400.access.AS400Timestamp. |
|
The following types can be parameterized: Bytes, Decimal, String, Timestamp.
f1 String[] {@StructArray{elementCount = 10, elementTypeAnnotation = @StructText{length= 25}, returnCountVariable = f3}}; f2 Int[] = new Int[5]{@StructArray{elementCount = 5}}; f3 Int;
function TEST(length1 String, f1 String[], f2 String[] ){ @IBMiProgram{ programName = "/QSYS.LIB/VARLABXX.LIB/GETREC", parameterAnnotations = [ @StructText{length=2}, @StructArray{elementCount = 10, elementTypeAnnotation = @StructText{length= 25}, returnCountVariable = length1}, @StructArray{ elementCount = 5, elementTypeAnnotation = @StructText{length= 10} } } ] }
Any value that is used to resize an array must be assignment compatible with an EGL int. An example is length1, which is of type String.