Using JCL procedures to start IBM HTTP Server on z/OS

You can prepare JCL procedures to start and stop IBM® HTTP Server from the MVS system console.

By using a JCL cataloged procedure to issue the apachectl start and stop commands, you can start and stop an IBM HTTP Server instance from the MVS system console. Other apachectl commands can be issued from the MVS system console using the same procedure.

Copy the following sample JCL procedure from the HAP.SHAPJCL3(HAPCPROC) member to your system procedure library and substitute the high-level qualifier on your system installation for the HAP value:

//*---------------------------------------------------------
//IHSAPACH PROC ACTION='start',
//          DIR='/path/to/IHS/runtime/directory',
//          CONF='conf/httpd.conf'
//*---------------------------------------------------------
//IHS      EXEC PGM=BPXBATCH,REGION=0K,TIME=NOLIMIT
// PARM='SH &DIR/bin/apachectl -k &ACTION -f &CONF -DNO_DETACH',
// MEMLIMIT=2048M
//STDOUT   DD		PATH='&DIR/logs/proc.output',
//				PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//				PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)
//STDERR   DD		PATH='&DIR/logs/proc.errors',
//				PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//				PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)
//* SYSMDUMP DD ...
//         PEND
//* ==========================================================/
//PROPRIETARY-STATEMENT:/
//Licensed Material - Property of IBM/
// /
//5724-I63, 5724-H88, 5655-N01, 5733-W61, 5655-M23/
//(C) Copyright IBM Corp. 2006/
//All RIghts Reserved/
//US Government Users Restricted Rights - Use, duplication or/
//disclosure restricted by GSA ADP Schedule Contract with IBM Corp./
//===========================================================*/

Warning: The PARM value is limited to 100 characters. Since the PARM value contains the installation directory (&DIR), the total length could exceed the 100 character limit if the directory path is too long. The path name length needs to be taken into consideration when choosing the installation directory. If the installation directory path name is too long, it is possible to use a shorter named path in the JCL that is symbolically linked to the original installation directory path name.

If you require a PARM value greater than 100 characters, you can use the

/PARMIN DD
*,SYMBOLS=JCLONLY

JCL card as illustrated in the following example:

/*------------------------------------------------------
//WEBFTNEI JOB (KOMA-Y98),'Apache NZX2      ',MSGCLASS=T,
//  TIME=NOLIMIT                                        
//         EXPORT SYMLIST=*                             
//*-------------------------------------                
//  SET  ACTION='start'                                 
//  SET  DIR='/home/ihsa/install/webft'                 
//  SET  CONF='../../httpd/webftnei.conf'               
//*-----------------------------------------------------
//IHS EXEC PGM=BPXBATCH,PARMDD=PARMIN,                  
// MEMLIMIT=2048M                                        
//PARMIN   DD *,SYMBOLS=JCLONLY                         
PGM &DIR/bin/apachectl                                  
   -k &ACTION
   -f &CONF
   -DNO_DETACH
//*-------------------------------------------------------
//STDOUT   DD SYSOUT=T                                    
//*                                                        
//STDERR   DD SYSOUT=T                                     
//*                                                       
//                                                        
//STDOUT   DD PATH='&DIR/logs/proc.output',               
//         PATHOPTS=(OWRONLY,OCREAT,OTRUNC),               
//         PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)        
//*                                                      
//STDERR   DD PATH='&DIR/logs/proc.errors',               
//         PATHOPTS=(OWRONLY,OCREAT,OTRUNC),             
//         PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)        
//                                                        
/*----------------------------------------------------------

A description of the apachectl command used in the sample JCL can be found at the Apache HTTP Server Control Interface Web site.

The default jobname for the IBM HTTP Server instance will be the same as the member name of the cataloged procedure. The Web server is a multi-process server, and each additional process that is created will have a generated jobname that is based on the original jobname. If the original jobname is 8 characters long, then all the additional processes will have the same jobname. If the original jobname is less then 8 characters then the additional processes will have jobnames that are composed of the original jobname with an added digit as a suffix. If the Web server is started from the UNIX environment using the bin/apachectl command, then the default jobname will be the userid that the command is running under. As with the jobname, if the userid is 8 characters long, then all the additional processes will have the same jobname. If the userid is less then 8 characters then the processes will have jobnames that are composed of the userid with an added digit as a suffix.

In the following examples, a procedure name of WEBSRV1 is used. Edit the new cataloged procedure by replacing /path/to/IHS/runtime/directory with the actual installation directory for this instance of IBM HTTP Server. Create a SAF STARTED profile to associate the server user ID and group with the Web server started task:

RDEFINE STARTED WEBSRV1.* STDATA(USER(WWWSERV) GROUP(WWWGROUP) TRACE(YES))
SETROPTS RACLIST(STARTED) GENERIC(STARTED) REFRESH

To start the server from the MVS system console, enter:
```
S WEBSRV1
```
Note: The Web server jobname can be changed by adding jobname to the start command, for example:
```
S WEBSRV1,JOBNAME=HTTPDWS1
```
Best Practice 1: Use an eight character jobname. Using an eight character jobname ensures that all the processes created for this instance of the Web server will have the same jobname.
To stop the server, enter:
```
P WEBSRV1
```
Note: When using the System Display and Search Facility (SDSF), you must use the System Command Extension (command entry) screen to enter the command to stop the server.
- At the command prompt, type a forward slash (/) and then hit enter to access the System Command Extension window.
- From the System Command Extension window, enter the S WEBSRV1,ACTION='stop' command. Make sure that stop is in lowercase.
To issue other apachectl commands, enter:
```
S WEBSRV1,ACTION='<command>'
```

To restart the server, enter:
```
S WEBSRV1,ACTION=restart
```
You can restart the server from the z/OS® console.
To gracefully restart the server, enter:
```
S WEBSRV1,ACTION=graceful
```
You can gracefully restart the server from the z/OS console.

The output files for the start and stop commands are located in the files specified on the STDOUT and STDERR DD JCL statements in the procedure

Using the zos_cmds module: If zos_cmds module is active, then you can use the z/OS STOP and MODIFY console commands.

Important: In the httpd.conf file, the following line must be added to activate the zos_cmds module:

LoadModule zos_cmds_module modules/mod_zos_cmds.so

Note: If you are not using a consistent eight character jobname for all the processes, you must determine the jobname of the process that is handling the z/OS operator commands is instance of the Web server. When the Web server is started, it will issue a message to the operator console that identifies the job that is handling the operator commands.

BPXM023I (WASTST1) IHS is active. Use jobname HTTPDWS1 for MVS commands.

where WASTST1 is the userid that the Web server is running under. An entry will be written to the error log that identifies the jobname as well. Notice that the mod_zos_cmds daemon jobname is HTTPDWS1. When a MODIFY command is entered, it gets targeted to every job with the specified jobname. Only one of the Web server processes will accept the command. The system will issue the following message for each of the other jobs of the same jobname. The message will only be prefixed by message ID BPXM023I and a userid if the userid under which the HTTP server is running cannot access the BPX.CONSOLE FACILITY class.

IEE342I MODIFY   REJECTED-TASK BUSY

To stop the server using the stop command:
```
P HTTPDWS1
```
To restart the server using the modify command, enter:
```
F HTTPDWS1,appl='restart'
```
To gracefully restart the server using the modify command, enter:
```
F HTTPDWS1,appl='graceful'
```

When the Web server stops with the zos cmds module active, it will issue the following message to the operator console.

BPXM023I (WASTST1) IHS is stopping

where WASTST1 is the userid that the Web server is running under.

Best Practice 2: The output files are overwritten each time the procedure is used. They might contain warning messages about the configuration or error messages for startup failures. If you want to retain a log of these messages across multiple uses of the procedure, modify the two occurrences of the PATHOPTS option in the sample procedure to PATHOPTS=(OCREAT,OAPPEND,OWRONLY). For more information on the PATHOPTS option, refer to the z/OS MVS JCL Reference (SA22-7597). Link to this document from the z/OS Internet Library.

Best Practice 3: The STDENV DD statement is not recommended. You might consider adding environment variable settings to the bin/envvars file within the runtime directory so that the variables are active whether IBM HTTP Server is started from JCL or from the UNIX environment.

Best Practice 4: The SH parameter of BPXBATCH is recommended instead of the PGM parameter. Processing for the PGM parameter bypasses system default settings in the /etc/profile file, including the umask setting, and files created by IBM HTTP Server do not have the correct permissions.