Bumping up the number of CGI jobs servicing your Valence apps

Your IBM i HTTP Server powered by Apache is a powerful web-serving system akin to a bank staffed with multiple fast-working tellers. The AJAX requests coming in from your front-end apps are like customers entering the bank to perform transactions. Each “customer” queues up in an orderly line on a first-in/first-out basis, and is serviced by the next available “teller” as soon as they’re finished dealing with the prior customer. The tellers in this analogy are the CGI jobs you can see churning away in the QHTTPSVR subsystem. 

By default most IBM i systems are configured in Apache to spawn up to a maximum of five concurrent CGI jobs in each server instance.  So whenever a large number customers come into the bank with longer-running transactions to perform, the queue of AJAX requests waiting to be serviced can become noticeable to users by virtue of a longer response time in the apps they’re running. The Apache Server will spawn CGI jobs (or add bank tellers) as needed to service incoming requests (customers), up to the maximum allowed in your settings. 

This month’s tip shows how you can adjust this configuration so you can effectively “expand your bank” so there are more tellers servicing your customers, thereby improving the response time on your apps during certain busy periods. You can typically see the number of CGI jobs currently available to service a particular instance by looking for active jobs with “PGM-QZSRCGI” listed as the current function.  So if your production instance of Valence is named VALENCE51P, you could see the jobs catering to that instance via command WRKACTJOB JOB(VALENCE51P), resulting in something like this:

Figure 1 – Spotting CGI jobs via WRKACTJOB command

In this case you can see an example of some very busy “bank tellers” servicing VALENCE51P, as there are only five CGI jobs in the instance, all of them actively churning with a status of RUN (whereas idle “tellers” would show a status of TIMA or TIMW).  In this scenario there would almost certainly be a number of HTTP/AJAX requests (“customers”) waiting in line to be serviced, so bumping up the number of CGI jobs would likely be helpful to speed up response times. The best way to adjust the maximum number of CGI jobs is by using the web administration utility that should be accessible on port 2001. 

To access it, point your browser to xxx.xxx.xxx.xxx:2001/HTTPAdmin (where xxx.xxx.xxx.xxx is the address of your IBM i system) and log in with the appropriate IBM i user.  If you don’t get any response it may be an indication that your administration server instance is not running (ADMIN jobs running in your QHTTPSVR subsystem), in which case you can start up your Admin sever from a command line via STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN). Select the appropriate server instance on the HTTP Servers tab, then click on “General Server Configuration” on the left panel.  The key configuration for controlling the CGI jobs is the “Number of threads to process requests” field near the bottom of the page (this value is ultimately stored as the “ThreadsPerChild” setting in the configuration file).  A “thread” is essentially synonymous to a CGI job in the case of our Valence instances, so the value here controls the maximum number of CGI jobs the instance will spawn to service your users.

Figure 2 – Accessing the CGI jobs setting for a Valence instance

Note that if the value in this “Number of threads to process requests” field is blank — as it tends to be on most systems by default — it means it’s deferring to your global HTTP Server setting.  You can see that global value in one of two ways:  (1) By prompting the CHGHTTPA command, where the value is in the “Number of server threads – Maximum” field (figure 3 below); or (2) by going to the Advanced tab in the web administration page and clicking on Global Server Settings link on the left panel (figure 4).

Figure 3 – Finding the global max CGI default via CHGHTTPA
Figure 4 – Accessing the same value via the web administration page

 Although changing the global default for all your HTTP server instances is certainly an option, most administrators prefer to set the CGI job value on the individual server instances themselves (figure 2), since some are likely busier than others (i.e., production instances versus test instances). Note that once you make an adjustment to this setting you must completely stop and restart your server instance before the change takes effect.  A simple restart via the VVSTART Valence command, or using the RESTART(*HTTP) setting on the STRTCPSVR command, won’t cut it.  Also keep in mind that any value you specify for the number of threads should be less than or equal to the “Maximum active CGI jobs” value specified in the General Settings tab of the Dynamic Content and CGI page.  For most locations this is set to 40, which should be more than ample for most Valence sites.

Performance tuning in Apache is a bit of an art — you don’t want the overhead of having too many jobs spawned, but neither do you want too few.  So you should experiment with this thread configuration and find a number that works for your needs.  Ideally it should be extremely rare that you would spot all of your CGI jobs occupied in a RUN status, as depicted in figure 1.  

Special note:  Some Valence sites have been using a different technique to control the CGI jobs that involves manipulating the QUSRSYS/QATMHINSTC file containing HTTP Server definitions.  The process entails adding a “-uiMax xx” directive to the member corresponding to the instance name, where xx is the number of CGI jobs.  IBM does not recommend this approach as it is not an officially supported function within the HTTP server group.