Environment variables in STDENV and BIPENVS

You must set environment variables according to the task that you want to run. The values in the following sections are examples only.

The JCL and the console listener program drive shell scripts. When you submit the JCL jobs, the shell scripts are run under BPXBATCH, and the JCL job passes in an environment file that sets the environment variables. For JCL, the environment file is referred to as STDENV, and for the console listener program, the environment file is referred to as BIPENVS. For more information, see Passing environment variables to BPXBATCH.

You can put all the environment variables in one ENVFILE member or split them up into separate environment files. For example, you can have one member to specify the connection parameters, one member for build details, and one member for each integration server Docker instance for server port allocation.

The resources that you need to run IBM® z/OS® Container Extensions (zCX) need to be available on the z/OS UNIX System Services file system. The resources must be readable by the user ID under which the JCL or started task runs.

The values in the following sections are examples only.

Values for each zCX instance

Set the following values from the IBM z/OS Container Extensions (zCX) instance that you provision, as described in Provisioning an IBM z/OS Container Extensions (zCX) instance.

ZCX_IPADDR=9.20.2.2 - The IP address of the zCX instance to use
ZCX_PORT=8022 - The SSH port of the zCX instance to use. Defaults to 8022 if unset. Not required for BIPXISCM, BIPXPUT, or BIPXGET if you use server ssh access. For more information, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).
ZCX_USER=zcxuser - The user ID under which to access the zCX instance. Not required for BIPXISCM, BIPXPUT, or BIPXGET if you use server ssh access. For more information, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).
ZCX_SSH_KEY=/u/aceadmin/.ssh/id_rsa - The SSH key to be used to access the zCX instance as ZCX_USER. Not required for BIPXISCM, BIPXPUT, or BIPXGET if you use server ssh access. For more information, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).

Values for building the Docker image

Set the following values before you submit the JCL job BIPXBLD.

ACE_DOWNLOAD_PACKAGE_DIR=/u/aceadmin. The directory that holds the downloaded IBM App Connect Enterprise Linux® on IBM Z package.
ACE_DOWNLOAD_PACKAGE_NAME=ace-aceserver1-s390x.tar.Z. The name of the downloaded IBM App Connect Enterprise Linux on IBM Z package.
ACE_DOCKER_IMAGE_BAR_DIR=/u/aceadmin/bars. This environment variable is optional. If it is set along with ACE_DOCKER_IMAGE_BAR_NAME, build processing includes the BAR file in the built Docker image to be made available when the integration server Docker container is run.
ACE_DOCKER_IMAGE_BAR_NAME=zcx.bar . This environment variable is optional. If it is set along with ACE_DOCKER_IMAGE_BAR_DIR, build processing includes the BAR file in the built Docker image to be made available when the integration server Docker container is run.
ACE_DOCKER_IMAGE_YAML_DIR=/u/aceadmin. This environment variable is optional. If it is set along with ACE_DOCKER_IMAGE_YAML_NAME, the integration server Docker container that uses this image uses this directory to find its server.conf.yaml configuration file.
ACE_DOCKER_IMAGE_YAML_NAME=server.conf.yaml. This environment variable is optional. If it is set along with ACE_DOCKER_IMAGE_YAML_DIR, the integration server Docker container that uses this image uses this file as its server.conf.yaml configuration file.
ACE_IMAGE=ace_jenkins_2020-06-15_09:59:01.957539. The name of the Docker image to be built.
ACE_TAG=testing. The tag of the Docker image to be built. The default value is latest.
SERVER_ACCESS_SSH_PUBLIC_KEY=/u/aceadmin/.ssh/aceserver1_rsa.pub. This environment variable is optional. The public key of the private/public key pair used to provide direct access to the integration server Docker container. For more information about ssh access, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).
If you want to include the IBM MQ Client in the Docker image to be made available when the integration server Docker container is run, you must set the environment variables ACE_DOCKER_IMAGE_MQCLIENT_TAR_DIR, and ACE_DOCKER_IMAGE_MQCLIENT_TAR_NAME:
ACE_DOCKER_IMAGE_MQCLIENT_TAR_DIR=/u/aceadmin/tars. This environment variable is optional. If you set it, you must also set ACE_DOCKER_IMAGE_MQCLIENT_TAR_NAME.
ACE_DOCKER_IMAGE_MQCLIENT_TAR_NAME=9.2.0.0-IBM-MQC-UbuntuLinuxS390X.tar.gz. This environment variable is optional. If you set it, you must also set ACE_DOCKER_IMAGE_MQCLIENT_TAR_DIR.

Values for loading a Docker image from a .tar archive by submitting the JCL job BIPXDLI

ACE_DOCKER_IMAGE_TAR_DIR=/u/aceadmin. The directory that contains the .tar archive file to be loaded as a Docker image. Ensure that the image to be loaded was saved by repository/tag, so that when the image is loaded, it has a repository and tag to set as ACE_IMAGE/ACE_TAG.
ACE_DOCKER_IMAGE_TAR_NAME=ace-s390x.tar. The name of the .tar archive file to be loaded as a Docker image. Ensure that the image to be loaded was saved by repository/tag, so that when the image is loaded, it has a repository and tag to set as ACE_IMAGE/ACE_TAG.

Values for starting an integration server

ACE_IMAGE=ali.zcx. The name of the Docker image to be used to run the integration server Docker container.
ACE_TAG=latest. The tag of the Docker image to be used to run the integration server Docker container. The default value is latest.
SERVER_NAME=ace1. The name of the integration server. The default value is ace1.
REST_PORT=port. The number of the port to be used as the integration server's REST administration port. The default value is 7600. If you do not want to expose a REST administration port, set this value to 0. The value must be unique for everything that runs in the zCX instance.
HTTP_PORT=port. The port number for the integration server's HTTP listener. The default value is 7800. If you do not want to expose an HTTP port, set this value to 0. The value must be unique for everything that runs in the zCX instance.
HTTPS_PORT=port . The port number for the integration server's HTTPS listener. The default value is 7843. If you do not want to expose an HTTPS port, set this value to 0. The value must be unique for everything that runs in the zCX instance. Default is 7843.
SERVER_REUSE=yes/no. Valid values are yes and no. The default value is no. You can set SERVER_REUSE to yes to allow processing to restart or reattach to an existing integration server container or start a new one. If you restart an integration server, the original input settings are used even if they were changed. If SERVER_REUSE is set to yes, the console listener does not attempt to remove the stopped integration server Docker container when the started task ends.
SERVER_REUSE=yes
When you run BIPXIS or the console listener, it checks whether an instance of the integration server container exists. One of the following events takes place:
- If the integration server exists and is running, its logs are reattached to the new task.
- If the integration server exists and is stopped, it is started and attached to the new task.
- If the integration server does not exist, an attempt is made to start a new integration server container.
When the console listener ends, it stops the integration server container but does not delete it.

If you run BIPXIS or the console listener again, the integration server is restarted.

SERVER_REUSE=no

When you run BIPXIS or the console listener, an attempt is made to start a new integration server container.

When the console listener ends, it stops the integration server container and deletes it.

The integration server is not restarted if you run BIPXIS or the console listener.
SERVER_ACCESS_SSH_PORT=port. The number of the port to be used as the integration server docker container's SSH port. The value must be unique for every docker container that runs on the zCX instance. For more information, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).
SERVER_RUN_OVERRIDE= -p 7604:7604 -p 7804:7804 -p 7844:7843 -e LICENSE=accept. If you build your own image by using your own processing methods, specify the parameters, including port mappings to use when you issue the docker run. For more information, see Building your own Docker image.

Integration server ports

If you do not want to expose a port for HTTP_PORT, HTTPS_PORT, or REST_PORT, set the value to 0.

These port numbers are for the ports that are made available outside of the integration server Docker container. For the HTTP and admin ports, to ensure that the internal port numbers that are reported in messages and statistics match these external port numbers, their internal port settings are overridden when you start the integration server. Do not set these port settings in server.conf.yaml because they are overridden. You cannot override the HTTPS port in this way. If you need to match internal and external port numbers for HTTPS, use the default value.

Running IBM App Connect Enterprise commands by submitting the JCL job BIPXISCM

SERVER_NAME. The name of the integration server. The default value is ace1.
SERVER_ACCESS_SSH_PORT=port. This environment variable is optional. The number of the port to be used as the integration server docker container's SSH port. The value must be unique for every docker container that runs on the zCX instance.
SERVER_ACCESS_SSH_KEY=/u/aceadmin/.ssh/aceserver1_rsa. This environment variable is optional. The private key of the private/public key pair used to provide direct access to the integration server Docker container.

For more information about ssh access, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).

ACE_DEBUG

Specify this option only if you are directed to do so by your IBM service representative.

Environment variables that are addressed by STDENV and BIPENVS:

Environment variable name	BIPXBLD	BIPXDLI	BIPXIS	BIPXISCM	BIPXISTP	BIPXDSP	BIPXPUT	BIPXGET	BIPXDBG	Console listener
ZCX_SSH_KEY Optional for some tasks. For more information, see Values for each zCX instance.	Required	Required	Required	Optional	Required	Required	Optional	Optional	Required	Required
ZCX_PORTdefault=8022 Optional for some tasks. For more information, see Values for each zCX instance.	Required	Required	Required	Optional	Required	Required	Optional	Optional	Required	Required
ZCX_USER Optional for some tasks. For more information, see Values for each zCX instance.	Required	Required	Required	Optional	Required	Required	Optional	Optional	Required	Required
ZCX_IPADDR	Required	Required	Required	Required	Required	Required	Required	Required	Required	Required
ACE_DOWNLOAD_PACKAGE_DIR	Required
ACE_DOWNLOAD_PACKAGE_NAME	Required
ACE_DOCKER_IMAGE_BAR_DIR	Optional. If you set this variable, you must also set ACE_DOCKER_IMAGE_BAR_NAME.
ACE_DOCKER_IMAGE_BAR_NAME	Optional. If you set this variable, you must also set ACE_DOCKER_IMAGE_BAR_DIR.
ACE_DOCKER_IMAGE_YAML_DIR	Optional. If you set this variable, you must also set ACE_DOCKER_IMAGE_YAML_NAME.
ACE_DOCKER_IMAGE_YAML_NAME	Optional. If you set this variable, you must also set ACE_DOCKER_IMAGE_YAML_DIR.
ACE_IMAGE	Required		Required							Required
ACE_TAG. The default value is `latest`	Optional		Optional							Optional
ACE_DOCKER_IMAGE_TAR_DIR		Required
ACE_DOCKER_IMAGE_TAR_NAME		Required
SERVER_NAME The default value is ace1.			Optional	Optional	Optional			Optional	Optional	Optional
REST_PORT. The default value is 7600. Optional for some tasks. For more information, see Integration server ports.			Optional							Optional
HTTP_PORT. The default value is 7800. For more information, see Integration server ports.			Optional							Optional
HTTPS_PORT. The default value is 7843. For more information, see Integration server ports.			Optional							Optional
SERVER_ACCESS_SSH_PORT Optional for some tasks. For more information, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).			Optional	Optional			Optional	Optional		Optional
SERVER_ACCESS_SSH_PUBLIC_KEY Optional for some tasks. For more information, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).	Optional
SERVER_ACCESS_SSH_KEY Optional for some tasks. For more information, see Configuring access to Integration Servers running in IBM z/OS Container Extensions (zCX).				Optional			Optional	Optional		Optional
ACE_SCRIPTS_DIR										Required
SERVER_REUSE. The default value is no.			Optional							Optional
ACE_DOCKER_IMAGE_MQCLIENT_TAR_DIR	Optional. If you set this variable, you must also set ACE_DOCKER_IMAGE_MQCLIENT_TAR_NAME.
ACE_DOCKER_IMAGE_MQCLIENT_TAR_NAME	Optional. If you set this variable, you must also set ACE_DOCKER_IMAGE_MQCLIENT_TAR_DIR.
SERVER_RUN_OVERRIDE			Optional							Optional
ACE_DEBUG