List Signed On Users From a Web Page
December 14, 2005 Shannon O'Donnell
The code for this article is available for download.
If you are like me, you receive support calls at the most inconvenient times. For example, when you are at a conference and you don’t have access to your own PC. Many times these calls are simply related to poor system performance, and I could resolve some of these issues simply by knowing who is signed on to my system. There are a few users in my company, probably like there are in your own, who are notorious for running complex queries or submitting the same job over and over simply because the first one didn’t complete as fast as they thought it should have. Since often times I have access to a PC and the web, but not access to an emulator, I got to wondering if there was a quick way to see what jobs were running on the system.
The first thing that came to mind was to use iSeries Access for Web. This Web-based product from IBM would easily give me all the functionality that I needed for a situation like this. However, programmer that I am, I wanted a solution that I could create myself so that I would be able to understand how every single component of it worked. Having the ability to expand on it as my needs grew was important to me too. That got me to thinking that there was probably something simple I could do to view active jobs on the system through the Web and which would allow me to customize it as needed. Thinking about all of this led me to the QEZSLGNU (List Signed On Users) API.
List Active Users API
By using the QEZSLGNU API you can generate a list of users who are signed on to your system. When you combine this API with a little bit of RPG IV and CGI, you end up with a winning combination that can grow as your needs grow. In this article I will show you how to use the QEZSLGNU API and then how to display its output on a Web page from your iSeries.
To use the QEZSLGNU API you will need to dump its output to a user space object. So the first thing we need to do is to create the user space. We do that with the following bit of code:
* Create the Qualified User Space Name C Eval qUserNm = 'LSTACTVUSRQGPL ' C Eval qText = 'List Active Users' * * Attempt to delete the user space first... * Just to clean it up C Call 'QUSDLTUS' 50 C Parm qUserNm C Parm dsEc * * Now create the user space C Call 'QUSCRTUS' 50 C Parm qUserNm C Parm *Blanks eXtAtr C Parm 5000 iNzSize C Parm *Blanks iNVal C Parm '*CHANGE' pUbAut C Parm qText C Parm rEplace C Parm dsEc *
As you can see here, we first named the user space, then attempted to delete it if it already existed, and then we tell the API to create the user space in library QGPL.
Once the user space has been created we can then call the QEZSLGNU API to list only the users who are currently signed on the system into the user space. You can also choose to list any user who has a job on the system, even if they are not currently signed on. Here’s the code to list the signed on users:
* Now List the Active Users and Place Into The User Space C Call 'QEZLSGNU' C Parm qUserNM C Parm 'SGNU0200' Format C Parm '*ALL' iUser C Parm '*ALL' iDisplay C Parm '*NO ' iDscJobs C Parm '*NO ' iSgnOff C Parm dsEc
Extracting Data from the User Space
Now that the actively signed on users have been listed into the user space, we can iterate through that user space to retrieve the information.
|
If you have never used any of the List APIs on the iSeries, then looping through a user space might be new to you. Don’t let that discourage you if you fall into that category. The List APIs are actually pretty easy to use, assuming you define the required data structures correctly ahead of time, that is. And since I have already done that for you, there should not be any problem using these APIs.
Every List API shares a common header data structure. That is, no matter what kind of information you return from a List API, such as QEZSLGNU, they will all have the following information:
*************************************************** * List Data Generic Header *************************************************** D HdrSection Ds D UserArea 64 D GenHdrSiz 10i 0 D StrucLevel 4 D FormatName 8 D ApiUsed 10 D CreateStamp 13 D InfoStatus 1 D SizeUsUsed 10i 0 D InpParmOff 10i 0 D InpParmSiz 10i 0 D HeadOffset 10i 0 D HeaderSize 10i 0 D ListOffset 10i 0 D ListSize 10i 0 D ListNumber 10i 0 D EntrySize 10i 0
You can retrieve the header information into this data structure from the user space by executing this bit of code:
* Get the User Space Header Section C Call 'QUSRTVUS' C Parm qUserNM C Parm 1 qStart C Parm 140 qLen C Parm *Blanks HdrSection C Parm dsEc
Within this data structure you have all the information you need to process the contents of the user space. For example, by looking at the ListNumber variable, you can tell how many entries were returned by the QEZSLGNU API. In other words, in this case, the number of active users signed on. By looking at the EntrySize variable, you can tell how long each group of data in the list is, and by looking at the ListOffset, you can tell where in the user space to start extracting data. Knowing all of this, we can then very easily loop through the user space and pull out the information we need.
* Write the HTML Header Information to the Browser C Exsr HTMLHdr * C Eval qStart = ListOffset + 1 * * ** Loop through User Space for number of list entries returned C Do ListNumber * C Call 'QUSRTVUS' C Parm qUserNM C Parm qStart C Parm EntrySize qLen C Parm *Blanks SgnU0200 C Parm dsEc * * Write the HTML Detail Information To the Browser from * the contents of the User Space C Exsr HTMLDtl * C Eval qStart = qStart + EntrySize C Enddo
Within this section of code, the first thing we do is to send the HTML Webpage header information to the browser. You can refer to the sample program that accompanies this article to see how that part works. The next thing we do is set our pointer to the beginning of the returned data in the user space. We can determine this starting position by adding one to the ListOffset from the header data structure. Then entering the loop, which will loop for the number of entries returned in the list, we can call the QUSRTVUS (Retrieve User Space) API to pull the list data out of the user space and dump it into our data structure, which describes the output from the QEZSLGNU API, SgnU0200.
**************************************** * Output format for API QEZLSGNU **************************************** D SGNU0200 DS D Display 10a D UserName 10a D Job# 6a D Activity 10a D ActivityName 10a D DscJobAlwdI 1a D Rsvrd17 17a D DspDesc 50a D UsrDesc 50a
We got the format for this data structure from the online documentation on IBM’s Information Center Website for the QEZSLGNU API. As you can see from this, you can retrieve the user ID, the display name, and the job number, along with some other descriptive information, for each user who is signed on.
Writing the Information to the Browser
Now that you have this information, all you need to do is to write it out to your Web browser. To do that, we send the data to be written to the Web browser to the QtmhWrStout, (Write To Standard Output, API).
**************************************************** * Writes HTML Code to STDOUT (user's browser) C SendToBrwsr Begsr * * Get the length of the data to write to STDOUT C eval BrwsrDtaln = %len(%trimr(BrwsrDta)) * C Callb 'QtmhWrStout' C Parm BrwsrDta C Parm BrwsrDtaln C PARM DsEc * C Endsr
For this example, I am doing nothing more than building a simple HTML table into my Web page with some table headings that describe the data in the table, and then for each row of the table, I am listing the information returned in the SGNU0200 data structure.
You can refer to the code for this article to see how I built the table. For more detailed information on how to use the CGI APIs to push a Web page to the browser from the iSeries, please refer to my article “Step by Step, RPGIV and Interactive Web Pages.” That article contains complete instructions on how to create a CGI program, and how to set up the HTTP Server on your iSeries to serve the output from your CGI programs to your users via the Web.
Time to Customize
Now that you have a prototype of how to display from the Web, who is signed on to your system, you can begin to expand on it. For example, you might add a form that allows you to look up specific user profiles, or perhaps you want to search by user profile description. When you combine the QEZSLGNU API with other object and job function APIs, you can begin to create a truly unique and useful bit of information serving that will give you exactly what you need to fully manage your shop when you are away from the office.
RELATED STORY
