Building a CICS bundle, application, application binding, or platform

You can automate the build of CICS projects, including CICS bundle projects, application projects, application binding projects, and platform projects by writing a build script that calls the CICS build toolkit.

Before you begin

CICS build toolkit needs write access to the source projects as it might modify them as part of the build process. Make sure that you use a temporary copy of the source projects that can be discarded after the build completes. For more information about preparation, see Preparing to use the CICS build toolkit.

If you are building Java projects from source, you need to know the target CICS release and have any additional Java library dependencies available. Alternatively, you can copy built versions of those Java projects, for example .jar .wab .eba or .ear files, into the CICS bundle root directory before you run the CICS build toolkit.

About this task

Use this procedure after you develop your applications and before you deploy your applications as part of a continuous delivery model. Run cicsbt as part of your build automation. Alternatively, run cicsbt at the shell on UNIX or Linux®, or cicsbt.bat at the command prompt on Windows.

Procedure

  1. Specify the --input option to indicate the location of the CICS projects and any referenced projects to be built.
  2. Specify the --build option to indicate which CICS bundle projects, application projects, application binding projects, and platform projects to build from the source location.

    When you build an application binding project, the CICS build toolkit looks for associated applications and platforms in the input directory. If an associated application is found, it is also built. If no associated applications or platforms are found, the build completes with warnings.

  3. Specify the --output option to indicate the output directory.
  4. Optional: To build CICS projects that reference Java projects, specify a target platform by using the --target option. It is not necessary to build Java projects if they are already built and included in the CICS bundle root directory.
    There are several ways to specify a target platform:
    1. Specify a built-in target that corresponds to the lowest version of CICS that your application runs on. You can view a list of available built-in targets by specifying --target with no arguments.
    2. Provide the path to an Eclipse .target file created by CICS Explorer® or Eclipse. Ensure that the user that runs the CICS build toolkit has access to all libraries and directories that are referenced by the .target file.
  5. Optional: To use an alternative character set for your built artifacts, specify the --encoding option.

    Some CICS bundle artifacts must be in the character set that is specified by LOCALCCSID CICS SIT parameter. CICS build toolkit uses character set cp037 by default.

Results

The CICS projects and any referenced projects are built in the output directory within subdirectories that follow the naming convention symbolic.name_version, for example, com.ibm.cics.test.bundle_1.0.0.

Example

This example shows an output directory where only applications and bundles are built, with no associated bindings: 
/output/dir/
    applications/
        my.application_1.0.0
        my.other.application_1.0.0
    bundles/
        my.application.bundle_1.0.0
This example shows an output directory where a binding that is associated with the platform testplatform is built. Application my.application_1.0.0 and bundle my.application.bundle_1.0.0 are also built, but are not associated with the binding: 
/output/dir/
    applications/
        my.application_1.0.0
    bundles/
        my.application.bundle_1.0.0
    testplatform/
        applications/
            my.other.application_1.0.0
        bindings/
            my.other.application.test.binding_1.0.0
        bundles/
            my.other.application.bundle_1.0.0
            my.other.application.another.bundle_1.0.0

The output directory that is created by the CICS build toolkit has the same structure as the platform home directory (PLATHOME). For more information about the platform home directory structure, see Platform directory structure in z/OS UNIX.

This example shows a CICS build toolkit call that builds the CICS application binding my.application.binding(1.0.1) and any associated applications that are found in the input directory: 
cicsbt --input my/source/dir/* \
       --build my.application.binding(1.0.1) \
       --output /my/output/dir
To use this example on Windows, enter all parameters on the same line as the CICS build toolkit call. Paths that contain spaces must be within quotation marks.

What to do next

If your built projects contain variables, you must resolve the variables before they are installed into CICS. For more information about variable substitution, see Resolving variables in a CICS bundle.

After you run the CICS build toolkit, use your build script to copy the built CICS projects to an artifact repository or a staging location on zFS, ready for deployment.
Note: If the artifacts are transferred to zFS by FTP, you must make the transfers in binary mode to ensure that their contents are preserved.