Wednesday, June 17, 2009

Deploying on Websphere Application Server 6.1 for i5/OS

The IBM official alternative to IBM Integrated Web application server for i is websphere application server.

By default, WAS uses the classic JVM, the problem is that, since version 1.0, grails doesn't work with the classic JVM. So to deploy a grails application on WAS, the instance must run with the IBM technology for java VM.

To switch an instance to the IBM technology for java VM, run the following command under qshell:
/QIBM/ProdData/Websphere/AppServer/V61/edition/bin/enableJvm -jvm std32 -profile profile
Where edition is the WAS edition you use.
To switch all instances, you can omit the -profile profile parameter.

Once the instance is switched, you can start it and deploy your app.

The rest is WAS administration

Monday, June 15, 2009

Deploying on IBM Integrated Web Application Server for i

Starting with i5/OS V5R4, you can get the Integrated Web Application Server v7.1. It is meant as a partial replacement for Tomcat which isn't available from IBM for IBM i V6R1 and up. The Integrated Web Application Server is a small footprint J2EE web server. For small CPUs (pre-power4 or partial power5 520s) or systems very low in RAM (less than 2GB) it can be very useful.

There are a few limitations to know about:
* You can have only one DataSource, its jndi name is jdbc/ProxyDS. But you can simulate multiple DataSource (more on this below)
* The DataSource pooling is done by Apache commons pool which is considered as quite slow
* You can only access DB2 for i (local or remote)

The server creation and administration is pretty straightforward via IBM Web Administration for i5/OS.

The default memory limit is very low, so complex webapp won't run out of the box, you're likely to get StackOverflowError. To increase memory limit, edit the /www/appserver/lwi/conf/overrides/i5javaopts.javaopt file and add a line with -Xmx1024m or more.

You can create several "Database connections" which will be made available to all application through the jdbc/ProxyDS DataSource. You assign each connection a "connection ID", one can be *DEFAULT. To get a *DEFAULT connection, you simply use getConnection() on the DataSource. To get a non *DEFAULT connection, you use getConnection(connectionID,null) on the DataSource. I will make further investigation to check if GORM is able to use a non *DEFAULT connection.

Don't forget to apply the latest HTTP PTF group.

Sunday, June 14, 2009

Practical example: jtopen and webservice

At my job we are currently prototyping a monitoring solution. We use a packaged solution to monitor our Unix and Windows servers, our telecom equipments and our AS/400s.

For the AS/400, we want to check verify that our scheduler is up. The way to determine if it's running is to see if a given data area is locked. If it is locked, the scheduler is running. The question was: how to check this from the monitoring box? The first solution was to create a telnet script that would connect to the AS/400, and check if the data area is locked. Of course, this is not the good way to go, this should be considered as a last resort. The second solution was to create a java program on the monitoring package that would use jtopen (the library, not the plugin) to try to lock the data area. This would work but we would be tied between the monitoring solution program and the scheduler (think about updates...). The third solution was to use a web service. The monitoring solution is able to call a web service and take action depending on the result. With grails, creating the web service is so simple a monkey could do it (even I did it!).

The first step is to create a new grails application:
grails create-app monitor

Then we install the jtopen plugin:
grails install-plugin jtopen

For web service, there are several plugins available. I decided to go with xfire plugin, it is the simplest for me:
grails install-plugin xfire

We then create a new service:
grails create-service scheduler

We then instruct xfire to expose the service:
static expose = ['xfire']

We define an ibmI object that will be injected:
def ibmI

We then define the service method:
boolean isSchedulerActive(){
def cr = ibmI.execute("ALCOBJ OBJ((DTAARA *DTAARA *SHRRD)) WAIT(0)")
if(cr.success){
ibmI.execute("DLCOBJ OBJ((DTAARA *DTAARA *SHRRD))")
false
} else {
if(cr.messageList[0].ID == "CPF1002"){
true
} else {
throw new RuntimeException("Unexpected message "+cr.messageList[0].toString())
}
}
}

And that's it!
Let's give a closer look at the method:

def cr = ibmI.execute("ALCOBJ OBJ((DTAARA *DTAARA *SHRRD)) WAIT(0)")
This will try to allocate the data area, returning immediately if the lock can't be locked.

if(cr.success){
ibmI.execute("DLCOBJ OBJ((DTAARA *DTAARA *SHRRD))")
false
}
If the command ran successfully, it means that the data area was not locked. We immediately unlock the data area to avoid being bugged by a ghost lock and return false.

else {
if(cr.messageList[0].ID == "CPF1002"){
true
} else {
throw new RuntimeException("Unexpected message "+cr.messageList[0].toString())
}
}
If the command did not run successfully, we check the message ID returned by the command processor. If the message is a CPF1002, it means that the data area was already locked, meaning the scheduler is active, so we return true. If we have another message, then something went wrong and we throw an exception.

We just have to specify the as/400 host name, user and password in Config.groovy and that's it.

You can take your favorite soap client (I use Mac SOAP Client) and point it to the wsdl which is created by the xfire plugin at: http://localhost:8080/monitor/services/scheduler?wsdl and test the isSchedulerActive method.

And that's all. No boiler plate code, no infinite xml file to write, just strait to the code.

In a next post, I will talk about deployement.

Tuesday, June 9, 2009

Grails jtopen plugin 0.3 is out: user profile authentication

Release 0.3 of the grails jtopen plugin is out.

This new release features user profile authentication.

More information about how to use it in a future post.

Monday, June 8, 2009

grails jtopen plugin 0.2 is out: groovy record level access

GORM is a fantastic tool, it's especially good with tables it creates. When you have legacy tables (without generated IDs, without version field, with composite keys), it's not that good.
Of course, you can fall back to groovy sql support which is very good, but, once again, with legacy tables, SQL is not always the ideal tool.
If you spent several years coding in RPG, you probably sometimes miss the classical but so efficient traditional RPG file access, as I do. Of course it's possible to use the toolbox record level access, but it needs even more boilerplate code than bare metal JDBC.
That's where the jtopen grails plugin 0.2 new feature comes in handy: "groovy record level access".
You can now access files from groovy almost like you would do from RPG:
def file = ibmI.getFile(name:"FILE")
file.setll("KEY1","SKEY1")
def rec = file.reade("KEY1")
while(rec != null){
// Do something with rec...
rec = file.reade("KEY1")
}

Let's have a closer look:
def file = ibmI.getFile(name:"FILE")
This will create a file object, reading the file "FILE". By default, the file will be opened read only, it will be accessed by key if it has a key, otherwise, it will be accessed by arrival order.

file.setll("KEY1","SKEY1")
As the RPG SETLL opcode, this will set the cursor position with the given composite key.

def rec = file.reade("KEY1")
This will read the next record with the partial key equals to "KEY1".

while(rec != null){
// Do something with rec...
rec = file.reade("KEY1")
}
These lines will iterate through the records with the partial key equals to "KEY1".

RPG coders will be happy to have the read, readp, chain, setll, setgt, reade, readpe, write, update and delete methods that are almost identical to the RPG opcodes.

The record object returned by the read* and chain are dynamic POGO with properties from the file fields (case insensitive). For example, if your file has an ITEMCOD field, it can be accessed by rec.itemcode, rec.ItemCod or rec.ITEMCOD or even rec.iTeMcOd.

You can also use groovy iteration methods (each, eachWithIndex, collect, any...) on file objects. In this case, the iteration will process the next records from the current cursor position. It's possible to process the previous records from the current position with:
file.reverse.each { // Do something with the record }

If the file is accessed by key, it is also possible to process a subset of the file based on the key, for example:
file.setll("KEY1") // Iteration function always start from the current cursor position
file.key("KEY1").each { // Do something with the record }

To process the records in reverse order:
file.setgt("KEY1")
file.reverseKey("KEY1").each { // Do something with the record }

For the latest jtopen plugin release, please go to the plugin page.

Wednesday, June 3, 2009

Program call: a practical example

In this post, I will show a practical example of using the jtopen plugin to call a program on the AS/400.

We will create a grails service to execute commands on the AS/400.

We assume we have a grails application with the jtopen plugin installed.

We first have to set the AS/400 host, user and password. We will edit the grails-app/conf/Config.groovy file and add the three following lines:
jtopen.as400 = 'as400'
jtopen.user = 'user'
jtopen.password = 'password'
Of course, you should customize the values to your environment. As they are typically per-environement values, we will set them with the grails.serverURL variable.

We then create a new service:
grails create-service Command

This will create the file grails-app/services/CommandService.groovy, we will change it to:
import org.codehaus.groovy.grails.plugins.jtopen.types.*
class CommandService {
boolean transactional = false
def ibmI

def executeCommand(String command) {
def cr = ibmI.call('QCMDEXC',[
new IChar(command),
new IPacked(command.length(),15,5)] as Type[])
cr.success?:cr.messageList
}
}
And that's it!
Let's have a closer look.

import org.codehaus.groovy.grails.plugins.jtopen.types.*
We import the parameter types used to call the program.

def ibmI
This line creates a property named ibmI. It will automatically be injected with an IbmI object.

def cr = ibmI.call('QCMDEXC',[
new IChar(command),
new IPacked(command.length(),15,5)] as Type[])
Here is the heart of the service. This will call the QCMDEXC API with the two parameters it expects:
  • The command to execute as a CHAR variable
  • The command length as a (15,5) packed decimal
You can see that the QCMDEXC parameters are surrounded by [ and ] as Type[]. This is necessary because of a bug in groovy. This bug has been fixed in the groovy trunk and this circumvention shouldn't be necessary in future grails releases.

cr.success?:cr.messageList
This line makes the service return true if the command execution is successful or the array of messages returned by the command will be returned.

Now let's create a controller using this service:
grails create-controller DataArea

This will create the file grails-app/controllers/DataAreaController.groovy, change it to:
class DataAreaController {
def commandService
def create = {
def result = commandService.executeCommand("CRTDTAARA ${params.name} TYPE(*CHAR) LEN(10)")
render result==true?"Data area ${params.name} created":result.inspect()
}
}
We now start the application:
grails run-app

Now point your browser to:
http://localhost:8080/yourAppName/dataArea/create?name=grails

You should see the message "Data area grails created". On your AS/400, you should have a data area named grails in the jtopen.user user current library (or QGPL).

That's all for this example.

jtopen grails plugin 0.1.2 available

Earlier today, the jtopen grails plugin 0.1.2 was released, here's what's new:
  • A bug with IbmI bean injection was fixed
  • The IBin2 and IBin8 parameter types were added to handle 2-byte and 8-byte integers
  • The IByteArray parameter type was added. This type is useful when a parameter does not have a fixed layout that can be handled by IDataStructure

jtopen grails plugin 0.1.1 available

The 0.1.1 release is available on the grails site.

The only change is that the IbmI object is now a bean that can be injected. You must define the jtopen.as400, jtopen.user and jtopen.password variables in the Config.groovy file.

Tuesday, June 2, 2009

jtopen grails plugin 0.1 available

The first release of the jtopen plugin for grails is now available on the grails site.

Enjoy!

The grails jtopen plugin is coming

Later today I will release version 0.1 of the grails jtopen plugin.

Here is a list of what's included:
  • jtopen 6.5.1
  • injection of an AS400ConnectionPool bean
  • the IbmI class
  • easy program call
  • easy data area access
The IbmI class is a wrapper around the jtopen AS400 object and other objects from jtopen.
The jtopen classes are very well designed and give access to a wide range of functions, but its use is very verbose. The IbmI class gives a more groovy way of using some of these functions in a more natural way for CL and RPG developpers:
  • Easy program call with handling of input and output parameters
  • Easy access to character and decimal data areas
  • Possibility to use traditionnal object names (OBJECT or LIBRARY/OBJECT)
Any comment or suggestion will be appreciated.