Accessing an IBM i called or service program

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 
         ],
         resourceBindingURI = @Resource{uri = "binding:file:EGLDDFile#MyConnection"}
      }
   }
end   

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 the following help topic: Resource bindings.

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.

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?{@AS400DecimalFloat{length = 34}};

   //Convert using the default AS400PackedDecimal
   f5 decimal(10,2);

   //Convert using the AS400ZonedDecimal
   f6 decimal(10,4){@AS400ZonedDecimal{}};
end

Consider the following proxy function, which resides in an EGL Program type:

Program TestSimpleProgram

   //On IBM i, only service programs support a return
   function MyHostProcedure(p1 string, p2 string)RETURNS(INT)
   {
      @IBMiProgram{
         programName = "/QSYS.LIB/VARLABXX.LIB/GETREC",
         resourceBindingURI = @Resource{uri = "binding:file:someConnection"},
         isServiceProgram= true,
         parameterAnnotations = [@AS400Text{length = 10}, @AS400Text{length = 10}]
      }
   }
   end
end

Here is a call from another function in the same program, including reference to a Customer Record type. The call relies on the binding detail that was just shown in the resourceBindingURI field:

cust Customer;
result Int;
myString String = "abc";
try
   call MyHostProcedure(myString, cust) returns (result);
   onexception(exception AnyException)
	    //handle exception
end

cust Customer;
result int;
myString String = "abc";
conn IBMiConnection? = SysLib.getResource(uri="binding:file:someOtherConnection");
try
   call MyHostProcedure(myString, cust) 
      using conn
      returns (result);
   onexception(exception AnyException)
	     //handle exception
end

The following code is equivalent to the previous logic:

cust Customer;
result int;
myString String = "abc";
try
   call MyHostProcedure(myString, cust) 
      using SysLib.getResource(uri="binding:file:someOtherConnection") 
         as IBMiConnection
      returns (result);
   onexception(exception AnyException)
	     //handle exception
end

Here is yet another alternative call, which might provide a value of type IBMiConnection instead of referencing the EGL deployment descriptor:

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

If you want to access the AS400 connection pool from your code, you also assign connection detail to a variable of type IBMiConnection; but for that purpose, you invoke the static Java function that is referenced in the following EGL external type:

externalType JTOpenConnections type JavaObject
   private constructor();
   static function getAS400ConnectionPool()returns(AS400ConnectionPool);
end

Here are the fields:

dateFormat

The date format for AS400Date objects.

This value overrides the default date format, which is com.ibm.as400.access.AS400Date.FORMAT_ISO. For an individual parameter or field that is being passed to the proxy, you can specify a ibmiFormat value on the AS400Date annotation, and that value overrides any other, with one exception: any ibmiSeparatorChar value on that annotation is used for the separator value.

dateSeparator

The date separator for AS400Date objects.

This value overrides the date separator that is specified in the dateFormat value. For an individual parameter or field that is being passed to the proxy, you can specify a ibmiSeparatorChar value on the AS400Date annotation, and that value overrides any other.

encoding

The character encoding for AS400Text objects.

This value overrides the default encoding, which is obtained from the CCSID value of the AS400 connection. For an individual parameter or field that is being passed to the proxy, you can specify an encoding value on the AS400Text annotation, and that value overrides any other.

library

The library where the program is located. If you specify a value for this field, you replace any value specified in the IBMiProgram annotation, library field.

password

The password for the specified user ID.

system

The IBM i system name.

timeFormat

The time format for AS400Time objects.

This value overrides the default time format, which is com.ibm.as400.access.AS400Time.FORMAT_ISO. For an individual parameter or field that is being passed to the proxy, you can specify a ibmiFormat value on the AS400Time annotation, and that value overrides any other, with one exception: any ibmiSeparatorChar value on that annotation is used for the separator value.

timeSeparator

The time separator for AS400Time objects.

This value overrides the date separator that is specified in the timeFormat value. For an individual parameter or field that is being passed to the proxy, you can specify a ibmiSeparatorChar value on the AS400Time annotation, and that value overrides any other.

timeZone

The time zone for AS400Date, AS400Time, and AS400Timestamp objects.

This value overrides the default time zone, which is obtained from the timezone value of the AS400 connection. For an individual parameter or field that is being passed to the proxy, you can specify an ibmiTimezoneID value on the AS400Date, AS400Time, or AS400Timestamp annotation, and that value overrides any other.

userid

The user ID that provides access to the IBM i system.