In prior releases of the operating system HTTP Apache is limited to running only in the QHTTPSVR subsystem. At V7R1 and above we have the ability to run servers in their own subsystem. The following document describes how to configure this.
Resolving The Problem
NOTE: This functionality is built into the initial GA of V7R2 and V7R3. It was later added to V7R1 in HTTP group PTF SF99368 level 30.
In order to setup an HTTP server to run in its' own subsystem we first need to create a user defined HTTP server subsystem, job description, class, job queue along with setting the job queue and routing entry . Here are the steps to create these objects:
1. Create a new library
Create a new library for example: HTTPSVR24 to store all IBM i native objects like subsystem description, job queue, job description, class and so on.
2. Create job queue
This is where the job is submitted before it starts running. The HTTP job can be submitted to QBATCH or some other queue, but we are showing a customized way here. Create job queue entry HTTPSVR24 in the library you created above.
CRTJOBQ JOBQ(HTTPSVR24/HTTPSVR24) OPRCTL(*YES) AUTCHK(*OWNER) AUT(*USE) TEXT('User defined HTTP Job queue')
3. Create job description
This defines how the job should be run and can be customized according to specific requirements as needed. Create a job description named HTTPSVR24 in the above library and associate it with the job queue you just created.
CRTJOBD JOBD(HTTPSVR24/HTTPSVR24) JOBQ(HTTPSVR24/HTTPSVR24) TEXT('User defined HTTP job description') USER(QTMHHTTP) RTGDTA(HTTPSVR) JOBMSGQFL(*WRAP)
Note: This step is optional. We can also use the default HTTP job description QHTTPSVR/QZHBHTTP where the default routing data is HTTPWW, here we use HTTPSVR as an example.
4. Create class
The class defines the processing attributes for the jobs. The class used by a job is specified in the subsystem description routing entry used when starting the job, we simply need a class here. Create a default one named “HTTPSVR24”.
CRTCLS CLS(HTTPSVR24/HTTPSVR24) RUNPTY(25) TEXT('User defined HTTP Server job class')
Note: This step is optional. We can also use the default class QHTTPSVR/QZHBHTTP
5. Create subsystem description
Here’s where the HTTP server jobs actually run . Create the subsystem with the same name as the class defined in previous section, HTTPSVR24. The important component that needs to be defined for the subsystem is the memory pool that all jobs running in this subsystem will use. There are two kinds of memory pools that can be used, base memory pool and private memory pool. The base memory pool contains all unassigned main storage on the system which can be shared by many subsystems. However, the private memory pools (also known as user-defined memory pools) contain a specific amount of main storage which can be used by only a single subsystem. Using a private memory pool means you can manage memory for this subsystem without interference by other subsystems or jobs on the system. If you want to use the base memory pool, issue the CL command like below:
CRTSBSD SBSD(HTTPSVR24/HTTPSVR24) POOLS((1 *BASE)) MAXJOBS(*NOMAX) AUT(*USE) TEXT('User defined subsystem using *BASE pool')
If you want to create own private pool especially for the subsystem, issue the below CL command for example:
CRTSBSD SBSD(HTTPSVR24/HTTPSVR24) POOLS((1 1024 500 *MB)) MAXJOBS(*NOMAX) TEXT('User defined subsystem using private pool')
(Note: 1024 specifies the size of the new storage pool, 500 specifies the maximum number of threads that can run at the same time in the pool. You can configure your private memory pool according to your requirements. This article creates a private memory pool and sets its pool-size/thread-number to 1024MB/500. Memory and active threads is a component of application performance that needs to be watched closely. If your applications start to be memory constrained or are running out of threads, your application performance can be adversely effected. )
6. Add job queue entry
This command tells the subsystem which job queue it should search for jobs to run. Here we let subsystem HTTPSVR24/HTTPSVR24 search job queue HTTPSVR24/HTTPSVR24.
ADDJOBQE SBSD(HTTPSVR24/HTTPSVR24) JOBQ(HTTPSVR24/HTTPSVR24) MAXACT(*NOMAX) SEQNBR(10)
7. Add routing entry
Add the routing entry to subsystem defines the criteria of job selection and parameters used to start a job.
ADDRTGE SBSD(HTTPSVR24/HTTPSVR24) SEQNBR(10) CMPVAL(HTTPSVR) PGM(QSYS/QCMD) CLS(HTTPSVR24/HTTPSVR24)
1. If you don't create your own class via step 4, you can use the HTTP server default class QHTTPSVR/QZHBHTTP.
2. CMPVAL(*ANY) means allow anything. The default compare value for HTTP server is HTTPWWW. In this example, we will use HTTPSVR as the routing data. You can also add multiple other routing entries.for example:
ADDRTGE SBSD(HTTPSVR24/HTTPSVR24) SEQNBR(20) CMPVAL(HTTPWWW) PGM(QSYS/QCMD) CLS(HTTPSVR24/HTTPSVR24)
WRKSBSD HTTPSVR24/HTTPSVR24 (Take an opt. 5, then a 7)
Opt Seq Nbr Program Library Compare Value Pos
10 QCMD QSYS 'HTTPSVR' 1
20 QCMD QSYS 'HTTPWWW' 1
If the any of the compare values do not match the routing data value specified by RTGDTA() parameter in the SBMJOB command , the job will not be selected and run in the subsystem.
8. Modify the HTTP Apache configuration
Using the examples from the previous steps we would then add the following directives to the Apache configuration so that the server is pointing at the newly created Job Queue, Job Description, Routing Data, and Subsystem Description:
- HTTPStartJobQueue HTTPSVR24/HTTPSVR24
9. Starting/Stopping the Server
The server can now be started/stopped via the normal STRTCPSVR/ENDTCPSVR commands:
STRTCPSVR SERVER(*HTTP) HTTPSVR(SERVER)
ENDTCPSVR SERVER(*HTTP) HTTPSVR(SERVER)
NOTE: As of now the IBM Web Administration GUI (http://systemname:2001/HTTPAdmin) is not able to detect the correct status of the server when it is running in its' own subsystem (it can only determine the status for servers running in the default QHTTPSVR subsystem). The server will always show in a 'stopped' status in the GUI.
18 December 2019