EDT:Support for IBM i

As an EGL developer, you can access IBM i called programs, as well as procedures in IBM service programs.

Access to any of those host programs is by way of the JTOpen toolkit, which determines what program types are supported. For an overview of the toolkit, see the following web site: (JTOpen).

Your coding task has the following aspects:

• You write an EGL proxy function for IBM i. The proxy function might be in an EGL Library, Service, Handler, or Program type. The function has no logic, and any logic you place there will be ignored. Instead, you write one or more annotations there to tell the EGL Java generator how to structure the runtime call.
  
  The main annotation is IBMiProgram. In most cases, that annotation references a resource binding in the EGL deployment descriptor. 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 write the EGL code that calls the function, you might access the proxy function and rely on the details provided there. Alternatively, you might do as follows:

1. Code a variable that references a different resource binding or that specifies new detail.
2. Refer to that variable in the using clause of the call statement.
   
   

When you include a using clause, the coded detail overrides any IBMiProgram annotation reference to the EGL deployment descriptor. 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.

• The parameters of the EGL proxy function represent the parameters of the host program, and your call can pass simple data, as well as records and handlers. If a value is returned from the proxy function, the type of value is an EGL Int. (On IBM i, a return value is possible from a service program but not from a called program.)

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.

Runtime process

At run time, the proxy function is an endpoint for accessing an IBM i program. That function acts as follows:

1. Retrieves a connection for the AS400 connection pool, if you are using that kind of connection.
2. Converts your data from an EGL format to byte arrays. The structure of those arrays is based on a set of AS400DataType classes that are provided by the JTOpen toolkit.
3. Creates a JTOpen ProgramCall or ServiceProgramCall object, depending on whether the call is to an IBM i called program or service program.
4. Creates JTOpen ProgramParameter objects and passes the byte arrays to them.
5. Calls the host program by calling the run method on the ProgramCall or ServiceProgramCall object.
6. Reformats the returned value (if any) to EGL format.
7. Converts the returned byte arrays to EGL format. The structure of those arrays is based on a set of AS400DataType classes that are provided by the JTOpen toolkit.
8. Returns the connection to the AS400 connection pool, if you are using that kind of connection.
   
   

Development process

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 AS400xxxx. The annotation type names correspond to the JTOpen com.ibm.as400.access.AS400Datatype class names.

To determine which annotations to specify, refer to the table shown later, along with the Javadoc for the com.ibm.as400.access.AS400Datatype classes.

EGL proxy functions for IBM i

Here is an example of an EGL proxy function, including the annotations named ExternalName and IBMiProgram:

function GETRECA(CUST CUST[] inout, 
                 EOF   string inout, 
                 COUNT decimal (2,0) inout) {

      @ExternalName{value="MyHostProc"}
      
      @IBMiProgram {         
         programName = "GETREC",
         libraryName = "/QSYS.LIB/VARLABXX.LIB/"
         isServiceProgram=true,
         parameterAnnotations = [
            @AS400Array{elementCount = 10},
            @AS400Text{length = 1},
           	null 
         ],
         connectionResourceBindingURI = 
            @Resource{uri = "binding:file:EGLDDFile#MyConnection"}
      }
   }
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 IBMiProgram is the primary annotation that structures the call. The annotation holds the following detail:

• The path of the library and program on IBM i.
  
  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.
  
  
• A flag as to whether a service program is being invoked.
  
  
• Annotations for each parameter, as described later.
  
  
• A reference to a binding that is defined in the EGL deployment descriptor. Your call to the EGL proxy function can refer to a different binding in the deployment descriptor, and that reference in the call statement overrides any connection detail that is specified in the function.
  
  The EGL runtime code uses the binding details to construct a JTOpen object of type AS400ConnectionPool.
  
  A resource of type IBMiConnection contains a library field. Any value specified in that field replaces the library field in the IBMiProgram annotation.
  
  For general details on binding, see Resource bindings.
  
  

Annotations for data conversion

The data-conversion annotations cause the use of converters that are found in the following JTOpen package: com.ibm.as400.access. The EGL annotation name is the same as the Java class name.

When you set a value for the parameterAnnotations field, you specify an annotation or the null keyword for every annotation:

• Values of simple reference types require an annotation. Example types are String, Decimal, and Timestamp.
• Values of simple value types require an annotation only if you do not want to accept the defaults. Example types are String(7), Decimal (5,2), and Timestamp("yyyyMMddHHmm").
• Lists require a parameter annotation.
• null is always used for a variable that is based on a Record or Handler type.

If you do not set a value for the parameterAnnotations field, the defaults are used for every parameter.

Equivalent rules are in effect for the fields that are in a container; that is, in a variable that is based on a Record or Handler type. For example, here is a Record type with annotations:

Record Example
 
// Convert using the default AS400Bin4
f1 int;
 
// After the host program call, f2 is resized using the data returned in f3
f2 int[]{@AS400Array{elementCount = 10, returnCountVariable = f3}};
 
// A fixed text with a length 2 characters using the default encoding
f3 string{@AS400Text{length = 2}};
 
//Convert a number to a AS400DecFloat
f4 number?{@AS400DecFloat{length = 34}};
 
//Convert using the default AS400PackedDecimal
f5 decimal(10,2);
 
//Convert using the AS400ZonedDecimal
f6 decimal(10,4){@AS400ZonedDecimal{}};
 
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.