Starting and stopping the IBM z/OS Connect Servers

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Learn how to use the supplied started task procedure to run z/OS Connect Servers on z/OS.

Setting up a started task to run IBM z/OS Connect Servers

On z/OS, a started task procedure is used to start the IBM® z/OS Connect Server. This topic describes how to use the supplied started task procedure. You must create and configure the z/OS Connect Server that is to be started. For more information about creating a z/OS Connect Server, see Creating an IBM z/OS Connect Server.

A single instance of the started task procedure JCL can be used to start multiple z/OS Connect Servers because the server name is passed as a parameter to the procedure and the JOBNAME parameter can also be specified on the start command to distinguish between different address spaces. You might require multiple copies of the started task JCL, if your z/OS Connect Server requires different settings, for example: JVM_OPTIONS or environment variable values.

To set up the started task procedure, customize the sample JCL provided in <hlq>.SBAQSAMP(BAQSTRT) and add it to your PROCLIB library. The sample BAQSTRT JCL turns on the heap pools algorithms, which can improve performance for C/C++ code that might be called by z/OS Connect or Liberty functions. For more information, see the z/OS documentation A launch icon to indicate a link opens a new tab or window. Using heap pools to improve performance and the two options HEAPPOOLS and HEAPPOOLS64.

The started task procedure must be associated with a SAF user ID with an OMVS segment defined.

For RACF®, specify the OMVS segment parameters HOME and PROGRAM. For example,
```
HOME(/u/<myuser>)
```
and
```
PROGRAM(/bin/sh)
```
The values are case-sensitive.
For non-IBM External Security Managers, specify the OMVS segment HOME parameter value to be the location where the server instances are stored. This location should be the same as the value you specify for the WLP_USER_DIR environment variable. For example, if you are using the default WLP_USER_DIR value of /var/zosconnect, set
```
HOME(/var/zosconnect)
```
Additionally, set any other OMVS segment properties. For example, OMVSPGM, as required by your security manager.
If you use a non-IBM External Security Manager and receive a CHECK_PROC_OWNER error message when you start z/OS Connect as a started task, check that the HOME parameter of the OMVS segment of the started task user ID is correctly defined.

Then, enter the SAF command to associate the name of the started task procedure with a user ID. For example, to define the BAQSTRT procedure name to run under the user ID <userid>, use the following RACF command.

RDEF STARTED BAQSTRT.* UACC(NONE) STDATA(USER(<userid>) GROUP(<group>) PRIVILEGED(NO) TRUSTED(NO) TRACE(YES))

z/OS Connect Server environment variables

Define Liberty environment variables if the default values are not suitable for your configuration.

WLP_USER_DIR

The default is value /var/zosconnect

Used to specify where the runtime environment looks for shared resources and server definitions. This must be the same value that is specified when the server was created.

For example, /var/myservers. If you do not set this value, the default /var/zosconnect is used.

WLP_LOGGING_CONSOLE_LOGLEVEL

The default is value AUDIT.

The logging level used to filter messages written to system streams. Affects the contents of the z/OS Connect Server's STDERR. The valid values are INFO, AUDIT, WARNING, ERROR, and OFF.

AUDIT: Audit and warning messages are written to the system output stream. Error messages are written to the system error stream.
ERROR: Error messages are written to the system error stream.
INFO: Info, audit, and warning messages are written to the system output stream. Error messages are written to the system error stream.
WARNING: Warning messages are written to the system output stream. Error messages are written to the system error stream.
OFF: No server output is written to system streams. Only JVM output is written to system streams.

WLP_LOGGING_CONSOLE_FORMAT

The required format for the console that affects the format of the messages that are written to the z/OS Connect Server's STDOUT. Setting WLP_LOGGING_CONSOLE_FORMAT does not affect the format of messages that are written to the messages.log file. Valid values are DEV, SIMPLE, JSON, or TBASIC. The default value is DEV.

DEV

Use the dev logging format. For example,

[AUDIT ] CWWKE0001I: The server zOSConnServer has been launched.

JSON

Use the JSON logging format. For example,

{"type":"liberty_message",
"host":"192.0.2.0",
"ibm_userDir":"\/var\/zosconnect\/",
"ibm_serverName":"zOSConnServer",
"message":"CWWKE0001I: The server zOSConnServer has been launched.",
"ibm_threadId":"0000000b",
"ibm_datetime":"2023-05-22T10:42:53.041+0000",
"ibm_messageId":"CWWKE0001I",
"module":"com.ibm.ws.kernel.launch.internal.FrameworkManager",
"loglevel":"AUDIT",
"ibm_sequence":"1684752173041_0000000000001",
"ext_thread":"EmbeddedLibertyServer-Thread-2"}

SIMPLE

Use the simple logging format. For example,

[5/22/23 10:46:20:668 GMT] 0000000b com.ibm.ws.kernel.launch.internal.FrameworkManager A CWWKE0001I: The server zOSConnServer has been launched.

TBASIC

Use the tbasic logging format. For example,

[5/22/23 10:48:00:274 GMT] 0000000b FrameworkMana A CWWKE0001I: The server zOSConnServer has been launched.

Environment variables can also be used in the server configuration files. For more information, see Logging environment variables in the WebSphere Application Server Liberty documentation.

Specifying environment variables

To specify optional environment variables, you can use either of these methods:

Started task Specify the STDENV variables in line, as shown in the sample started task procedure that is provided in <hlq>.SBAQSAMP(BAQSTRT).
Started task Use a z/OS UNIX file. For example, place the file <name>.env in the <WLP_USER_DIR>/servers directory, enter each of your environment variables on separate lines, and add the following to the started task procedure:
```
//STDENV DD PATH='<WLP_USER_DIR>/servers/<name>.env'
```
where <name>.env is the name of the file containing the environment variables in the <WLP_USER_DIR>/servers directory.
Containers Specify environment variables in ConfigMaps and Secrets Object store when deploying to a container platform. For more information, see Configure environment variables (Optional).

Specifying JVM options

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

To specify JVM options, you must use the JVM_OPTIONS STDENV variable. If you need to specify multiple JVM options that would exceed the line length of your started task procedure, you can either store all the STDENV variables in a z/OS UNIX file as described before, or store only your JVM options in a z/OS UNIX file. For example, create a z/OS UNIX EBCDIC file that is called <name>.options in the <WLP_USER_DIR>/servers directory, enter each of your JVM options on separate lines and add the following to the STDENV statement of the started task procedure:

JVM_OPTIONS=-Xoptionsfile=<WLP_USER_DIR>/servers/<name>.options

where <name>.options is the name of the file that contains the JVM options in the <WLP_USER_DIR>/servers directory.

Starting an IBM z/OS Connect Server

To start the server started task procedure, enter the following command.

/S BAQSTRT,PARMS='<serverName> [--clean]'

Note: If you are using SDSF to issue your MVS system commands, you must use the System Command Extension window within SDSF to preserve the case of your server name. From SDSF, enter / to open the System Command Extension window, then enter the START command. If you have restored z/OS Connect from a later version, then you must specify the --clean option when starting a server.

If you have multiple IBM z/OS Connect Servers that share a started task procedure JCL, use the JOBNAME parameter on the START command to assign a unique JOBNAME to each address space. For example,

/S BAQSTRT,JOBNAME=jobname,PARMS='<serverName> [--clean]'

For more information, see A launch icon to indicate a link opens a new tab or window. Starting a system task from a console in the z/OS MVS System Commands documentation.

Note: The z/OS Connect Server server.xml file is only read once upon server startup. Changes to the server configuration file can be gathered by issuing the MVS system command MODIFY REFRESH. For more information on the MODIFY command, for zosConnect-2.0 feature see The MODIFY command zosConnect-2.0 and for zosConnect-3.0 feature, see The MODIFY command zosConnect-3.0.

Stopping an IBM z/OS Connect Server

To stop the server started procedure, enter the following command.

/P <JOB NAME>

Where <JOB NAME> is either the value of the JOBNAME parameter that is specified on the START command or, if that was not specified, then the name of the started task procedure JCL, for example, BAQSTRT.

Note: Liberty's default behavior is to open an ephemeral command listener port at startup, but this port is not needed by the IBM z/OS Connect Server, so z/OS Connect closes this port at startup. unless it is defined in bootstrap.properties.

For more information, see in the A launch icon to indicate a link opens a new tab or window. Specifying Liberty bootstrap properties in the WebSphere® Application Server for Liberty documentation.