Creating IBM i program call Java bean and PCML file

Program call bean limitations

Procedure

  1. Program call definitions that invoke a program can have a maximum of 35 parameters.
  2. Program call definitions that invoke a procedure in a service program can have a maximum of 7 parameters
  3. The PCML attributes Min version and Max version are only valid for program call beans that have the Use PCML option enabled.

Run-time support classes

The Program call wizard generates the following runtime support class files once for each project.

Example

AbstractProgramCallBean

This is the parent class for all program call beans. It contains common methods and properties of all program call beans.

LogonSpec

This class contains the host name, user ID, and password that is used to connect to the remote system. If your application will be running on the remote system, you can use these special values for hostname, user ID, and password: "localhost", "*CURRENT", "*CURRENT". The current user profile is used to perform program calls.

IConnection
This is the connection interface that the program call bean uses to connect to the remote system. Associated with each program call bean is an IConnection object. An IConnection defines the following methods:
  1. getAS400() - this method returns an AS400 object that the program call bean uses to establish a connection with the remote system for the program call.
  2. releaseAS400() - this method is used by the program call bean to free the connection after the program is invoked.
The program call bean will use the getAS400() method to get an AS400 object before attempting to call the program. After the program is called, it will use the releaseAS400() method to free the connection. The flow of the program call is : getAS400() -> Call remote program -> releaseAS400()

The program call wizard generates 3 classes that implement this interface: AS400Connection, PooledAS400Connection, JcaAS400Connection.

AS400Connection

An AS400Connection is a simple wrapper around an AS400 object. You will want to associate this type of connection with the program call bean if your application is managing all the connections to the remote system.

A RuntimeContext contains all the information defined in the runtime configuration file as well as other global information shared by different program call beans. There is one RuntimeContext instance for each configuration file defined in your project.

Example 1:

TestProgram pgm = new TestProgram(); 
AS400Connection myConnection = new AS400Connection(myAS400);
pgm.initConnection(myConnection);
PooledAS400Connection

A PooledAS400Connection is a connection that is part of a connection pool. The getAS400() method returns an AS400 object from the pool. Using the hostname, user ID, and password specifed in the LogonSpec object, the method attempts to find an existing AS400 object in the pool. If one is available, it is returned. Otherwise, a new AS400 is created. After the program is invoked, the AS400 object is put back to the connection pool by the releaseAS400() method.

Note that the library list and initial command information in the LogonSpec object is not used in the search for an existing AS400 object in the pool. These information are only used when a new connection is created. The libary list information is used to setup the initial library list. Likewise, the initial command is executed once only. If your application manipulates the library list at runtime, you should beware that any changes made to the library list will be persisted when the connection is re-used at a later time. Also, you should not define two connections with the same hostname, user ID, and password but different library list and initial command information. Doing so may result in your program getting a connection with an incorrect library list. For example, say program A defines a connection that specifies library LIBA to be in the library list. Program B defines a connection with the same hostname, user ID, and password but it specifies library LIBB to be in the library list. At runtime, the program B may end up using the connection defined by program A.

The connection pool is an instance of the Toolbox AS400ConnectionPool class. The connection pool stays open until your application ends. However, your application can explicitly close the pool by using the getPoolInstance() method to get a handle to the pool. With a handle to the pool, you can also configure other settings such as the minimum and maximum number of allowed connections.

Connections are created on an as needed basis. Once created, they stay in the pool until the pool is closed.

The following examples show how to use PooledAS400Connection.

Example 1:

TestProgram pgm = new TestProgram();
LogonSpec logonInfo = new LogonSpec();
logonInfo.setHostName("mySystem");
logonInfo.setUserName("user");
logonInfo.setUserPw("password");
PooledAS400Connection pooledConn = new PooledAS400Connection(TestProgram.getRuntimeContext().getAS400ConnectionPool(), logonInfo);
initConnection(pooledConn);
JcaAS400Connection

A JcaAS400Connection represents an ISeriesPgmCallConnection JCA connection. The getAS400() method will do a look up using the specified JNDI name for the JCA connection. This JCA connection must be an instance of ISeriesPgmCallConnection. The returned AS400 is the one that is inside the ISeriesPgmCallConnection JCA connection.

The releaseAS400() method will close the JCA connection.

In order to use the JcaAS400Connection, you must setup a separate connector project. Refer to Setting up the IBM i program call J2C connector for the WebSphere test environment for more information.

Example 1: In this example, a JCA connection is created using the default logon information in the JCA connector project.

String jndiName = "my.jca";
JcaAS400Connection jcaConn = new JcaAS400Connection(jndiName);
initConnection(jcaConn);

Example 2: In this example, a logon specification is provided to over-ride the default the logon information of the connector project.

String jndiName = "my.jca";
JcaAS400Connection jcaConn = new JcaAS400Connection(jndiName);
LogonSpec logonInfo = new LogonSpec();
logonInfo.setHostName("mySystem");
logonInfo.setUserName("user");
logonInfo.setUserPw("password");
initConnection(logonSpec, jndiName);
IConnectionFactory

This interface represents a connection factory. Implement this interface to provide custom connections for the program call beans. If you do that, you should update the WDT_CONNECTIONFACTORY variable in the runtime configuration file to point to your connection factory class.

ConnectionFactory

This class implements the IConnectionFactory interface. It creates the following types of IConnection depending on the values that is specified in the runtime configuration file: JcaAS400Connection PooledAS400Connection

Messages

Messages issued by the program cal beans are defined in this class. There is a corresponding Messages.properties file that stores the text of the messages.

Constants

Constants used by the program call beans are defined in this class.

Specify the location for the Java bean and PCML file

Before you begin

Use the second page of the Program Call wizard to specify the location where the Java™ bean and PCML file are to be generated.

Procedure

  1. Click Browse next to the Folder field to select an existing folder where you want the Java bean and PCML file to be generated.
  2. Click Browse next to the Package field to select an existing package. If you type a package name that does not exist, the Program Call wizard creates it for you. The default is the package that you selected from the workbench when you started the Program Call wizard.
  3. Specify or select the name that you want to give to the PCML file generated by the wizard in PCML file name. The default name is the Java bean name of the first program that you defined.
  4. The Java application check box is selected by default.
    • If you want a Java bean, leave the Java application check box selected. The generated Java beans can be used in any Java code. This includes any standalone Java application or Java components of Web applications such as servlets and JSP pages. The wizard generates a Java bean for each program defined.
    • If you want a Web Services bean, select the Web Services check box. The generated Java beans can be used by the Web Services wizard to create a Web service.
    • If you want program calls to be performed with Toolbox's ProgramCallDocument class, choose the Use PCML check box. You should select this option if any parameters or fields in your program define a Min version or a Max version.
  5. Click Next to proceed to the next page of the Program Call wizard and choose whether to generate a runtime configuration file.

Results

The Program Call wizard generates classes for each program that you define along with classes that represent data structures. If you selected the option to generate Web service, three additional classes will be generated for each program. One of the classes is a Java bean whose name ends with the word Services. The other two classes have names ending with Input or Result. These two classes are required by the Web Services Java bean class. If you want to create a Web service using the Web Services wizard, you have to use the class whose name ends with the word Services as input to the Web Services wizard.

In addition to the classes mentioned above, the wizard also generates runtime support class files once for each project. For more details, see Run-time support classes.

The wizard also creates a PCML file and a .mpcml file. You do not need the .mpcml file when you deploy your application or services. It is used only at design time in the workbench. Also, a .config file is created, if you advance to the third page of the wizard and specify that you want the settings saved.

If the folder that you specified belongs to a Java project, the class path of the project is updated to include the following JAR files. When you deploy your Java application, ensure that these JAR files are set in your application class path. Note that the iseriespgmcallclient jar file is added only if your project is J2EE compliant.

  • WDSC_HOME\plugins\com.ibm.etools.iseries.toolbox_version_number\runtime\jt400.jar
  • WDSC_HOME\plugins\com.ibm.etools.iseries.javatools_version_number\lib\confighelper.jar
  • WDSC_HOME\plugins\com.ibm.etools.iseries.javatools_version_number\lib\iseriespgmcallclient.jar

If the folder that you specified belongs to a Web project, these jar files are copied to the lib folder of your Web project. Note that the iseriespgmcallclient jar file is added only if your project targets a J2EE compliant server.

What to do next


Feedback