z/OS JCL cataloged procedures

This concept is an explanation of how WebSphere® Application Server for z/OS® server uses the JCL cataloged procedures.

Each WebSphere Application Server for z/OS server uses a JCL cataloged procedure. These procedures are all fairly similar and consist of a main cataloged procedure and an INCLUDE member that contains DD statements. Here are sample cataloged procedure library members for a controller as generated by the Profile Management Tool or the zpmt command:

Procedure library member BBO7ACR:
//BBO7ACR  PROC ENV=,PARMS=' ',REC=N,AMODE=00                   
// SET ROOT='/wasv7config/bbobase/bbonode'                      
// SET FOUT='properties/service/logs/applyPTF.out'              
// SET WSDIR='AppServer'                                        
//************************************************************* 
//* Test that OMVS can successfully launch a shell and return * 
//************************************************************* 
//TOMVS   EXEC PGM=BPXBATCH,REGION=0M,                          
// PARM='SH exit 13'                                            
//SYSOUT   DD PATH='&ROOT./&ENV..HOME/&FOUT.',                  
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=(SIRWXU,SIRWXG)   
//SYSPRINT DD PATH='&ROOT./&ENV..HOME/&FOUT.',                  
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=(SIRWXU,SIRWXG)   
//*********************************************************     
//* If the shell RC code is as expected (13) - proceed    *     
//*********************************************************     
//IFTST   IF (RC = 13) THEN                                     
//*********************************************************     
//* Start the Multi-Product PTF Post-Installer            *     
//*********************************************************     
//APPLY   EXEC PGM=BPXBATCH,REGION=0M,                          
// PARM='SH &ROOT./&ENV..HOME/bin/applyPTF.sh inline'           
//SYSOUT   DD PATH='&ROOT./&ENV..HOME/&FOUT.',                  
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=(SIRWXU,SIRWXG)   
//SYSPRINT DD PATH='&ROOT./&ENV..HOME/&FOUT.',                  
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=(SIRWXU,SIRWXG)   
//       IF (APPLY.RC <= 4) THEN                                
//*********************************************************          
//* If the RC from the Post-Installer is LE 4 then start  *          
//* the WebSphere Application Server                      *          
//*********************************************************          
//STEP1    EXEC PGM=BPXBATA2,REGION=0M,TIME=MAXIMUM,MEMLIMIT=NOLIMIT,
// PARM='PGM &ROOT./&WSDIR./lib/bbooctlm &AMODE. &PARMS. REC=&REC'   
//STDENV DD PATH='&ROOT/&ENV/was.env'                                
//*                                                                  
//* Output DDs                                                       
//*                                                                  
//CEEDUMP   DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                      
//SYSOUT    DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                      
//SYSPRINT  DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                      
//DEFALTDD  DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                      
//HRDCPYDD  DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                      
//          ENDIF                                                    
//IFTSTEND ENDIF 
Procedure library member BBO7ASR:
//BBO7ASR  PROC ENV=,AMODE=00                                       
//  SET ROOT='/wasv7config/bbobase/bbonode'                         
//  SET WSDIR='AppServer'                                           
//STEP1   EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT,MEMLIMIT=NOLIMIT,
//         PARM='PGM &ROOT./&WSDIR./lib/bboosrmr &AMODE.'           
//STDENV    DD PATH='&ROOT/&ENV/was.env'                            
//*                                                                 
//* Output DDs                                                      
//*                                                                 
//CEEDUMP   DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                     
//SYSOUT    DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                     
//SYSPRINT  DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                     
//DEFALTDD  DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE                     
//HRDCPYDD  DD SYSOUT=*,SPIN=UNALLOC,FREE=CLOSE 
[oct2010] The cataloged procedure specifies where the procedure is processed: [oct2010]
oct2010
The PARM= parameter on the EXEC PGM statement contains the parameters that are passed to the program identified by the PGM= parameter.
Note: The appropriate interface for making changes to the language environment (LE) parameters is through the was.env file; however, do not modify any LE parameters without first consulting with the IBM® Software Support team. The LE parameters are set internally to ensure the best possible performance of the WebSphere Application Server, which is the main LE application running in the address space. If you need to add or change LE parameters, make sure that you work with the IBM Software Support team to ensure that the internally set parameters are not compromised.

The STDENV DD statement points to the was.env (startup parameter) file for the server. The path to this file consists of the configuration HFS directory name (hardcoded using the ROOT JCL variable) and the symbolic link for this particular server, which is specified at startup using the ENV= parameter.

The controller cataloged procedure includes some additional statements before the EXEC statement that invokes BPXBATA2. These are used to invoke the post installer program that applies any needed maintenance to the configuration HFS and its home directories when service is applied to the product HFS and load modules.

The following sections describe the cataloged procedures required for each configuration, provide a recommended naming convention, and explain how the SAF user ID for each server is determined.

Cataloged procedures for standalone application servers

A standalone application server uses the following cataloged procedures:
  • Controller cataloged procedure
  • Servant cataloged procedure
  • Adjunct process cataloged procedure
  • Location service daemon cataloged procedure

You can use the same cataloged procedures for different standalone servers if the configuration HFS and product code level (including STEPLIB) are the same for both servers.

Cataloged procedures for Network Deployment cells

A Network Deployment cell uses the following cataloged procedures:

For the deployment manager:
  • Deployment manager controller cataloged procedure
  • Deployment manager servant cataloged procedure
For each application server node:
  • Application server controller cataloged procedure (also used for the node agent)
  • Application server servant cataloged procedure
  • Adjunct process cataloged procedure
For the location service daemon (one per z/OS system):
  • Location service daemon cataloged procedure

The application server servant cataloged procedure is the only one likely to require modification, in order to place libraries (CICS®, DB2®, and so on) in the STEPLIB concatenation.

You can use the same cataloged procedures for several nodes in a Network Deployment cell, or even for several cells, if the configuration HFS is the same for all of them.

A recommended cataloged procedure naming convention

Use a consistent naming convention for your WebSphere Application Server for z/OS cataloged procedures. The procedure name should distinguish between WebSphere Application Server for z/OS version and configuration HFS

The following convention works for either a standalone application server or Network Deployment cell, for example, where cc is a two-character cell identifier:
Deployment manager controller cc7DCR
Deployment manager servant cc7DSR
Location service daemon controller cc7DMN
Application server controller cc7ACR
Application server servant cc7ASR
Control region adjunct cc7AAR
If you require separate cataloged procedures for nodes on different systems in a sysplex (if they need independently settable STEPLIB statements to allow for a nondisruptive restart for example), either place the location service daemon and application server procedures in system-specific proclibs or append a one-character system identifier to the cataloged procedure names for the location service daemon and application servers.

Assigning user IDs to WebSphere Application Server for z/OS address spaces

If you use z/OS Security Server (RACF®) as your SAF-compliant security system on z/OS, then STARTED class profiles are used to assign started task user IDs to each WebSphere Application Server for z/OS server. These STARTED profiles are set up by the batch jobs created by the Profile Management Tool or the zpmt command. Update these STARTED profiles as needed to place servers that you create yourself under the appropriate user IDs.

Controllers (deployment manager, location service daemon, node agent or applications server controller) are started using a console START command that you issue either from the MVS™ console or internally. For these servers, the STARTED profile name that is checked is of the form procname.jobname.

Whenever it creates a controller or daemon cataloged procedure, the Profile Management Tool or the zpmt command also creates a STARTED profile that associates all controllers using that cataloged procedure with the appropriate controller user ID and configuration group. If you set up a standalone application server with default names, therefore, the Profile Management Tool or the zpmt command would create the following STARTED profiles for controllers:
  • RDEFINE STARTED BBO7ACR.* STDATA(USER(WSCRU1) GROUP(WSCFG1) TRACE(YES))
  • RDEFINE STARTED BBO7DMN.* STDATA(USER(WSCRU1) GROUP(WSCFG1) TRACE(YES))
Note: TRACE(YES) writes message IRR812I to the MVS console whenever the profile is used.

Servant regions (application server servants and adjunct processes) are started using Workload Manager (WLM). For these servers, the STARTED profile name that is checked is of the form jobname.jobname.

Unfortunately, there is no way to assign all servers using a particular servant cataloged procedure to a servant user ID. Therefore, the Profile Management Tool or the zpmt command creates a STARTED profile for each servant and one for each control region adjunct. If default names are chosen, the following servant STARTED profiles are created for a standalone application server:
  • RDEFINE STARTED BBOS001S.* STDATA(USER(WSSRU1) GROUP(WSCFG1) TRACE(YES))
  • RDEFINE STARTED BBOS001A.* STDATA(USER(WSCRU1) GROUP(WSCFG1) TRACE(YES))
When you choose cataloged procedure names, make sure that the appropriate STARTED profile is in place to map the server to its appropriate SAF user ID. Use the RACF ISPF panels or the RLIST STARTED command to display the STARTED profiles.

If you use another SAF-compliant security system, contact the security server vendor for WebSphere Application Server for z/OS setup information.

Cataloged procedure for the administrative asynchronous task

The asynchronous administrative task also requires a cataloged procedure. This very simply cataloged procedure does not include a STEPLIB or configuration HFS pointer. Because it must run under a specific user ID and group associated with the security domain of the cell for which it runs, however, you must choose a different cataloged procedure name for each security domain or cell.

Recommendation: Name the administrative asynchronous task cataloged procedure "ccADMH," where cc is a two-character cell identifier.



Related concepts
Configuration file systems
Concept topic    

Terms of Use | Feedback

Last updated: Oct 22, 2010 2:27:32 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-zos&topic=cins_plancatzos
File name: cins_plancatzos.html