Creating a z/OS Connect (OpenAPI 2) server

Use the zosconnect command to create a IBM z/OS Connect server.

Before you begin

To use the zosconnect command, you must be a IBM z/OS Connect administrator with access to the OMVS shell.

Before you create a IBM z/OS Connect server, ensure that the shared directory is available. For more information, see Creating the IBM z/OS Connect shared directory.

For step-by-step examples of creating a server and connecting it to a System of Record (SoR), see:

About this task

This task shows you how to use the default template to create a IBM z/OS Connect server. Templates are a Liberty feature that you can use when you create a server. Other service providers can supply their own templates to enable a quicker start with their functions. For more information, see Creating Liberty servers from custom configurations in the WebSphere® Application Server Liberty documentation.
Note: The file permissions on the server are controlled by setting the _BPX_BATCH_UMASK STDENV variable. For more information, see _BPX_BATCH_UMASK environment variables in the z/OS UNIX System Service documentation. IBM z/OS Connect server does not use the umask settings in /etc/profile and user’s .profile files.

Procedure

  1. Optional: Set the WLP_USER_DIR environment variable to the location where you want your server instances and user features to be stored. For example, /var/myservers. If you do not set this value, the default, /var/zosconnect will be used.

    You can specify the WLP_USER_DIR environment variable in the shell environment. This variable must be an absolute path.

  2. Run the zosconnect command with the create option.
    Use the following syntax:
    zosconnect create <server name> --template=<template name>

    For example, to create a server named server1 with the default IBM z/OS Connect template, type the command:

    zosconnect create server1 --template=zosconnect:default
    To create a server for the z/OS application to call REST APIs, you can use the specific template for API requester as in the following command:
    zosconnect create myserver --template=zosconnect:apiRequester

    For more information about server template options, see Supplied server templates in the Reference section.

    Note: You must add the same WLP_USER_DIR environment variable to the started task procedure:
    //STDENV *
    WLP_USER_DIR=/var/myservers
    For more information about the started task procedure, see Starting and stopping IBM z/OS Connect.

    For more information about variables and options, see Specifying environment variables and JVM options

Results

A IBM z/OS Connect server is created in the <WLP_USER_DIR>/servers directory with a server.xml configuration file that defines the IBM z/OS Connect feature and the default location of the API archive files, API requester archives, service archives and policy rules. The shared resources and the server definitions are also located in this directory when servers are running.
The following table shows the directory structure and contents when a server is created:
Table 1. Directory paths and contents
Path Contents
<WLP_USER_DIR>/servers Server instances. One subdirectory per server instance, each created by using the create option of the zosconnect command.
<WLP_USER_DIR>/extension The location where user features are installed.

Specifying environment variables and JVM options

Learn how to specify environment variables and JVM options.

Further information can be found in the performance topic: Threads, Java heap, MEMLIMIT, REGION.

Specifying optional environment variables

To specify optional environment variables you can use either of these methods:
  • Specify the STDENV variables in line, as shown in the sample started task procedure provided in <hlq>.SBAQSAMP(BAQSTRT).
  • 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.

Specifying JVM options

To specify JVM options, you must use the JVM_OPTIONS STDENV variable. If you need to specify multiple JVM options which 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 above, or store only your JVM options in a z/OS UNIX file. For example, create a z/OS UNIX EBCDIC file 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. For more information, see https://www.ibm.com/support/knowledgecenter/en/SSYKE2_8.0.0/com.ibm.java.zos.80.doc/diag/appendixes/cmdline/Xoptionsfile.html?cp=SS7K4U_liberty in the WebSphere Application Server for z/OS Liberty documentation.