Recently, I customized an i5/OS connector to an AS/400 system. This was a system that I had limited experience with in the past, so the first step was researching what made a user within the system, what objects get attached to that user, and what permissions needed to be set for the user to have access to the subsystems they need. In doing that, I was able to gain a generic understanding of the OS/400 server, some basic commands, and how to traverse myself through the applications.
I knew my next hurdle would be the drivers shim. The i5/OS connector uses a shim which leverages internal CL (command language) scripts to perform the work on the server, as the driver can’t run these commands directly. After getting the shim installed on the AS/400 server, I first checked that the shim was up via its web-service front-end. From here I saw that there was the ability to look at the trace logs, directly through the web-service, but upon attempting could not seem to get them to display. At this point I FTP’d into the AS/400 server going to /usr/local/<library_name>/logs/ and was able to pull my log file down to my local computer. Upon opening these logs, it was immediately evident that it was using a character set that I was not familiar with. Luckily I had the TextFX plugin for notepad++ handy, and was able to run ‘Convert EBCDIC to ASCII’ and could actually read my logs!
Now that I had my arsenal ready, I began more closely examining the CL scripts of the shim to get a better feel for the potential of this connector. First, I tried to pull the scripts to my local computer, assuming I could convert to ASCII make my changes, convert back to EBCDIC and upload it back to the server. Since I already said it was the first thing I tried, you might have guessed that didn’t quite work out. The line breaks were different and the horizontal ruling broke at 80 characters, instead of the 72 most people are familiar with, so I relinquished my hopes of editing that code locally and began looking into editing the files on the server and doing my work there. I quickly found the ‘EDTF’ command which gives you a text editor to look at the CL.
One of the first thing I noticed was in the base CL code, the SPCAUT variable was declared with a very small character limit (9 I believe), but my client wanted to be able to supply many special authorities simultaneously, many of which values were 5-6 characters a piece. At this point I started hunting down if there was a system limitation on the special authority that mandated it not be more than 9 characters, but couldn’t find anything of the sort. I thought to myself, “It can’t be this easy” and I simply changed that 9 limitation to 100. The next change was within the CL script RENUSER which handles rename events. Since the OS/400 system doesn’t actually support the renaming of user profiles, what happens is: it copies all values out of the existing profile, creates a new profile with those values and then runs DLTUSRPRF to delete the old profile. Unfortunately, the DLTUSRPRF function call, as I later found out, deletes all objects owned by that profile. So even though it copied a pointer to the old users MSGQ for example, once this command ran, that object would be deleted, and you have a new account pointing at invalid data. After hunting down some documentation, I found that you can supply an additional parameter to DLTUSRPRF called OWNOBJOPT, which will allow you to transfer ownership of all owned objects to the new account before the old account gets deleted.
This was all fine for most of the objects, OUTQ for example, however, my client then specified that they wanted the MSGQ to always be named the same as the account it is owned by. So having an account that used to be BJONES, which had been renamed to BSMITH but still had a MSGQ of BJONES wasn’t going to work. At this point, I changed the code for the CRTUSRPRF call where it sets the MSGQ to the value from the previous account, and replaced that line with MSGQ(*USRPRF) which will make the account make a new MSGQ object that has the same name as this account. At this point, after the DLTUSRPRF that now transfers ownership, since it now deletes nothing but the user account, I specifically run the DLTMSGQ command to wrap things up.
At this point your CL source code needs to be compiled, using the CRTBNDCL command. At this point you will see 1 of two outcomes. The first outcome is one of success, where this command will tell you that your program has been created. The second is a simple message of “Program not created”. How useful… At this point you can append the parameter OPTION to the CRTBNDCL command with the value of *EVENTF, making your command CRTBNDCL … … OPTION(*EVENTF). This will create an EVFEVENT file that you can then open to see the output of the attempted compilation to see any errors.
Now that I had the shim working how I wanted, I realized it needed to be deployed to multiple AS/400 servers, but I knew I didn’t want to redo all of this work for each system. So without further ado, I give you the instructions for repackaging your shim, and pulling it off of the remote server so it can be reinstalled and deployed to later systems.
1) On the server run CRTSAVF file(QSYS/<distribution_name>)
This will create the file where you will pack up your library.
2) Run SAVLIB LIB(<library_name>) DEV(*SAVF) SAVF(QSYS/<distribution_name>)
This backs up the specified library into your file.
3) From your host machine run FTP <server_name>
Enter your authentication information when prompted.
4) Run CD QSYS
Changes your directory to where you backed up your library.
5) Run BIN
This puts you in Binary image format so your host operating system can recognize the file.
6) Run GET <distribution_name>.file
This will put the file on your host computer, so you can now deploy to any number of sites with your customized code.
I hope this blog has helped to sort out some confusion on this topic. If you have any questions, please leave a comment.
Recently we launched HealthcareIDM.com, a site dedicated to our Healthcare Identity Management Connectors/Drivers. Please visit the site to learn more about the work we're doing to simplify the way IDM works in healthcare settings.
What is IDM? Get your Identity and Access Management questions answered here.