For z/OS platforms

Administering Liberty on z/OS

On the z/OS® platform you can start, stop, or modify Liberty by using MVS™ operator commands.

Before you begin

Ensure that the following security profiles are set up as described in Enabling z/OS authorized services on Liberty for z/OS.
  • STARTED profiles for the server process, and the angel process
  • SERVER profiles to allow access to authorized z/OS services
Attention:

Each LPAR can have one default angel process. You can give an angel a name if the angel is started at V16.0.0.4 or later. That angel can become an additional angel process on that LPAR. For more information about angels and LPARs, see Named angel. Where possible, ensure that the default angel process is running at the latest installed level of Liberty on the LPAR. If a Liberty server instance connects to an angel that is running at an earlier service level, some features of the server might not be available.

About this task

This topic describes how to start, modify, and stop Liberty by using the MVS console. You can also start and stop the server from a shell, or use a shell to start the server as a started task, see Starting and stopping a server from the command line.

CAUTION:
Do not include # or $ characters in the job name. Liberty constructs a UNIX path with the job name in it. The # and $ characters can cause incorrectly formed UNIX paths.
A started task is JCL that is run immediately in response to an operator START command. Two JCL procedure templates (PROCs) are available in the wlp/templates/zos/procs directory. One template is for the server process, and the other is for the angel process:
  • bbgzsrv for Liberty.
  • bbgzangl for the angel process that is required for controlling access to system authorized services on the z/OS platform.
Administrators can copy the templates to a user location, and then customize them to start Liberty servers from the MVS console.
Note: Files in the /templates directories might be modified when product updates are applied.
The examples section provides further information about the two PROC templates.

The target of an operator STOP command is a job or a started task.

After the JCL procedure templates are customized, they must be placed into the system procedure library concatenation. The name of the procedure member becomes the argument to the START command.

Procedure

  • To start a process, use the START command for the appropriate proc:
    • START bbgzsrv to start the bbgzsrv proc for the server process
    • START bbgzangl to start the bbgzangl proc for the angel process
  • To modify Liberty, use the MODIFY command.
    See the following topics:
  • To stop a process, use the STOP (p) command for the appropriate proc:
    • STOP bbgzsrv to stop the bbgzsrv proc
    • STOP bbgzangl to stop the bbgzangl proc
    Attention:

    Canceling the Angel process started task (What to do if the Angel process started task abends)

    A best practice is to NOT ever cancel the angel process. Server tasks and application tasks can be depend on the angel process running. However, there are rare cases in which to avoid a severe system shutdown, such as a re-IPL, you might find it necessary to cancel the angel process. If you ever need to cancel the angel started task or if the angel started task should abend, your WebSphere® Application Server administrator should cancel the servers with applications dependent on the successful running of the angel started task. Leaving the server(s) and application(s) running can result in a server hang condition.

Example

The following example shows the procedure template for the server process (bbgzsrv). This PROC is in a data set in the z/OS proclib concatenation.

//BBGZSRV PROC PARMS='defaultServer'
//*------------------------------------------------------------------
//* INSTDIR - the path to the WebSphere Liberty install.
//*           This path is used to find the product code and is
//*           equivalent to the WLP_INSTALL_DIR environment variable
//*           in the Unix shell.
//* USERDIR - the path to the WebSphere Liberty user area.
//*           This path is used to store shared and server specific
//*           configuration information and is equivalent to the
//*           WLP_USER_DIR environment variable in the Unix shell.
//*------------------------------------------------------------------
//  SET INSTDIR='/u/MSTONE1/wlp'
//  SET USERDIR='/u/MSTONE1/wlp/usr'
//*------------------------------------------------------------------
//* Start the Liberty server
//*
//* WLPUDIR - PATH DD that points to Liberty's "user"
//*           directory. If the DD is not allocated, the user
//*           directory location defaults to the wlp/usr directory
//*           in the install tree.
//* STDOUT  - Destination for stdout (System.out)
//* STDERR  - Destination for stderr (System.err)
//* MSGLOG  - Destination for messages.log (optional)
//* STDENV  - Initial Unix environment - read by the system.  The
//*           installation default and server specific server
//*           environment files will be merged into this environment
//*           before the JVM is launched.
//*------------------------------------------------------------------
//STEP1   EXEC PGM=BPXBATSL,REGION=0M,
//  PARM='PGM &INSTDIR./lib/native/zos/s390x/bbgzsrv &PARMS' 
//WLPUDIR  DD PATH='&USERDIR.' 
//STDOUT   DD SYSOUT=* 
//STDERR   DD SYSOUT=* 
//*MSGLOG   DD SYSOUT=*
//*STDENV   DD PATH='/etc/system.env',PATHOPTS=(ORDONLY) 
//*STDOUT   DD PATH='&ROOT/std.out', 
//*            PATHOPTS=(OWRONLY,OCREAT,OTRUNC), 
//*            PATHMODE=SIRWXU 
//*STDERR   DD PATH='&ROOT/std.err', 
//*            PATHOPTS=(OWRONLY,OCREAT,OTRUNC), 
//*            PATHMODE=SIRWXU
Notes:
  • The launcher uses the STDENV DD as the initial environment, but this DD is optional. The initial environment to the process is defined in the PROC. It can point to any type of data set that Language Environment® supports, but the format must be compatible with what is expected. For example, Extended Binary Coded Decimal Interchange Code (EBCDIC), simple key=value with no expansion.
  • A PATH DD that points to an existing directory (not a file) is allowed. If that DD is opened, the FILE stream that is returned is valid for fldata so the HFS path that is associated with the DD can be used. The PROC template defines a WLPUDIR PATH DD that represents the equivalent of WLP_USER_DIR.
  • The WLP_USER_DIR is determined by the following logic:
    • If the WLPUDIR DD is defined, the associated path is used as WLP_USER_DIR.
    • If WLPUDIR is not defined but WLP_USER_DIR is set in the initial environment (from STDENV), it is used.
    • If WLPUDIR is not defined and WLP_USER_DIR is not set in the initial environment, the default value of $WLP_INSTALL_DIR/usr is used.
  • The environment is determined by the following logic:
    • If you define the STDENV DD, then Language Environment reads the entry as the initial environment.
    • If $WLP_INSTALL_DIR/etc/server.env exists and is readable, its key=value contents are read and set into the environment. The file can be in ASCII or EBCDIC. Comments start with a pound sign (#) and go to the end of the line. Values that contain blank space can be placed in double quotation marks. Any environment entries that are specified in this file overrides entries from the initial environment.
    • If $WLP_USER_DIR/servers/{serverName}/server.env exists and is readable, its key=value contents are read and set into the environment. This file can also be in ASCII or EBCDIC and supports comments. Any entries that are specified here override entries from the initial environment and the etc/server.env.
    • Regardless of the user specified environment, the following entries are explicitly set: _BPXK_WLM_PROPAGATE=NO, JAVA_THREAD_MODEL=HEAVY, and JAVA_PROPAGATE=NO. If _EDC_PTHREAD_YIELD is not set, it is set to -2.
  • After the environment is set, the JAVA_HOME is determined by the following logic:
    • If JAVA_HOME is set in the environment, its location is used as JAVA_HOME.
    • If JAVA_HOME is not set in the environment but $WLP_INSTALL_DIR/../java64 exists, $WLP_INSTALL_DIR/../java64 is used as JAVA_HOME.
    • If JAVA_HOME is not set in the environment and $WLP_INSTALL_DIR/../java64 does not exist, $WLP_INSTALL_DIR/../java is used as JAVA_HOME.
  • After JAVA_HOME is determined, JVM command line options are determined by the following logic:
    You can create multiple jvm.options files in the following locations. These files are merged in order from the beginning to the end of this list before server start and are used as the JVM options for the server.
    • ${wlp.install.dir}/usr/shared/jvm.options
    • ${server.config.dir}/configDropins/defaults/jvm.options
    • ${server.config.dir}/jvm.options
    • ${server.config.dir}/configDropins/overrides/jvm.options
    If none of these files are present, then the ${wlp.install.dir}/etc/jvm.options file is read.
    In addition to the JVM command-line options that are merged from any jvm.options files, the following options might also be merged.
    • The -Dfile.encoding=iso8859-1 option is set only if the -Dfile.encoding property is not already set in any merged jvm.options file or the JVM_ARGS environment variable.
    • The -javaagent:$WLP_INSTALL_DIR/lib/bootstrap-agent.jar option is set only if the WLP_SKIP_BOOTSTRAP_AGENT environment variable is not set to TRUE.

    The server process always sets the -Djava.class.path=$WLP_INSTALL_DIR/lib/ws-launcher.jar option from the command line.

    To provide JVM command-line options when the jvm.options files are read-only, consider using the IBM_JAVA_OPTIONS environment variable, which overrules command-line options and thus any options set in jvm.options files.

  • When you start a Liberty server with a z/OS procedure, you can customize the umask that is used by the server process. To customize the umask, define the WLP_SKIP_UMASK and the _BPX_BATCH_UMASK environment variables in one of the following ways:
    • Specify the WLP_SKIP_UMASK environment variable. You can specify this variable in the server.env file, or, if you start the server with a z/OS procedure, you can specify the variable under the STDENDV DD entry. In the z/OS procedure, specify the _BPX_BATCH_UMASK variable under the STDENV DD entry. You cannot specify the _BPX_BATCH_UMASK variable in the server.env file. The following example shows a sample umask value customization:
      //STDENV DD *      
_BPX_BATCH_UMASK=XXXX
WLP_SKIP_UMASK=TRUE
/*
    • Specify both _BPX_BATCH_UMASK=XXXX and WLP_SKIP_UMASK=TRUE in an EBCDIC encoded z/OS UNIX file. Define the path under the STDENV DD entry in the z/OS procedure. The following example shows a sample umask value customization:
      //STDENV DD PATH='u/path/to/env/ebcdic/file',PATHOPTS=ORDONLY
The following example shows the command that you would use to start Liberty by using the sample bbgzsrv proc for a configured "defaultServer": 
start bbgzsrv,parms='defaultServer'
The following example shows the procedure template for the angel process (bbgzangl): 
//BBGZANGL PROC PARMS='',COLD=N,NAME=''
//*------------------------------------------------------------------
//  SET ROOT='/u/MSTONE1/wlp'
//*------------------------------------------------------------------
//* Start the Liberty angel process
//*------------------------------------------------------------------
//STEP1   EXEC PGM=BPXBATA2,REGION=0M,TIME=NOLIMIT,
//      PARM='PGM &ROOT./lib/native/zos/s390x/bbgzangl COLD=&COLD NAME=X
//             &NAME &PARMS'
//STDOUT    DD SYSOUT=*
//STDERR    DD SYSOUT=*