Installation and Customization Guide

SCLM Developer Toolkit
Installation and Customization Guide

Version 2.1

Document Number SC31-6970-00

5655-R37


Note!

Before using this information and the product it supports, be sure to read the general information under Notices.

First Edition (December 2006)

This edition applies to IBM SCLM Developer Toolkit, Version 2 Release 1, Program Number 5655-R37 and to any subsequent releases until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product.

The IBM SCLM Developer Toolkit web site is at

http://www.ibm.com/software/awdtools/sclmsuite/devtoolkit/

The latest edition of this document is always available from the web site.

(C) Copyright International Business Machines Corporation 2005, 2006. All rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.


Contents

  • Figures

  • About this Document
  • Who should use this document
  • Changes from the previous edition
  • Where to find more information
  • Publications
  • Softcopy publications
  • IBM Systems Center publications
  • Installation overview
  • TCP/IP considerations
  • SMP/E installation
  • Batch job considerations
  • Separate SCLM installation

  • Part 1. Installing SCLM Developer Toolkit

  • Chapter 1. Installing and customizing SCLM Developer Toolkit on z/OS
  • Step 1: Check z/OS software requirements
  • Step 2: Configuration considerations
  • Step 3: Run the setup JCL
  • Step 4: Customize the SCLM Developer Toolkit configuration files
  • Customize the ISPF configuration file
  • Customize the TRANSLATE configuration file
  • Override settings in the TRANSLATE.conf file
  • Step 5a: Configure the SCLM Developer Toolkit HTTP Server
  • HTTP server configuration file customization
  • HTTP server environment file customization
  • HTTP server JCL/STARTED TASK customization
  • Step 5b: Configure Remote Systems Explorer
  • Customizing the RSE Environment file
  • Customizing the RSE environment setup script
  • Activating the RSE Environment file
  • Step 6: Configure long/short name table VSAM file
  • Step 7: Install and customize Ant
  • Step 8a: Run the IVP to check correct HTTP installation and customization
  • Testing connection to the HTTP server
  • Step 8b: Run the IVP to check correct RSE installation and customization
  • Chapter 2. Installing the Eclipse-based client onto the PC
  • Preparing for installation
  • Media requirements
  • Hardware and software requirements
  • Installing SCLM Developer Toolkit
  • Step 1. Install from CD or electronic image
  • Step 2. Install SCLM Developer Toolkit

  • Part 2. Customizing SCLM Developer Toolkit

  • Chapter 3. SCLM customization for the SCLM administrator
  • Language translators for JAVA/J2EE support
  • JAVA/J2EE build summary
  • JAVA/J2EE build objects generated
  • SCLM language definitions
  • SCLM types
  • SCLM member formats
  • JAVA/J2EE Ant XML build skeletons
  • Mapping J2EE projects to SCLM
  • Recommendations for mapping J2EE projects to SCLM
  • SCLM Developer Toolkit deployment
  • WebSphere Application Server (WAS) deployment
  • SCLM to Unix System Services deployment
  • Secure deployment
  • Other deployment options
  • ASCII or EBCDIC storage options
  • ASCII/EBCDIC language translators
  • $GLOBAL member
  • SITE and project-specific options
  • Example of using combinations of the TRANSLATE.conf overrides
  • Example of using combinations of the BIDIPROP overrides
  • Chapter 4. SCLM security
  • Build/Promote/Deploy security flag and process flow
  • Security rules and surrogate user ID
  • Build rule format
  • Promote rule format
  • Deploy rule format
  • SAF/RACF BUILD, PROMOTE, DEPLOY, and PROFILE rules
  • Chapter 5. CRON-initiated Builds and Promotes
  • STEPLIB and PATH requirements
  • CRON Build job execution
  • CRON Build job samples

  • Part 3. Appendixes

  • Appendix A. SCLM overview
  • SCLM Concepts
  • File naming
  • Type
  • Language
  • SCLM properties
  • SCLM project structure
  • ARCHDEF
  • JAVA/J2EE concepts
  • Appendix B. Long/short name translation table
  • Technical summary of the SCLM Translate program
  • Single long/short name record processing
  • FINDLONG Processing
  • FINDSHORT Processing
  • TRANSLATE Processing
  • Multiple long/short name record processing
  • IMPORT processing
  • MIGRATE processing
  • Appendix C. Messages and codes

  • Bibliography

  • Notices
  • Trademarks
  • Glossary

  • Index

  • Figures

    1. Publications
    2. IBM Systems Center Publications
    3. Sample ISPF.conf
    4. User of TRANSLATE.conf keywords
    5. httpd.conf customization
    6. httpd.env customization
    7. Pass and exec directives
    8. RSE Environment file customization
    9. Sample rsed.envars
    10. Sample Long/Short Translate VSAM file JCL
    11. HTTP server logon prompt
    12. Host installation and customization welcome screen
    13. An example of validation responses (part 1)
    14. An example of validation responses (part 2)
    15. An example of validation responses (part 3)
    16. Server Connection successful message
    17. change directory command
    18. IVP validation responses
    19. Required hardware
    20. Required operating systems
    21. Sample translators
    22. Sample Jar application (JAR) ARCHDEF
    23. J2EE Build script JAR sample
    24. Sample Jar application (JAR) ARCHDEF
    25. Sample Web application (WAR) ARCHDEF
    26. Sample EJB Application (EJB) ARCHDEF
    27. Sample EAR Application (EAR) ARCHDEF
    28. J2EE Ant build script
    29. Customer-defined variables
    30. J2EE Build script JAR sample
    31. J2EE Build script WAR sample
    32. J2EE Build script EJB sample
    33. J2EE Build script EAR sample
    34. Multiple types
    35. SCLM build hierarchy
    36. SCLM Language Translators and ASCII/EBCDIC
    37. $GLOBAL variables
    38. Sample SITE specific SCLM project setting
    39. Sample PROJECT specific SCLM project setting
    40. SITE/Project options
    41. Sample CRON members
    42. Sample CRON Build Exec
    43. Sample Build parameter file
    44. Multiple types
    45. Sample REXX for Translate module invocation

    About this Document

    This document contains the configuration procedure for the IBM(R) SCLM Developer Toolkit product, which combines standard z/OS(R) installation procedures with z/OS UNIX(R) System Services and IBM z/OS HTTP server configuration. It also describes the Eclipse client installation on Windows(R).

    From here on, the following names are used in this manual:

    Sometimes, "IBM SCLM Developer Toolkit" is shortened to "Developer Toolkit" or "SCLMDT".


    Who should use this document

    Part 1 of this document is written for system programmers who are installing, configuring and administering the IBM SCLM Developer Toolkit product. Readers should be familiar with the z/OS UNIX System Services environment (z/OS UNIX System Services file system) structure, security software (for example, Resource Access Control Facility (RACF(R))) profiles needed to support z/OS UNIX System Services, started tasks (or the equivalent for the installed security product), and, if used, the HTTP server.

    Additionally a chapter is provided in Part 1 for users who are installing the client component on Windows.

    Part 2 of this document contains information for the administrator of any SCLM projects that will be used with the SCLM Developer Toolkit. This includes projects that are using the Java(R) and z/OS UNIX System Services component languages, as well as traditional SCLM projects. These administrators also need to be familiar with the z/OS UNIX System Services environment and z/OS UNIX System Services file system structures, REXX Script, and the Java Compiler and SCLM project and language definitions.


    Changes from the previous edition

    Second edition

    The changes are marked with revision bars.


    Where to find more information

    Where necessary, this document references information in other books, using shortened versions of the book title. For complete titles and order numbers of the books for all products that are part of z/OS, see the z/OS Information Roadmap. Direct your request for copies of any IBM publication to your IBM representative or to the IBM branch office serving your locality.

    There is also a (US) toll-free customer support number (1-800-879-2755) available Monday through Friday from 6:30 a.m. through 5:00 p.m. Mountain Time. You can use this number to:

    Publications


    Figure 1. Publications

    Short Title Used in This Document Title of Publication Order Number
    HTTP Server Guide HTTP Server Planning, Installing and Using SC31-8690
    WebSphere Developer for System z Host Configuration Guide WebSphere Developer for System z Host Configuration Guide SC31-6930
    Communications Server for z/OS V1R2 TCP/IP Implementation Guide Communications Server for z/OS V1R2 TCP/IP Implementation Guide SG24-5227
    z/OS UNIX System Services Planning z/OS UNIX System Services Planning GA22-7800
    z/OS UNIX System Services Messages z/OS UNIX System Services Messages and Codes GA22-7807
    z/OS UNIX System Services Commands z/OS UNIX System Services Command Reference GA22-7802
    IBM Ported Tools for z/OS User' Guide IBM Ported Tools for z/OS User' Guide SA22-7985
    SCLM Project Manager's Guide z/OS ISPF Software Configuration and Library Manager Project Manager's and Developer's Guide SC34-4817
    SCLM Developer Toolkit: Program Directory (GI10-3352-00) SCLM Developer Toolkit: Program Directory GI10-3352
    SCLM Reference z/OS ISPF Software Configuration and Library Manager Reference SC34-4818

    Softcopy publications

    The z/OS library is available on the z/OS Collection Kit, SK2T-6700. This softcopy collection contains a set of z/OS and related unlicensed product books. The CD-ROM collection includes the IBM Library Reader(TM), a program that customers can use to read the softcopy books.

    Softcopy z/OS publications are also available for Web browsing. PDF versions of the z/OS publications for viewing or printing using Adobe Acrobat Reader are available at this URL:

    Select "Library".

    You can also find WDz, Eclipse, and SCLM Advanced Edition information at the following URLs:

    IBM Systems Center publications

    IBM Systems Center produces Redbooks(TM) that can be helpful in setting up and using z/OS UNIX System Services. You can order these publications through the usual channels, or you can view them with a Web browser from this URL:

    http://www.redbooks.ibm.com
    

    These books have not been subjected to any formal review nor have they been checked for technical accuracy, but they represent current product understanding (at the time of their publication) and provide valuable information about a wide range of z/OS topics. You must order them separately. A selected list of these books follows:

    Figure 2. IBM Systems Center Publications

    Title of Publication Order Number Comments
    P/390, R/390, S/390 Integrated Server: OS/390 New User's Cookbook SG24-4757-01 Despite the title, it is oriented toward the system programmer, and describes considerations for the z/OS UNIX System Services environment.
    Debugging UNIX System Services, Lotus Domino, Novell Network Services SG24-5613-00 Provides an overview of the z/OS UNIX System Services environment along with tips and suggestions for setup and problem analysis.
    OS/390 e-business Infrastructure: IBM HTTP Server V5.1 for OS/390 SG24-5603-00 Provides an overview of Web servers in general with specific details for the OS/390(R) server along with hints and tips for setup and customization.
    ABCs of z/OS System Programming Vol 9 SG24-6989-00 Describes UNIX System Services for system programmers.
    e-business Enablement Cookbook for OS/390 Volumes 1, 2, and 3 SG24-5664-00
    SG24-5981-00
    SG24-5980-00


    Installation overview

    This manual contains the installation procedure for all components of SCLM Developer Toolkit. There are two installation components to SCLM Developer Toolkit; the z/OS host component and the client component. The client component is an Eclipse plug-in that can be installed into an existing Eclipse, installed with the Eclipse that is shipped with the standalone SCLM Developer Toolkit installation, or if WebSphere Developer for System z has been installed, the plug-in is an installable part of that installation. Eclipse is an open extensible Integrated Development Environment (IDE), which will be referred through this document as the Eclipse IDE.

    The installation procedure is a combination of standard z/OS installation procedures, z/OS UNIX System Services file set up, HTTP server configuration, and (if installed as a plug-in with WebSphere Developer for System z) RSE configuration.

    The manual is structured into the following chapters:

    The appendixes, starting at page Appendix A, "SCLM overview"

    For a high-level description of SCLM and JAVA/J2EE concepts, see Appendix A, SCLM overview.


    TCP/IP considerations

    When you are setting up the SCLM Developer Toolkit server, you also need to consider your site's installation of TCP/IP. SCLM Developer Toolkit can use an HTTP server or, if it is installed as a plug-in in WebSphere Developer for System z, via an RSE connection.

    If SCLM Developer Toolkit is configured to use an HTTP server then the TCPIP.DATA file needs to be available. The z/OS UNIX System Services Planning guide documents where the system finds this file.

    However, if you use another method of defining the location of this file (such as the System Resolver), you need to add a //SYSTCPD DD card to your SCLM Developer Toolkit server job. A TCP port needs to be available and it is recommended to reserve the port number. To understand more about the System Resolver and TCPIP.DATA, see the following publications:


    SMP/E installation

    This manual does not cover the implementation aspects of SCLM Developer Toolkit. Rather, it is intended to guide the installer through a successful configuration of the product. The manual assumes that the System Modification Program/Extended (SMP/E) installation of SCLM Developer Toolkit is complete. The SMP/E instructions for SCLM Developer Toolkit are in the IBM SCLM Developer Toolkit Program Directory. Before you begin the SCLM Developer Toolkit installation, note that the following actions were recommended for the SMP/E installation:

    These recommendations conform with those specified in the z/OS UNIX System Services Planning guide. See the section "Deciding How to Mount Your Root z/OS UNIX System Services file system for Execution" for full details.

    Upon successful completion of the SMP/E installation follow the directions in subsequent chapters to complete the installation and customization on z/OS, and to install the Eclipse-based client on to the PC.


    Batch job considerations

    SCLM Developer Toolkit uses SDSF to retrieve job completion status and job output if requested. As not all customers are JES2 or have SDSF, additional support has been put into SCLM Developer Toolkit to use the OUTPUT command. As shipped with z/OS the OUTPUT command only lets you retrieve job output that begins with the logged on user ID. If you want to use the OUTPUT facility fully then the supplied TSO/E exit IKJEFF53 may need to be modified to allow users to retrieve job output they own that does not begin with their user ID. For more information about this exit see the z/OS TSO/E Customization Guide.


    Separate SCLM installation

    This manual does not cover the implementation and loading of the SCLM product.


    Part 1. Installing SCLM Developer Toolkit

    Partial Table-of-Contents

  • Chapter 1. Installing and customizing SCLM Developer Toolkit on z/OS
  • Step 1: Check z/OS software requirements
  • Step 2: Configuration considerations
  • Step 3: Run the setup JCL
  • Step 4: Customize the SCLM Developer Toolkit configuration files
  • Customize the ISPF configuration file
  • Customize the TRANSLATE configuration file
  • Example of the TRANSLATE configuration file
  • Override settings in the TRANSLATE.conf file
  • Step 5a: Configure the SCLM Developer Toolkit HTTP Server
  • HTTP server configuration file customization
  • HTTP server environment file customization
  • HTTP server JCL/STARTED TASK customization
  • Customizing an existing HTTP server for SCLM support
  • Start the SCLM Developer Toolkit HTTP server
  • Turning trace on the HTTP server
  • Step 5b: Configure Remote Systems Explorer
  • Customizing the RSE Environment file
  • Customizing the RSE environment setup script
  • Activating the RSE Environment file
  • Step 6: Configure long/short name table VSAM file
  • Step 7: Install and customize Ant
  • Step 8a: Run the IVP to check correct HTTP installation and customization
  • Testing connection to the HTTP server
  • Step 8b: Run the IVP to check correct RSE installation and customization
  • Chapter 2. Installing the Eclipse-based client onto the PC
  • Preparing for installation
  • Media requirements
  • Hardware and software requirements
  • Prerequisites for SCLM Developer Toolkit
  • Installing SCLM Developer Toolkit
  • Step 1. Install from CD or electronic image
  • Step 2. Install SCLM Developer Toolkit

  • Chapter 1. Installing and customizing SCLM Developer Toolkit on z/OS

    This chapter provides a list of the tasks required to install SCLM Developer Toolkit on your host z/OS system and the tasks involved in installing the Eclipse client plug-in of the SCLM Developer Toolkit.

    It contains the following steps:

    These steps must be implemented by the z/OS Systems Programmer.

    The SCLM Developer Toolkit can connect to the z/OS host either by using an HTTP server or by using an RSE (Remote Systems Explorer) connection. If SCLM Developer Toolkit is running under WebSphere Developer for System z then the communication mechanism is RSE. Configuring SCLM Developer Toolkit for RSE communication is covered in Step 5b: Configure Remote Systems Explorer. If SCLM Developer Toolkit is running under any other installation of Eclipse, such as Rational(R) Application Developer (RAD), then the communication mechanism is HTTP. This is described in Step 5a: Configure the SCLM Developer Toolkit HTTP Server.

    For additional information about configuring SCLM Developer Toolkit for specific SCLM projects see Chapter 3, SCLM customization for the SCLM administrator. This chapter contains additional customization for:


    Step 1: Check z/OS software requirements

    To successfully install SCLM Developer Toolkit, the following system requirements must be in place at your installation:


    Step 2: Configuration considerations

    Consider the following points before you configure your system.

    1. Each user that uses the SCLM Developer Toolkit must have an RACF OMVS segment (or equivalent) defined that specifies a valid non-zero uid, home directory, and shell command.

      If this is not specified then the user will not be able to log on to the SCLM Developer Toolkit through the Eclipse IDE.

    2. Set MAXPROCUSER in BPXPRMxx parmlib member to a minimum of 50. This can be checked and set dynamically (until the next IPL) with the following commands (as described in z/OS MVS System Commands SA22-7627):
            DISPLAY OMVS,O
            SETOMVS MAXPROCUSER=50.
       
      
      Setting a value that is too low can cause SCLM translations and possibly other activities to fail.
    3. It is recommended to have the BWB* modules reside in a data set that is part of the LINKLIST. Alternatively this data set may be added:

    Step 3: Run the setup JCL

    1. Customize and run BWBINST1, which resides in the SBWBSAMP data set.

      Follow the customization instructions within the member.

      This job performs the following tasks:

      The recommended base directory for the configuration files is /etc/SCLMDT. The part of the directory up to SCLMDT must exist before running this job.

      SCLM Developer Toolkit users will require read and write access to the WORKAREA and LOGS directories. By default users would require read and write access to /var/SCLMDT/WORKAREA and /var/SCLMDT/LOGS. The WORKAREA is used for transfer of files, ASCII/EBCDIC conversions, and for JAVA/J2EE builds.

      Temporary directories of format /var/SCLMDT/WORKAREA/userid/* are created during the use of Developer Toolkit. The following directories may be created under a directory of the user's user ID in the WORKAREA directory depending on the type of functions they are performing:

    Note:

    SCLM Developer Toolkit removes any temporary files that it creates in the WORKAREA directory. Saying that, temporary output is sometimes left over, for example, if there is a communication error while processing. For this reason, we recommend that you clear out the WORKAREA and LOGS directories from time to time.

    To do this, use the following commands in OMVS:

    cd /var/SCLMDT/WORKAREA
    rm -r *
    

    Where /var/SCLMDT/WORKAREA depends on where you create the WORKAREA directory.

    This removes all entries and the same process can be used on the LOGS directory.


    Step 4: Customize the SCLM Developer Toolkit configuration files

    The files ISPF.conf and TRANSLATE.conf reside at the default directory location /etc/SCLMDT/CONFIG and may require further customization.

    Customize the ISPF configuration file

    In order for SCLM Developer Toolkit to run ISPF and SCLM services, a valid ISPF environment has to be established. The ISPF configuration contains the required allocations for SCLM Developer Toolkit to run an ISPF environment under the covers.

    You must customize the ISPF configuration file ISPF.conf that resides in the CONFIG directory to host site requirements for ISPF data set allocation. The provided sample ISPF.conf has instructions to complete customization and enables the user site to:

    The allocations for each of the ISPF DDs must be specified on a single line with each data set separated by a comma. Comment lines can be added by beginning the line with an asterisk (*). See the sample ISPF.conf below for an example configuration.

    Figure 3. Sample ISPF.conf


    * REQUIRED:
    * Below is the minimum requirements for ISPF allocation.
    * Change the default ISPF data set names below to match your host site.
    * Add additional dsn concatenations on same line and separate by comma.
    * Order of data sets listed is search order in concatenation.
    * The sclmdt loadlib data set is required to be added to the ISPLLIB
    * concatenation to access the JAVA/J2EE SCLM Language translators.
    * Change BWB.SBWBLOAD to the appropriate data set where the
    * BWBxxx load modules reside.
    *
    * The libraries beginning BZZ.* are for the Breeze product and are
    * included to show how multiple data sets are added to the concatenations.
    * These should be removed if the Breeze product is not installed.
     
    sysproc=ISP.SISPCLIB,BZZ.SBZZCLIB
    ispmlib=ISP.SISPMENU
    isptlib=ISP.SISPTENU
    ispplib=ISP.SISPPENU
    ispslib=BZZ.SBZZSENU,ISP.SISPSLIB
    ispllib=BWB.SBWBLOAD,BZZ.SBZZLOAD
    

    Customize the TRANSLATE configuration file

    Review the TRANSLATE configuration file TRANSLATE.conf that resides in the CONFIG directory. Follow the instructions contained within the sample if different ASCII/EBCDIC conversion codepages are required, besides the default of ASCII=ISO8859-1 and EBCDIC=IBM-1047.

    The TRANSLATE.conf file provides keywords to determine how code is stored within SCLM. The provision to specify language definitions where files are binary transferred and stored, and also whether text based source remains in ASCII format rather than the default translation from ASCII to EBCDIC.

    Additionally SCLM language definitions control whether longname files are converted to suitable valid short hostnames to store in SCLM. This long to short name mapping is controlled by the SCLM long/short name translate file.

    Note: Default language definitions have been provided as a guide to use for determining long to shortname conversions, and/or BINARY transferred language definitions.

    The following keywords are valid within the TRANSLATE.conf file:

    Keyword
    Description

    CODEPAGE
    Determines the ASCII and EBCDIC codepages to use in translation

    Format:

    There must be a CODEPAGE keyword for both ASCII and EBCDIC for SCLM Developer Toolkit to determine how to convert files being transferred.

    TRANLANG
    Determines which SCLM language types require no ASCII/EBCDIC translation to the host (file will be binary transferred).

    If files were ASCII text they will remain in that ASCII codepage.

    Format:

    In the above examples dummy Language Translators would be set up in SCLM for these languages. See Chapter 3, SCLM customization for the SCLM administrator for more information about SCLM Language translators.

    LONGLANG
    Determines which SCLM language types require longname to shortname conversion. Longname to shortname translation implies the longname file on the Client (including directory package structure) will be mapped to a valid host member name of 8 characters and stored in SCLM using this translated host short name.

    Format:

    If the SCLM Language is not specified in the LONGLANG keyword then the Client file is assumed to already be in host short name format (8 characters or less) and is stored as is.

    Note: Comment lines can be added by beginning the line with an asterisk (*).

    Figure 4. User of TRANSLATE.conf keywords


    *
    * -------------------- CODEPAGE SECTION ----------------------
    *
    CODEPAGE ASCII = ISO8859-1
    CODEPAGE EBCDIC = IBM-1047
    *
    * ------------ ASCII to EBCDIC TRANSLATION SECTION -----------
    *
    TRANLANG JAVABIN
    TRANLANG J2EEBIN
    TRANLANG J2EEOBJ
    TRANLANG TEXTBIN
    TRANLANG BINARY
    TRANLANG DOC
    TRANLANG XLS
    *
    * ------------ LONG/SHORT NAME TRANSLATION SECTION -----------
    *
    LONGLANG JAVA
    LONGLANG J2EEPART
    LONGLANG JAVABIN
    LONGLANG J2EEBIN
    LONGLANG J2EEOBJ
    LONGLANG DOC
    LONGLANG XLS
    *
    

    See Example of the TRANSLATE configuration file for a configuration including the Figure 4.

    Example of the TRANSLATE configuration file

    As stated above, the TRANSLATE configuration files control a number of things. Two of these are:

    To show how these two settings could be used to help in deciding how to initially set up this config file here is an example.

    Example

    You have a number of Word documents that you want to store in SCLM. In this case files of this type cannot be edited on the mainframe. So there is no point in translating them to EBCDIC and they should just be stored in ASCII.

    Override settings in the TRANSLATE.conf file

    It is possible to override values set in the TRANSLATE.conf file at a SITE and SCLM Project level. For an explanation of this feature, see SITE and project-specific options.


    Step 5a: Configure the SCLM Developer Toolkit HTTP Server

    This section describes the setup and customization of an HTTP server if you are planning on configuring SCLM Developer Toolkit to communicate with the z/OS host via an HTTP server. An HTTP server is used when the SCLM Developer Toolkit is not installed with WebSphere Developer for System z, but under any other installation of Eclipse, such as Rational Application Developer (RAD).

    Alternatively if you plan to use SCLM Developer Toolkit with WebSphere Developer for System z, then RSE (Remote Systems Explorer) is used as the communication mechanism. This is covered in Step 5b: Configure Remote Systems Explorer.

    It is recommended that the HTTP server is a dedicated web server to support this interface, though optionally you may incorporate the required SCLM/HTTP configuration directives into an existing HTTP server. See Customizing an existing HTTP server for SCLM support.

    By default the SCLM/HTTP server is configured to use port 80 though you may choose another suitable dedicated port during customization (1024 or higher as port numbers lower than this are reserved for internal systems use).

    If you change the default port number it must be changed in the HTTP server JCL.

    The sample setup requires the end user to supply a valid z/OS user ID and password when accessing the host system using this interface.

    Note: For additional information about configuring IBM HTTP web servers, review these IBM manuals:

    The following sections outline the steps for customizing the supplied samples and starting the HTTP server.

    By default the HTTP server configuration file and the environment file reside in the SCLM Developer Toolkit CONFIG directory. Optionally these files may be copied to another user directory or existing server configuration and environment files. In all cases the HTTP server started task must be customized to reflect the appropriate directory.

    HTTP server configuration file customization

    Customize the sample HTTP configuration file httpd.conf (which resides in the CONFIG directory specified by setup job BWBINST1) by following the instructions in the configuration file for the changes that are needed. The following directives need to be reviewed:

    Figure 5. httpd.conf customization

    Directive Description of change
    Port Leave as port 80 or change to a valid port number as specified in the HTTP server JCL. It is recommended to reserve the port number.
    Protection Change SCLMDTWB to the name of the HTTP server job. For information about using the Protection directive, see the HTTP Server Guide.
    PidFile
    AccessLog
    ErrorLog
    Change /var/SCLMDT to the appropriate path if a different path to the default was selected.
    Pass and Exec Directives Change /var/SCLMDT to the appropriate path if a different path to the default was selected.

    Change /usr/lpp/SCLMDT to the appropriate path of the bin installation directory if a different path to the default was selected.

    Non-standard codepage translation in SCLM Developer Toolkit If users require different ASCII/EBCDIC codepage translation other than standard default (IBM-1047/ISO8859-1) the following parameters must be coded in the httpd.conf file for the HTTP server:

      DefaultFsCp ebcdic-codepage
      DefaultNetCp ascii-codepage
    

    For example, for Japanese translation the required codepages would be:

      DefaultFsCp IBM-939
      DefaultNetCp IBM-932C
    

    HTTP server environment file customization

    Customize the sample HTTP environment variables file httpd.env (which resides in the installation directory specified by install job BWBINST1) by following the instructions in the environment file for the changes that are needed.

    Figure 6. httpd.env customization

    Directive Description of change
    PATH Ensure the PATH directive has the correct Java path directory
    CGI_DTWORK This directive determines the WORKAREA directory path that is used for temporary files. The default is:
      CGI_DTWORK=/var/SCLMDT
    
    CGI_DTCONF This directive determines the CONFIG directory path where the configuration files reside. The default is:
      CGI_DTCONF=/etc/SCLMDT
    
    CGI_TRANTABLE This directive determines the name of the translate table used in short to long name translation. This VSAM file is discussed in Step 6: Configure long/short name table VSAM file. The default is:
      CGI_TRANTABLE=BWB.LSTRANS.FILE
    

    HTTP server JCL/STARTED TASK customization

    Before the HTTP server can be submitted, the following tasks must be performed.

    1. Copy the sample batch job BWBSRVR from the installed sample library, SBWBSAMP, to a JCL Library or PROCLIB data set and customize to your site-specific standards by following the instructions in the sample.
    2. Issue the CAPS OFF command to ensure that case sensitive values do not get changed to upper case.
    3. It is recommended to make this HTTP server job a started task, but it can also be run as a standalone job to test the HTTP server JCL.
    4. If performing foreground Java builds it is recommended to use a region size of 512M in the HTTP server job.
    5. RACF considerations:

    6. The default port to be used is 80. If you change this to a specific dedicated port you must also change the port number in the httpd.conf configuration file to match the port number in the started task JCL.
    7. If the BWB* modules do not reside in the LINKLIST then edit the STEPLIB to specify the load library containing these modules. By default these are in the SBWBLOAD library.
    8. Module BWBTSOW must reside in an APF authorized load library.
    9. Ensure a REXX/370 runtime environment on the host exists or alternatively use the REXX/370 Alternate Library.

    Note: The user ID assigned to the HTTP server must have READ authority to the BPX.SERVER resource in the FACILITY class. If this resource is not defined, UID 0 is required.

    Customizing an existing HTTP server for SCLM support

    Follow the instructions below if you optionally choose to incorporate the SCLM Developer Toolkit support into an existing HTTP server.

    Add the following pass/exec directives in the httpd.conf configuration file:

    Figure 7. Pass and exec directives


    Pass    /J2EEPUT/               /var/SCLMDT/WORKAREA/*
    Pass    /DWGET/                 /var/SCLMDT/WORKAREA/*
    Pass    /DWTRANSFER/            /var/SCLMDT/WORKAREA/*
    Pass    /BWBIVP.html            /usr/lpp/SCLMDT/bin/BWBIVP.html
    Pass    /SCLMDW.html            /usr/lpp/SCLMDT/bin/SCLMDW.html
    Pass    /DT*                    /usr/lpp/SCLMDT/bin/DT*
    Exec    /BWBCALL                /usr/lpp/SCLMDT/bin/BWBCALL
    Exec    /BWBIVP.cgi             /usr/lpp/SCLMDT/bin/BWBIVP.cgi
    

    Note: Tailoring this example as follows:

    Start the SCLM Developer Toolkit HTTP server

    Start the web server by submitting the job or if it is a started task procedure enter the following command from the z/OS console:

      Start server_proc_name
    

    where server_proc_name is the STC name.

    (Ensure the procedure is a member in a PROCLIB data set.)

    Check the HTTP server successfully initialized

    The server JOBLOG should contain the following messages:

      IMW0234I Starting.. httpd
      IMW0235I Server is ready.
    

    Turning trace on the HTTP server

    To turn tracing on the HTTP server, modify the server JCL PARM statement to include one of the tracing levels. For example:

    PARM=('ENVAR("_CEE_ENVFILE=//DD:ENV")/-vv -r //DD:CONF -B -p 80')
    

    The level of tracing provided is:
    -v trace for first level
    -vv trace for second level
    -mtv for third level
    -debug for maximum tracing.

    For more information about tracing see the "HTTP Server Planning, Installing and Using" manual.

    Note: Trace has an impact on performance and should only be carried out if advised by an IBM representative.


    Step 5b: Configure Remote Systems Explorer

    This section describes the setup and customization of Remote Systems Explorer (RSE) that can be used by the client to access SCLM on a z/OS host. RSE is used when the SCLM Developer Toolkit is installed with WebSphere Developer for System z.

    If you are not using SCLM Developer Toolkit with WebSphere Developer for System z, then the mechanism used to communicate with the z/OS host is HTTP. This is described in Step 5a: Configure the SCLM Developer Toolkit HTTP Server.

    The installation and configuration of the RSE component of WebSphere Developer for System z is covered in the WebSphere Developer for System z Host Configuration Guide. This section guides you through the steps to add SCLM Developer Toolkit specific settings to enable it to work through an RSE connection.

    You need to know the customization directory of the RSE component of WebSphere Developer for System z before you begin as modifications will need to be made to files contained there.

    Customizing the RSE Environment file

    Locate the rsed.envvars file that your RSE connection will be using, by default in /usr/lpp/wd4z/rse/lib. At the bottom of the file, copy in the SCLM Developer Toolkit member containing the RSE environment variables. This member is BWBRSED and can be found in the installed sample library SBWBSAMP.

    Customize the variables by following the instructions in the table below:

    Figure 8. RSE Environment file customization

    Directive Description of change
    CGI_DTCONF Determines the base path of the /CONFIG directory (configuration files reside here). The default is:
    CGI_DTCONF=/etc/SCLMDT
    
    CGI_DTWORK Determines the base path of the /WORKAREA directory (workarea files reside here). The default is:
    CGI_DTWORK=/var/SCLMDT
    
    CGI_TRANTABLE Determines the name of the translate table used in short to long name translation. This VSAM file is discussed in Step 6: Configure long/short name table VSAM file. The default is:
    CGI_TRANTABLE=BWB.LSTRANS.FILE
    
    STEPLIB Determines where the BWB load modules are run from. The STEPLIB should be CURRENT if BWB modules are in linklist or the name of the data set into which you have installed the SCLM Developer Toolkit load modules (BWB*). The default is:
    BWB.SBWBLOAD
    
    Additional data sets are separated by a colon (:).
    _SCLM_DT Determines the path of the /bin installation directory. The default is:
    /usr/lpp/SCLMDT
    
    _SCLM_J2EEPUT Determines the path of the /WORKAREA directory for put requests. The default is:
    $CGI_DTWORK/WORKAREA
    
    Using the default value for CGI_DTWORK this resolves to /var/SCLMDT/WORKAREA.
    _SCLM_DWGET Determines the path of the /WORKAREA directory for get requests. The default is:
    $CGI_DTWORK/WORKAREA
    
    Using the default value for CGI_DTWORK this resolves to /var/SCLMDT/WORKAREA.
    _SCLM_DWTRANSFER Determines the path of the /WORKAREA directory for transfer requests. The default is:
    $CGI_DTWORK/WORKAREA
    
    Using the default value for CGI_DTWORK this resolves to /var/SCLMDT/WORKAREA.
    _SCLM_BASE Determines the path of the /WORKAREA directory for all other requests. The default is:
    $CGI_DTWORK/WORKAREA
    
    Using the default value for CGI_DTWORK this resolves to /var/SCLMDT/WORKAREA.
    _SCLM_BWBCALL Determines the location of BWBCALL and BWBCALLR scripts. The default is:
    $_SCLM_DT/BWBCALL
    
    Using the default value for _SCLM_DT this resolves to /usr/lpp/SCLMDT/bin/BWBCALL.

    The PATH=$_SCLM_DT/bin:$PATH statement adds the SCLM Developer Toolkit /bin directory to the search path.

    Comment lines can be added by beginning the line with a hash (#). See the sample rsed.envvars additions below.

    Figure 9. Sample rsed.envars


    #ANT_HOME=/u/antdirectory/Ant/apache-Ant.1.6.2
    CGI_DTCONF=/etc/SCLMDT
    CGI_DTWORK=/var/SCLMDT
    CGI_TRANTABLE=BWB.LSTRANS.FILE
    STEPLIB=BWB.SBWBLOAD:BZZ.SBZZLOAD
    #STEPLIB=CURRENT
    _SCLM_DT=/usr/lpp/SCLMDT
    _SCLM_J2EEPUT=$CGI_DTWORK/WORKAREA
    _SCLM_DWGET=$CGI_DTWORK/WORKAREA
    _SCLM_DWTRANSFER=$CGI_DTWORK/WORKAREA
    _SCLM_BASE=$CGI_DTWORK/WORKAREA
    _SCLM_BWBCALL=$_SCLM_DT/BWBCALL
    PATH=$_SCLM_DT/bin:$PATH
    

    Customizing the RSE environment setup script

    RSE itself has two connection methods, directly via a daemon or using a script started by REXEC. If you use the REXEC connection method, changes have to be made to setup.env.zseries, the script that sets up the RSE environment variables. This script resides in the same location as rsed.envvars (default /usr/lpp/wd4z/rse/lib). At the bottom of the file, copy in the SCLMDT member containing the RSE environment export statements. This member is BWBREXEC and can be found in the installed sample library SBWBSAMP.

    Activating the RSE Environment file

    In order to pick up the SCLM Developer Toolkit variables it is recommended to:


    Step 6: Configure long/short name table VSAM file

    SCLM Developer Toolkit provides the ability to store long name files (which are files with names greater than 8 characters or in mixed case) into SCLM. This is achieved through the use of a VSAM file that contains the mapping of the long file name to the 8 character member name used in SCLM.

    For versions previous to z/OS V1.8, this facility is provided via a base ISPF/SCLM PTF that addresses APAR OA11426. This PTF must be applied before the long to short name translation can be used. If you are on z/OS V1.8 (or higher), you do not need this PTF.

    If this installation of SCLM Developer Toolkit is going to use this facility then the PTF providing the facility must be installed and the VSAM file containing the mapping from long to short name can then be allocated. To do so, the following sample JCL, found in member FLM02LST in the ISPF sample library ISP.SISPSAMP, can be modified and submitted.

    Users need update authority on this file.

    Figure 10. Sample Long/Short Translate VSAM file JCL


    //FLM02LST JOB <-JOB PARAMETERS->
    //* ----------------------------------------------------------------
    //* ALLOCATION OF LONGNAME/SHORTNAME VSAM FILE
    //*
    //* THIS JOB ALLOCATES THE LONGNAME TO SHORTNAME TRANSLATE FILE.
    //* THIS TRANSLATE FILE IS REQUIRED FOR THE FOLLOWING SCLM SUITE
    //* PRODUCTS - SCLM DEVELOPER TOOLKIT AND SCLM ADMIN TOOLKIT.
    //* THE ONE TRANSLATE FILE IS RECOMMENDED TO BE DEFINED AND USED
    //* FOR ALL SCLM PROJECTS.
    //*
    //*
    //*  CAUTION: THIS IS NEITHER A JCL PROCEDURE NOR A COMPLETE JOB.
    //*  BEFORE USING THIS SAMPLE, YOU WILL HAVE TO MAKE THE
    //*  FOLLOWING MODIFICATIONS:
    //*
    //*  1) ADD THE JOB PARAMETERS TO MEET YOUR SYSTEM REQUIREMENTS
    //*
    //*  2) CHANGE ALL REFERENCES OF HLQ.LSTRANS.FILE BELOW TO YOUR
    //*     REQUIRED NAMING CONVENTION FOR THE SCLM TRANSLATE FILE.
    //*
    //*  3) MODIFY CYLINDERS (PRIMARY SECONDARY)
    //*
    //*  4) SPECIFY THE VOLUME VVVVVV ON WHICH IT WILL BE ALLOCATED
    //* ----------------------------------------------------------------
    
    //IDCAMS   EXEC PGM=IDCAMS
    //SYSPRINT DD  SYSOUT=*
    //SYSIN DD *
      DELETE HLQ.LSTRANS.FILE
      SET MAXCC=0
      DEFINE CLUSTER(NAME(HLQ.LSTRANS.FILE)                       -
                    RECSZ(58  2048)                               -
                    INDEXED                                       -
                    CYLINDERS(1 1)                                -
                    VOLUMES(VVVVVV)                               -
                    SHR(3,3)                                      -
                    KEYS (8 0))                                   -
      DATA(NAME(HLQ.LSTRANS.FILE.DATA))                           -
      INDEX(NAME(HLQ.LSTRANS.FILE.INDEX))
     
        /* DEFINE ALTERNATE INDEX WITH NONUNIQUE KEYS -> ESDS     */
      DEFINE ALTERNATEINDEX (                                   -
                     NAME(HLQ.LSTRANS.FILE.AIX)                   -
                     RELATE(HLQ.LSTRANS.FILE)                     -
                     RECORDSIZE(58  2048)                         -
                     CYLINDERS(1 1)                               -
                     VOLUMES(VVVVVV)                              -
                     KEYS(50 8)                                   -
                     NONUNIQUEKEY                                 -
                     UPGRADE )                                    -
               DATA (                                             -
                     NAME(HLQ.LSTRANS.FILE.AIX.DATA) )            -
               INDEX (                                            -
                     NAME(HLQ.LSTRANS.FILE.AIX.INDEX) )
    //*
    //* ----------------------------------------------------------------
    //*  NOTE: THE FOLLOWING STEP WILL GET RC=4 DUE TO THE ALTERNATE
    //*        INDEX BEING EMPTY. THE MESSAGES RETURNED ARE AS FOLLOWS.
    //*
    //*        IDC3300I  ERROR OPENING HLQ.LSTRANS.FILE
    //*        IDC3351I ** VSAM OPEN RETURN CODE IS 100
    //*        IDC0005I NUMBER OF RECORDS PROCESSED WAS 1
    //*        IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 4
    //*
    //* ----------------------------------------------------------------
    //IDCAM2   EXEC PGM=IDCAMS
    //SYSPRINT DD  SYSOUT=*
    //INITREC  DD *
    INITREC1
    /*
    //SYSIN DD *
        REPRO INFILE(INITREC) -
              OUTDATA
    

    For more information about the Long to Short name translation process see Appendix B, Long/short name translation table.


    Step 7: Install and customize Ant

    This step is required if you plan to use the JAVA/J2EE build support in SCLM.

    Ant is freely available and can be downloaded from http://ant.apache.org/. Ant text files and scripts are distributed in ASCII format and require an ASCII/EBCDIC translation to run on z/OS in UNIX System Services. A sample translate script has been supplied in the SCLM Developer Toolkit SBWBSAMP library in sample member BWBTRANT and a sample copy job to copy the translate script into the appropriate Ant directory in sample member BWBCPANT. Follow the steps below to implement Ant on z/OS:

    1. Download the latest Ant compressed file into the z/OS UNIX System Services file system and unzip into the appropriate directory. (If the file is a TAR file, use the TAR extract command tar -xf filename, or if it is a compressed file, use the JAR extract command jar -xf filename).
    2. Customize the install copy member BWBCPANT to include the Ant installation directory and run the job to copy the translate script into the directory (review the instructions contained within the sample member BWBCPANT).
    3. To check successful translation, using whatever tool you use to list files in z/OS Unix Systems Services, such as OMVS or ISHELL, locate a text file within the ANT directory such as the file README and browse this using your preferred method of browsing, such as OBROWSE in OMVS. If the file is readable then the translation was successful.
    4. Change file permissions for all files under the Ant installation directory to enable all users to read and execute.

      For example

       cd /u/antdirectory/Ant/apache-Ant.1.6.2; chmod -R 755 *
      
    5. Before using Ant, set the z/OS UNIX System Services environment variables JAVA_HOME and ANT_HOME.
      1. JAVA_HOME is required to point to the Java home directory, for example:
        JAVA_HOME=/usr/lpp/java/IBM/J1.4
        
      2. ANT_HOME is required to point to the Ant installation directory, for example:
        ANT_HOME=/u/antdirectory/Ant/apache-Ant.1.6.2
        
    6. Ant will look for an Ant configuration file in the directory /etc, so we recommend creating an Ant configuration file named ant.conf and adding the variables JAVA_HOME and ANT_HOME. That is, in file /etc/ant.conf set:
      JAVA_HOME=/usr/lpp/java/IBM/J1.4
      ANT_HOME=/u/antdirectory/Ant/apache-Ant.1.6.2
      
      A sample ant.conf file is provided in member BWBANTC in the installed sample library SBWBSAMP. This can be copied to the /etc/ directory as file ant.conf and the JAVA_HOME and ANT_HOME variables modified to the correct value for your installation.

    Note: The above directory paths are only sample directory paths. Ensure the correct directory paths are used.

    These variables may also be set in other ways:

    To test that the Ant initialization has been successful:

    1. Add the Ant and Java bin directories to the environment variable PATH. This PATH variable may be added to your .profile or you can enter the following PATH definition below at the UNIX System Services command line.

      Example:

        export PATH=/u/antdirectory/Ant/apache-Ant.1.6.2/bin:/usr/lpp/java/IBM/J1.4/bin:$PATH
      
    2. Run Ant to display the version.

      Example:

        Ant -version
      

      This displays the Ant version if Ant is successfully installed.

    Note: Setting the PATH statement in this way is necessary for testing, not for operational use. During normal SCLM Developer Toolkit build processing, the ANT_HOME and JAVA_HOME environment variables are set dynamically from the values set in the $GLOBAL member. For a detailed description of the $GLOBAL member parameters, see $GLOBAL member.


    Step 8a: Run the IVP to check correct HTTP installation and customization

    This Installation Verification Process (IVP) applies if you have configured the HTTP server. The HTTP server must be running and the IVP pass/exec directives configured in the httpd.conf file for successful verification processing.

    From a browser, type the location URL address:

      http://hostname:portnumber/BWBIVP.html
    

    Where:

    hostname
    Is the TCP/IP host name the HTTP server is running on.

    port number
    Is the port used in the job and the httpd.conf file (default port 80).

    If the HTTP server is running you will be prompted for a valid TSO user ID and password for the system the web server is started on (Figure 11).

    Figure 11. HTTP server logon prompt

    This is the workload analysis table.

    Once you have entered your TSO user ID and password the browser will initially display the html welcome screen (Figure 12).

    Figure 12. Host installation and customization welcome screen

    This is the Host installation and customization welcome screen.

    If you fail to connect then check that:

    Once you receive the welcome screen, continue with the IVP, which checks and validates your installation and customization process.

    The sample screens (Figure 13 through to Figure 15) give an example of possible validation responses.

    Figure 13. An example of validation responses (part 1)

    This is an example of validation responses (part 1).

    Figure 14. An example of validation responses (part 2)

    This is an example of validation responses (part 2).

    Figure 15. An example of validation responses (part 3)

    This is an example of validation responses (part 3).

    Testing connection to the HTTP server

    At any time the server connection can be tested without running the full IVP check.

    From a browser, type the location URL address:

      http://hostname:portnumber/SCLMDW.html
    

    Where:

    hostname
    Is the TCP/IP host name the HTTP server is running on.

    port number
    Is the port used in the job and the httpd.conf file (default port 80).

    You are prompted for a valid user ID and password for the system the web server is started on.

    The browser then displays the message shown in Figure 16.

    Figure 16. Server Connection successful message

    This is the Server Connection successful message.


    Step 8b: Run the IVP to check correct RSE installation and customization

    This Installation Verification Process (IVP) applies if you have configured the RSE connection. This connection is used when Developer Toolkit is installed as a WD/z plug-in. A z/OS RSE connection must be configured and running. The SCLM Developer Toolkit directives must be configured in the rsed.envvars file for successful verification processing. For more information about this, see Step 5b: Configure Remote Systems Explorer.

    Follow these steps to invoke the SCLM Developer Toolkit IVP:

    1. In WebSphere Developer for System z, ensure the Remote Systems Explorer perspective is open. For the z/OS connection that will be connecting to SCLM, right click on the USS Shells node and then select Launch Shell.
    2. In the command line in the shell, change directory to the installation directory of the SCLM Developer Toolkit z/OS UNIX System Services file system modules. By default this will be /usr/lpp/SCLMDT/bin. To do this use the cd command as shown in Figure 17.

      Figure 17. change directory command

      This is the change directory command

    3. In the command line enter BWBIVPR.cgi to run the IVP script. The script will run in the shell and will give you a number of validation responses as it steps through the different tests in the IVP. Once complete you can scroll back up to examine all of the responses to ensure that the IVP worked successfully.
    4. An example of the IVP validation responses is shown in Figure 18.

      Figure 18. IVP validation responses

      These are the IVP validation responses.

     


    Chapter 2. Installing the Eclipse-based client onto the PC

    If you have already installed WebSphere Developer for System z onto your PC, you do not need to install the client because the SCLM Developer Toolkit plug-in must already be installed. However if you have not installed SCLM Developer Toolkit as part of your WebSphere Developer for System z installation, then you can install just the SCLM Developer Toolkit plug-in into an existing Eclipse by following the instructions contained in this chapter.

    Note: SCLM Developer Toolkit only supports the IBM Java Runtime Environment (JRE) Version 1.5.

    Furthermore, if you want to install the SCLM Developer Toolkit into a different Eclipse other than WebSphere Developer for System z, you must carry out the installation steps that follow.


    Preparing for installation

    To prepare for installation, you need to meet the following media requirements and hardware and software requirements.

    Media requirements

    To install SCLM Developer Toolkit onto your workstation, you must have access to the SCLM Developer Toolkit installation CD or electronic images. Once you have downloaded the SCLM Developer Toolkit images from Passport Advantage and expanded them, you will see the DISK1 directory that is used to install SCLM Developer Toolkit onto your workstation.

    Hardware and software requirements

    The following information gives hardware and software requirements for SCLM Developer Toolkit.

    Prerequisites for SCLM Developer Toolkit

    IBM SCLM Developer Toolkit is a licensed program to support users who want to store and build distributed code in SCLM on z/OS, as well as work with traditional z/OS artefacts through an IDE.

    Hardware requirements

    SCLM Developer Toolkit requires the hardware as shown in Figure 19.

    Figure 19. Required hardware

    Processor Intel Pentium III 800 MHz or higher is required
    Memory 768MB RAM is required, though 1GB RAM or higher is recommended
    Disk space 250 MB minimum disk space is required to install SCLM Developer Toolkit. This is assuming you are installing the complete Eclipse installation along with the SCLM Developer Toolkit plug-in. You will be installing SCLMDT using IBM Installation manager so you will need an additional 120 MB minimum disk space to install this (if you do not already have it installed). Installation also requires an additional 700MB of temporary space for product update installation files and other files.
    Monitor and video card A VGA display of 1024x768 or higher is required

    Supported operating systems

    SCLM Developer Toolkit requires any of the following operating systems:

    Figure 20. Required operating systems

    Windows XP Professional with Service Pack 1 or higher
    Windows 2000 Professional or Server or Advanced Server with Service Pack 3 or higher
    Windows Server 2003 Standard or Enterprise Edition

    Installing SCLM Developer Toolkit

    Install SCLM Developer Toolkit using IBM Installation Manager. If you do not have IBM Installation Manager, it is provided on the SCLM Developer Toolkit CD.

    The following steps work you through installing the IBM Installation Manager and then installing the SCLM Developer Toolkit.

    Step 1. Install from CD or electronic image

    You can install SCLM Developer Toolkit directly from CD or electronic image. Once the electronic image has been extracted, the image will contain the same contents as the CD. Installation is performed by IBM Installation Manager and this is installed if required.

    Step 2. Install SCLM Developer Toolkit

    From the Install Packages screen of the IBM Installation Manager:

    1. On the Install panel, select the SCLM Developer Toolkit V2.1 from the list of available offerings if it is not already selected and click Next.
    2. On the License panel, accept the license agreement and click Next.
    3. On the Location panel:
      1. Specify the Shared Resources Directory: Assuming you have not installed any other offerings yet using the IBM Installation Manager, specify the directory you want to use as your Common Component Directory.

        Note: This directory is used by all offerings installed by the Installation Manager, and is the directory where the majority of files (for example, all Eclipse features and plug-ins) are installed, so make sure you have plenty of disk space here. Once this location has been specified you will not be able to change it on the Location panel for other offerings you install later.

        Click Next.

      2. Specify the Installation Directory: On the next screen specify the installation directory where you want to install the offering.

        Note: Only certain files specific to this offering are installed to this location. The majority of the offering (for example, all of the Eclipse plug-ins and features) is installed to the Common Component Directory which was specified previously.

        Click Next.

      3. Extend an Existing Eclipse Installation: On the next screen you can choose to install the SCLM Developer Toolkit plug-in into an existing Eclipse. By default SCLM Developer Toolkit is installed into its own installation of Eclipse. If you want to add the plug-in to an existing Eclipse specify the installation location of the Eclipse IDE.

        Note: SCLM Developer Toolkit only supports the IBM Java Runtime Environment (JRE) Version 1.5. Installing into an existing Eclipse environment that uses an unsupported JRE will cause problems running SCLM Developer Toolkit.

        Click Next.

    4. On the Features panel:
      1. Select required languages: Select any offered language packs you want to install. Click Next.
      2. Select additional features: On the next screen select any additional features that are offered that you may require. The SCLM Developer Toolkit is the default feature and is selected by default.
    5. Review the Summary panel and click Install to begin the install.
    6. When the Installation completed panel appears, click Finish. This exits the Installation Manager.

    IBM SCLM Developer Toolkit is installed.

    To launch the workbench from Start > All Programs > IBM SCLM Developer Toolkit > IBM SCLM Developer Toolkit > IBM SCLM Developer Toolkit.


    Part 2. Customizing SCLM Developer Toolkit

    Partial Table-of-Contents

  • Chapter 3. SCLM customization for the SCLM administrator
  • Language translators for JAVA/J2EE support
  • JAVA/J2EE build summary
  • JAVA/J2EE build objects generated
  • SCLM language definitions
  • SCLM types
  • SCLM member formats
  • $GLOBAL
  • J2EE ARCHDEF
  • J2EE Ant build script
  • JAVA/J2EE Ant XML build skeletons
  • Mapping J2EE projects to SCLM
  • Recommendations for mapping J2EE projects to SCLM
  • SCLM Developer Toolkit deployment
  • WebSphere Application Server (WAS) deployment
  • SCLM to Unix System Services deployment
  • Secure deployment
  • Public key authentication
  • Other deployment options
  • ASCII or EBCDIC storage options
  • ASCII/EBCDIC language translators
  • $GLOBAL member
  • SITE and project-specific options
  • Options Definition
  • Example of using combinations of the TRANSLATE.conf overrides
  • Example of using combinations of the BIDIPROP overrides
  • Chapter 4. SCLM security
  • Build/Promote/Deploy security flag and process flow
  • Security rules and surrogate user ID
  • Build rule format
  • Promote rule format
  • Deploy rule format
  • SAF/RACF BUILD, PROMOTE, DEPLOY, and PROFILE rules
  • Chapter 5. CRON-initiated Builds and Promotes
  • STEPLIB and PATH requirements
  • CRON Build job execution
  • CRON Build job samples

  • Chapter 3. SCLM customization for the SCLM administrator

    This chapter looks at how the SCLM administrator can customize SCLM. It contains the following sections:


    Language translators for JAVA/J2EE support

    SCLM Developer Toolkit requires four new language translators defined in SCLM for JAVA/J2EE support. These language translators are shipped in the SBWBSAMP members as shown below:

    Figure 21. Sample translators



    Sample

    Translator
    Description

    BWBTRANJ
    Sample default member translator. No parsing. Similar to
    SCLM FLM@TEXT. This translator can be customized to create language
    definitions J2EEPART, J2EEBIN, BINARY, and TEXT.

    BWBTRAN1
    Sample Java language translator. LANG=JAVA.

    BWBTRAN2
    Sample JAVA/J2EE language translator incorporating Ant (for multiple Java
    compiles and JAR, WAR, and EAR builds).

    BWBTRAN3
    Sample J2EE language translator for SCLM ARCHDEF J2EE support.
    LANG=J2EEOBJ.

    The SCLM administrator will need to copy these samples, rename if required, and then generate them into the PROJDEFS.LOAD library for each SCLM project where Java support is required. These translators are required to be added/compiled in the Project Definition.

    A sample project definition for JAVA/J2EE projects and host components is provided in sample BWBSCLM.

    The LOADLIB data set containing the BWB* modules must be included in the ISPF ISPLLIB concatenation to access the JAVA/J2EE language translator modules. The ISPLLIB concatenation is customized in the configuration file ISPF.conf.

    SCLM DATASETS for JAVA/J2EE:

    It is recommended to create SCLM target source data sets of RECFM=VB, LRECL=1024 for JAVA/J2EE source being stored in SCLM from the Toolkit client to cater for long record types. The editors on the Eclipse-based client create files of variable record length, and to maintain integrity the Host target data sets in SCLM should also be of RECFM=VB. Using Fixed record length data sets (RECFM=FB) will result in imported members having white spaces appended to end of record.


    JAVA/J2EE build summary

    Here is a summary of the process that occurs for Java and J2EE builds using the supplied translators.

    Note: You can build JAVA/J2EE members or ARCHDEFS directly in TSO/ISPF on the host as well as via the Developer Toolkit Client.

    The ARCHDEF contains the members that make up the JAVA/J2EE project and are a short-name representation of how the project exists in an Eclipse workspace.

    The ARCHDEF itself is built which invokes a pre-build verify language translator (J2EEANT). The translator reads the J2EE build script, which is referenced in the ARCHDEF by the SINC keyword, and overlays the properties specified into the skeleton Ant XML referenced by properties SCLM-ANTXML (A). The build script, when generated by the SCLM Developer Toolkit, is stored in SCLM with a language of J2EEANT (1).

    An ARCHDEF generates Java Classes for Java source identified with the INCLD keyword in the ARCHDEF (2), and each ARCHDEF may also generate a J2EE archive file such as a JAR, WAR, or EAR file. The J2EE object created is dependent on the appropriate build script referenced and use of the ARCHDEF keyword OUT1 (3), (B).

    When the ARCHDEF is built the pre-build verify language translator associated with the build script (in SCLM type J2EEBLD) runs and determines what parts of the ARCHDEF are required to be rebuilt (including nested ARCHDEFs (4) identified through the use of the INCL keyword in the ARCHDEF). Those parts are then copied into the z/OS UNIX System Services file system workarea and Ant compiles and generates the required JAVA/J2EE objects specified by the build script and ARCHDEF. Any external jar or class references that your IDE project needs to resolve are done so from the path defined in the CLASSPATH_JARS property (C).

    SCLM then processes each individual ARCHDEF component running each language translator associated with the component. The Language translator JAVA, associated with Java source, copies the class files created back into SCLM.

    Finally, the ARCHDEF translator determines what J2EE objects have been generated (JAR, WAR, EAR) and copies these parts back into SCLM.

    It is essential to create a separate ARCHDEF for each application component that may make up an enterprise application (EAR). That is, an EAR which contains a WAR which contains an EJB JAR should have an ARCHDEF for the JAR, an ARCHDEF for the WAR with an INCL of the EJB JAR ARCHDEF. The EAR ARCHDEF then should include an INCL of the WAR ARCHDEF.

    Figure 22 shows the corresponding JAR sample.

    Figure 22. Sample Jar application (JAR) ARCHDEF


    *
    * Initially generated on 10/05/2006 by SCLM DT V2
    *
     LKED   J2EEOBJ           * J2EE Build translator
    *
    * Source to include in build
    *
     INCLD AN000002 V2TEST    * com/Angelina.java                          *
     INCLD V2000002 V2TEST    * com/V2Java1.java (2)        *
     INCLD V2000003 V2TEST    * V2InnerClass.java                          *
    *
    * Nested SCLM controlled jars to include                               *
    *
     INCL V2JART1 ARCHDEF     * DateService.jar (4)         *
    *
    * Build script and generated outputs
    *
     SINC   V2JARB1(1) J2EEBLD   * J2EE JAR Build script    *
     OUT1   *       J2EEJAR   * V2TEST.jar (3)              *
     LIST   *       J2EELIST
    

    Figure 23 shows the corresponding JAR script.

    Figure 23. J2EE Build script JAR sample


    <ANTXML>
    <project name="JAVA Project" default="jar" basedir=".">
    <property name="env" environment="env" value="env"/>
    <property name="SCLM_ARCHDEF" value="V2JAR1"/>
    <property name="SCLM_ANTXML" value="BWBJAVAA"/> (A)
    <property name="SCLM_BLDMAP" value="YES"/>
    <property name="JAR_FILE_NAME" value="V2TEST.jar"/> (B)
    <property name="CLASSPATH_JARS" value="/var/SCLMDT/CLASSPATH"/> (C)
    <property name="ENCODING" value="IBM-1047"/>
    </ANTXML>
    

    JAVA/J2EE build objects generated

    The following objects are generated:

    SCLM language definitions

    The sample translators define the following languages:

    Translator
    Description

    J2EEPART
    Language type that specifies a JAVA/J2EE component and defined by sample BWBTRANJ. No particular parsing occurs on build of this language definition. Non-Java source or J2EE components that require ASCII/EBCDIC language conversion may be generically slotted under this language definition if no particular build parsing is required (for example html, xml, .classpath, .project, definition tables). Optionally language definition of TEXT may be used.

    J2EEBIN
    Language type that specifies JAVA/J2EE Binary or ASCII stored component and defined by sample BWBTRANJ. No particular parsing occurs on build of this language definition. JAVA/J2EE binary files and text files that you want to be stored as ASCII may be generically slotted under this language definition if no particular build parsing is required.

    JAVA
    Language type for Java source and defined by sample BWBTRAN1. The Java translator determines what type of build has been issued against Java source.

    Note: This language definition must be assigned to Java programs if you want to store the Java source in EBCDIC on the host (that is, the source may be viewed and edited directly on the host through ISPF). The advantage of defining programs with this language definition is being able to edit and view the source directly on the z/OS host. The disadvantages are that codepage conversions need to take place when migrating or importing projects from the client to the host.

    JAVABIN
    Language type that is similar to Java and used when storing Java source as ASCII in SCLM.

    J2EEANT
    This is the main build translator for JAVA/J2EE builds and this verify translator is invoked when a J2EE ARCHDEF is built. The translator gets invoked because the JAVA/J2EE build script, stored in SCLM type J2EEBLD, is saved in SCLM with a language of J2EEANT. It is then referenced via the SINC keyword in the ARCHDEF.

    This verify translator determines what parts are required to be built (including nested ARCHDEFs) and depending on the build modes copies these parts into the z/OS UNIX System Services WORKAREA directory. A skeleton Ant xml is dynamically customized according to the build script and the parts built in the workarea using Ant. The class files are passed to the JAVA/JAVABIN language translators to store the class files back into SCLM. J2EE objects generated such as a JAR, WAR, or EAR are passed to the ARCHDEF language translator (J2EEOBJ) to be stored back into SCLM.

    J2EEOBJ
    This is the final build translator invoked as part of the ARCHDEF build process. This translator determines what J2EE objects (JAR, WAR, EAR) were previously built in translator J2EEANT and copies these objects into SCLM with the generated short name provided. This translator is referenced by the LKED keyword in the ARCHDEF itself.

    Note: All objects such as JAR, WAR, and EAR have their internal zipped source parts in ASCII to distribute to all platforms.

    SCLM types

    There are a number of SCLM types that need to be created for JAVA/J2EE support. Some of these types are mandatory types and must be created for JAVA/J2EE support to function.

    Type
    Description

    J2EEBLD
    This SCLM Type is required for Java and J2EE build and deploy processes.

    The J2EEBLD type contains:

    Note: Sample Java and J2EE ANTXML scripts are supplied. Generally these scripts require little or no user customization. Site- and user-dependent variables are customized in the J2EEBLD scripts themselves to override default ANTXML variables. (For more information, see JAVA/J2EE Ant XML build skeletons.)

    This contains a $GLOBAL member which is required for both Java and J2EE builds (see $GLOBAL member).

    ARCHDEF
    This contains JAVA/J2EE ARCHDEF members.

    The longname parts in each ARCHDEF member outline the JAVA/J2EE project structure. The ARCHDEF for a given project may be dynamically created from the client when migrating in new projects or updated when adding new parts to an existing project.

    The SCLM ARCHDEF is the primary SCLM file for defining the elements of a JAVA/J2EE project. In regards to JAVA/J2EE applications the ARCHDEF represents how the J2EE application is structured in the Client IDE project workspace.

    The Project file structure of the application is replicated in the ARCHDEF (using the SCLM host short name to map the long name structure). Additional keywords in the ARCHDEF such as LINK, SINC, and OUT1 indicate to SCLM the J2EE nature of this project and source include a JAVA/J2EE build script to facilitate build processing of this project.

    JAVALIST
    This SCLM type is required for the Java build process.

    The JAVALIST type contains listing outputs from Java builds.

    J2EELIST
    This SCLM type is required for the J2EE build process.

    The J2EELIST type contains listing outputs from J2EE builds.

    JAVACLAS
    This SCLM type is required for both Java and J2EE build processes.

    The JAVACLAS type contains output class files from builds associated with the JAVA, J2EEANT language definitions.

    J2EEJAR
    This SCLM type is required for JAVA/J2EE builds (language definition J2EEANT).

    The J2EEJAR type contains JAR output from builds associated with the J2EEANT language definition.

    J2EEWAR
    This SCLM type is required for the J2EE build process.

    The J2EEWAR type contains WAR output from builds associated with the J2EEANT language definition.

    J2EEEAR
    This SCLM type is required for the J2EE build process.

    The J2EEEAR type contains EAR output from builds associated with the J2EEANT language definition.

    <Java/J2EE> types
    A separate SCLM type is required for each JAVA/J2EE project to be stored in SCLM. This is to avoid conflicts in same-named files that occur with JAVA/J2EE projects. For more information about this, see Mapping J2EE projects to SCLM.

    SCLM member formats

    This section describes SCLM member formats:

    $GLOBAL

    The $GLOBAL format is of type J2EEBLD and language J2EEPART. It must use the name $GLOBAL and variables are defined in tagged language format.

    $GLOBAL specifies the default properties for the SCLM project for JAVA/J2EE build processing. This must reside in the SCLM type J2EEBLD.

    For a detailed description of the $GLOBAL member parameters, see $GLOBAL member.

    $GLOBAL sample

    <property name="ANT_BIN" value="/usr/lpp/Ant/apache-Ant-1.6.0/bin/Ant"/>
    <property name="JAVA_BIN" value="/usr/lpp/java/IBM/J1.4/bin"/>
    <property name="CGI_DTCONF" value="/etc/SCLMDT/CONFIG"/>
    <property name="CGI_DTWORK" value="/var/SCLMDT/WORKAREA"/>
    <property name="CLASSPATH_JARS" value="/var/SCLMDT/CLASSPATH"/>
    

    J2EE ARCHDEF

    The J2EE ARCHDEF format is of type ARCHDEF and language ARCHDEF.
    LKED J2EEOBJ
    INCLD SourceFile SourceType
    INCL ArchdefName ArchdefType
    SINC BuildScriptname J2EEBLD
    OUT1 * J2EEOutputObjectType
    LIST * J2EELIST

    The ARCHDEF uses standard SCLM architecture keywords to tell SCLM how to process the build of the ARCHDEF.

    LKED
    Indicates this is a LEC ARCHDEF and gives the language of the ARCHDEF translator to be invoked (for J2EE ARCHDEFs, this is always J2EEOBJ).

    INCLD
    SCLM include of J2EE component. SourceFile is the name of the source member (for example, Java source) that is included in this ARCHDEF. SourceType is the SCLM type that contains the member. In an SCLM Developer Toolkit generated ARCHDEF there will be a comment that gives the full file name of the file as it existed in the project on the workbench.

    INCL
    SCLM include of another nested ARCHDEF, such as the ARCHDEF that contains the manifest for an EJB application.

    SINC
    Source include of the J2EEBLD build script. BuildScriptName is the name of the build script. The source type is always J2EEBLD.

    OUT1
    Indicates the J2EE object type created by this ARCHDEF. The member name is always *. The J2EEOutputObjectType is set to either J2EEEAR, J2EEWAR, or J2EEJAR. The member created will be given a name of the generated shortname for the JAR, WAR, or EAR file.

    LIST
    Summary component listing and audit of the ARCHDEF built. The member name is always *. The source type is always J2EELIST. The member will be given a name of the same value as the ARCHDEF member name.

    J2EE ARCHDEF samples

    This section shows JAR, WAR, EJB, and EAR samples.

    Figure 24. Sample Jar application (JAR) ARCHDEF


    *
    * Initially generated on 10/05/2006 by SCLM DT V2
    *
     LKED   J2EEOBJ           * J2EE Build translator
    *
    * Source to include in build
    *
     INCLD AN000002 V2TEST    * com/Angelina.java                          *
     INCLD V2000002 V2TEST    * com/V2Java1.java                           *
     INCLD V2000003 V2TEST    * V2InnerClass.java                          *
    *
    * Build script and generated outputs
    *
     SINC   V2JARB1 J2EEBLD   * J2EE JAR Build script                     *
     OUT1   *       J2EEJAR   * V2TEST.jar                                *
     LIST   *       J2EELIST
    

    Figure 25. Sample Web application (WAR) ARCHDEF


    *
    * Initially generated on 5 Sep 2006 by SCLM DT V2
    *
     LKED  J2EEOBJ            * J2EE Build translator
    *
    * Source to include in build
    *
     INCLD DA000026 SAMPLE5   * JavaSource/service/dateController.java      *
     INCLD XX000001 SAMPLE5   * .classpath                                  *
     INCLD XX000002 SAMPLE5   * .project                                    *
     INCLD XX000003 SAMPLE5   * .websettings                                *
     INCLD XX000004 SAMPLE5   * .website-config                             *
     INCLD OP000002 SAMPLE5   * WebContent/operations.html                  *
     INCLD MA000001 SAMPLE5   * WebContent/META-INF/MANIFEST.MF             *
     INCLD IB000001 SAMPLE5   * WebContent/WEB-INF/ibm-web-bnd.xmi          *
     INCLD IB000002 SAMPLE5   * WebContent/WEB-INF/ibm-web-ext.xmi          *
     INCLD WE000001 SAMPLE5   * WebContent/WEB-INF/web.xml                  *
     INCLD MA000002 SAMPLE5   * WebContent/theme/Master.css                 *
     INCLD BL000001 SAMPLE5   * WebContent/theme/blue.css                   *
     INCLD BL000002 SAMPLE5   * WebContent/theme/blue.htpl                  *
     INCLD LO000013 SAMPLE5   * WebContent/theme/logo_blue.gif              *
     *
     * Build script and generated outputs
     *
     SINC  SAMPLE5  J2EEBLD   * J2EE WAR Build script                       *
     OUT1  *        J2EEWAR   * Sample5.war                                 *
     LIST  *        J2EELIST
    

    Figure 26. Sample EJB Application (EJB) ARCHDEF


    LKED  J2EEOBJ
    *
     INCLD XX000001 SAMPLE3   * .classpath                                  *
     INCLD XX000002 SAMPLE3   * .project                                    *
     INCLD MA000004 SAMPLE3   * ejbModule/META-INF/MANIFEST.MF              *
     INCLD EJ000004 SAMPLE3   * ejbModule/META-INF/ejb-jar.xml              *
     INCLD IB000003 SAMPLE3   * ejbModule/META-INF/ibm-ejb-jar-bnd.xmi      *
     INCLD XX000008 SAMPLE3   * ejbModule/com/ibm/ejs/container/_EJSWrapper *
                              * _Stub.java                                  *
     INCLD XX000009 SAMPLE3   * ejbModule/com/ibm/ejs/container/_EJSWrapper *
                              * _Tie.java                                   *
     INCLD XX000010 SAMPLE3   * ejbModule/com/ibm/websphere/csi/_CSIServant *
                              * _Stub.java                                  *
     INCLD XX000011 SAMPLE3   * ejbModule/com/ibm/websphere/csi/_Transactio *
                              * nalObject_Stub.java                         *
     INCLD DA000005 SAMPLE3   * ejbModule/myEJB/DateBean.java               *
     INCLD DA000006 SAMPLE3   * ejbModule/myEJB/DateBeanBean.java           *
     INCLD DA000007 SAMPLE3   * ejbModule/myEJB/DateBeanHome.java           *
     INCLD EJ000001 SAMPLE3   * ejbModule/myEJB/EJSRemoteStatelessDateBeanH *
                              * ome_1a4c4c85.java                           *
     INCLD EJ000002 SAMPLE3   * ejbModule/myEJB/EJSRemoteStatelessDateBean_ *
                              * _1a4c4c85.java                              *
     INCLD EJ000003 SAMPLE3   * ejbModule/myEJB/EJSStatelessDateBeanHomeBea *
                              * nHomeBean_1a4c4c85.java                     *
     INCLD XX000012 SAMPLE3   * ejbModule/myEJB/_DateBeanHome_Stub.java     *
     INCLD XX000013 SAMPLE3   * ejbModule/myEJB/_DateBean_Stub.java         *
     INCLD XX000014 SAMPLE3   * ejbModule/myEJB/_EJSRemoteStatelessDateBean *
                              * Home_1a4c4c85_Tie.java                      *
     INCLD XX000015 SAMPLE3   * ejbModule/myEJB/_EJSRemoteStatelessDateBean *
                              * _1a4c4c85_Tie.java                          *
     INCLD XX000016 SAMPLE3   * ejbModule/org/omg/stub/javax/ejb/_EJBHome_S *
                              * ub.java                                     *
     INCLD XX000017 SAMPLE3   * ejbModule/org/omg/stub/javax/ejb/_EJBObject *
                              * _Stub.java                                  *
     INCLD XX000018 SAMPLE3   * ejbModule/org/omg/stub/javax/ejb/_Handle_St *
                              * ub.java                                     *
     INCLD XX000019 SAMPLE3   * ejbModule/org/omg/stub/javax/ejb/_HomeHandl *
                              * e_Stub.java                                 *
     INCLD DA000008 SAMPLE3   * ejbModule/services/DateBeanServices.java    *
     INCLD XX000020 SAMPLE3   * ejbModule/services/_DateBeanServices_Stub.j *
                              * ava                                         *
    *
     SINC  SAMPLE3  J2EEBLD   * J2EE EJB JAR Build script                   *
     OUT1  *        J2EEJAR   * DateService.jar
    *
     LIST  *        J2EELIST
    

    Figure 27. Sample EAR Application (EAR) ARCHDEF


     LKED   J2EEOBJ
    *
     INCLD XX000001 SAMPLE6   * .classpath                                  *
     INCLD XX000002 SAMPLE6   * .project                                    *
     INCLD AP000001 SAMPLE6   * META-INF/application.xml                    *
     INCL  SAMPLE3  ARCHDEF   * DateService.jar                             *
     INCL  SAMPLE5  ARCHDEF   * Sample5.war                                 *
    *
     SINC  SAMPLE6  J2EEBLD   * J2EE EAR Build script                       *
     OUT1  *        J2EEEAR   * Sample6.ear                                 *
     LIST  *        J2EELIST
    

    J2EE Ant build script

    The J2EE Ant build Script format is of type J2EEBLD and language J2EEANT. It can be any name up to 8 characters and variables are defined in tagged language format. The build scripts are very similar for JAR, WAR and EAR. The syntax below is shown for a WAR build script. For JAR and EAR, build script variables are the same except for using EAR_NAME and JAR_NAME instead of WAR_NAME.

    Figure 28. J2EE Ant build script


    <ANTXML>
    <project name="J2EE Project type" default="web-war" basedir=".">
    <property name="env" environment="env" value="env"/>
    <property name="SCLM_ARCHDEF" value="ARCHDEF name"/>
    <property name="SCLM_ANTXML" value="ANTXML name"/>
    <property name="SCLM_BLDMAP" value="Include Buildmap"/>
    <property name="JAVA_SOURCE" value="Include Java Source"/>
    <property name="J2EE_HOME" value="${env.J2EE_HOME}"/>
    <property name="JAVA_HOME" value="${env.JAVA_HOME}"/>
    <property name="CLASSPATH_JARS" value="Classpath Directory location"/>
    <property name="CLASSPATH_JARS_FILES" value="Jar/class filenames"/>
    <property name="ENCODING" value="Codepage"/>
    <property name="DEBUG_MODE" value="debug_mode"/>
     
    <!-- WAR file name to be created by this build process -->
    <!-- include suffix of .war                            -->
    <property name="WAR_NAME" value="War name" />
     
    <path id="build.class.path">
     <pathelement location="."/>
     <pathelement location="${J2EE_HOME}/lib/j2ee.jar"/>
     <pathelement location="${CLASSPATH_JARS}/jdom.jar"/>
     <fileset dir="." includes="**/*.jar"/>
     <fileset dir="${CLASSPATH_JARS}" includes="**/*.jar, **/*.zip"/>
    </path>
     
    </ANTXML>
    

    The SCLM Build scripts overlay customer-defined variables dynamically on build request when running the Ant build script. These variables are set to values shown in Figure 29.

    Figure 29. Customer-defined variables

    Variable Description
    J2EE Project name Java/J2EE project type being built. This is a temporary project name set in the build script for Ant to use during the build. The values this will be set to are:
    • J2EE EAR Project
    • J2EE WAR Project
    • J2EE EJB Project
    • JAVA Project

    This variable does not need to be customized.

    ARCHDEF name ARCHDEF name or the ARCHDEF being built
    ANTXML name Name of skeleton Ant XML to use for build
    Include Buildmap Value of Yes or No. If Yes then include the SCLM build map in MANIFEST directory in JAR, WAR, or EAR. Provides audit and build map of parts included.
    Include Java Source Value of Yes or No. If Yes then include Java source in JAR, WAR, or EAR.
    Classpath directory location z/OS UNIX System Services classpath directory used for resolving classpath dependencies during build. All jars located in this directory will be used in the classpath.
    Jar/class filenames Names of individual JAR and Class files to be included in the build. This can be in the form of a list:
    <property name="CLASSPATH_JARS_FILES" value="V2J4.jar,V2J3.jar" />
    
    Codepage Either ASCII or EBCDIC codepage for JAVA This is the codepage JAVA source is stored on the z/OS host. For example:
    • For ASCII JAVA Codepage is set to SO8859-1
    • For EBCDIC JAVA Codepage is set to IBM-1047
    Ear_name/
    War name/
    Jar_name
    Name of the created EAR, WAR or JAR
    debug_mode Set to 'on' to force Developer Toolkit to not remove any build files from the WORKAREA directory. This is useful if you need to check the structure of a built Java/J2EE application.

    CLASSPATH dependencies

    Java source within an ARCHDEF can have classpath dependencies upon other Java libraries or classes. If these dependencies are on Java components contained within the same ARCHDEF structure, then these classpath dependencies are resolved as part of the ARCHDEF build (whether build mode is conditional or forced).

    However a J2EE ARCHDEF component may have classpath dependencies on external JARs or even on members contained in other ARCHDEFs. In this case the J2EE build script associated with the ARCHDEF can control classpath dependencies with the following keywords:

    CLASSPATH_JARS
    This is a directory name in the z/OS UNIX System Services file system which may include all external dependent JAR files and classes for that particular ARCHDEF build.

    This directory may be updated with CLASSPATH files via the Client Team function 'Upload jar files' to copy JAR files from the client into the classpath directory. Also available is the function 'Copy file from SCLM to classpath' to copy SCLM stored JAR files into the classpath directory.

    CLASSPATH_JARS_FILES
    This keyword can be used to selectively choose individual JAR or class files to be used in the classpath. If this keyword is used, then the listed JAR/class files are retrieved from SCLM or if not located in SCLM then the directory referenced by CLASSPATH_JARS is searched for retrieval. If this keyword is used then only those files listed are used in the classpath.

    J2EE sample scripts

    The following samples show JAR, WAR, EJB, and EAR scripts.

    Figure 30. J2EE Build script JAR sample


    <ANTXML>
    <project name="JAVA Project" default="jar" basedir=".">
    <property name="env" environment="env" value="env"/>
    <property name="SCLM_ARCHDEF" value="V2JAR1"/>
    <property name="SCLM_ANTXML" value="BWBJAVAA"/>
    <property name="SCLM_BLDMAP" value="YES"/>
    <property name="JAR_FILE_NAME" value="V2TEST.jar"/>
    <property name="CLASSPATH_JARS" value="/var/SCLMDT/CLASSPATH"/>
    <property name="ENCODING" value="IBM-1047"/>
    </ANTXML>
    

    Figure 31. J2EE Build script WAR sample


    <ANTXML>
    <project name="J2EE WAR Project" default="web-war" basedir=".">
    <property name="env" environment="env" value="env"/>
    <property name="SCLM_ARCHDEF" value="SAMPLE5"/>
    <property name="SCLM_ANTXML" value="BWBWEBA"/>
    <property name="SCLM_BLDMAP" value="YES"/>
    <property name="JAVA SOURCE" value="YES"/>
    <property name="J2EE_HOME" value="${env.J2EE_HOME}"/>
    <property name="JAVA_HOME" value="${env.JAVA_HOME}"/>
    <property name="CLASSPATH_JARS" value="/var/SCLMDT/CLASSPATH"/>
    <property name="ENCODING" value="IBM-1047"/>
    <!-- WAR file name to be created by this build process -->
    <property name="WAR_NAME" value="Sample5.war" />
    <path id="build.class.path">
     <pathelement location="."/>
     <pathelement location="${J2EE_HOME}/lib/j2ee.jar"/>
     <pathelement location="${CLASSPATH_JARS}/jdom.jar"/>
    <fileset dir="${CLASSPATH_JARS}" includes="**/*.jar, **/*.zip"/>
    </path>
    </ANTXML>
    

    Figure 32. J2EE Build script EJB sample


    <ANTXML>
    <project name="J2EE EJB Project" default="EJBBuild" basedir=".">
    <property name="env" environment="env" value="env"/>
    <property name="SCLM_ARCHDEF" value="SAMPLE3"/>
    <property name="SCLM_ANTXML" value="BWBEJBA"/>
    <property name="SCLM_BLDMAP" value="NO"/>
    <property name="J2EE_HOME" value="${env.J2EE_HOME}"/>
    <property name="JAVA_HOME" value="${env.JAVA_HOME}"/>
    <property name="CLASSPATH_JARS" value="/var/SCLMDT/CLASSPATH"/>
    <property name="ENCODING" value="IBM-1047"/>
    <property name="EJB_NAME" value="DateService.jar"/>
    <path id="build.class.path">
     <pathelement location="."/>
     <pathelement location="${J2EE_HOME}/lib/j2ee.jar"/>
     <pathelement location="${CLASSPATH_JARS}/jdom.jar"/>
     <fileset dir="${CLASSPATH_JARS}" includes="**/*.jar, **/*.zip"/>
    </path>
    </ANTXML>
    

    Figure 33. J2EE Build script EAR sample


    <ANTXML>
    <project name="J2EE EAR Project" default="j2ee-ear" basedir=".">
    <property name="env" environment="env" value="env"/>
    <property name="SCLM_ARCHDEF" value="SAMPLE6"/>
    <property name="EAR_NAME" value="Sample6.ear"/>
    <property name="SCLM_ANTXML" value="BWBEARA"/>
    <property name="SCLM_BLDMAP" value="NO"/>
    <property name="J2EE_HOME" value="${env.J2EE_HOME}"/>
    <property name="JAVA_HOME" value="${env.JAVA_HOME}"/>
    <property name="CLASSPATH_JARS" value="/var/SCLMDT/CLASSPATH"/>
    <path id="build.class.path">
     <pathelement location="."/>
     <pathelement location="${J2EE_HOME}/lib/j2ee.jar"/>
     <pathelement location="${CLASSPATH_JARS}/jdom.jar"/>
     <fileset dir="${CLASSPATH_JARS}" includes="**/*.jar, **/*.zip"/>
    </path>
    <target name="common">
    <echo message="BuildName: ${Ant.project.name}" />
    <echo message="BuildHome: ${basedir}" />
    <echo message="BuildFile: ${Ant.file}" />
    <echo message="BuildJVM: ${Ant.java.version}" />
    </target>
    </ANTXML>
    

    JAVA/J2EE Ant XML build skeletons

    This section lists sample Ant build skeletons which are provided in the SBWBSAMP library. These sample members can be copied into SCLM type J2EEBLD in the SCLM hierarchy to be referenced and used by the JAVA/J2EE build scripts. The JAVA/J2EE build scripts are property variable files that overlay the Ant XML skeleton files.

    The J2EE build skeletons work generically for standard J2EE projects and there is a separate sample for Enterprise JavaBeans (EJB) creating an EJB JAR, WEB application creating a web archive file (WAR), and Enterprise application creating an Enterprise archive file (EAR) and deployment sample. Be aware however that some J2EE projects may not fit the standard model and some customization of the supplied Ant XML skeletons may be required.

    Note: JAVA/J2EE build scripts can be generated via the Developer toolkit client application. These build scripts use a referenced Ant XML skeleton (as below) and an ARCHDEF in the JAVA/J2EE build process.

    A detailed description of build scripts, Ant skeletons and examples on JAVA/J2EE build processing is contained in the SCLM Developer Toolkit User Guide supplied with the client plug-in.

    BWBJAVAA
    Sample Ant XML JAVA build skeleton

    This Ant skeleton is used by a Java build script to compile multiple java programs and optionally create a Java Archive (JAR) file which has a structure determined by a specified ARCHDEF.

    BWBEJBA
    Sample Ant XML J2EE EJB build skeleton

    This Ant skeleton is used by a J2EE build script to compile/build an EJB project which would usually create an EJB JAR which has a structure determined by a specified ARCHDEF.

    BWBWEBA
    Sample Ant XML J2EE WEB build skeleton

    This Ant skeleton is used by a J2EE build script to compile/build a WEB project which would usually create a WEB Archive (WAR) file.

    BWBEARA
    Sample Ant XML J2EE EAR assemble skeleton

    This Ant skeleton is used by a J2EE build script as an assemble process in preparation for J2EE application deployment. The process produces Enterprise Archive (EAR) files which can be deployed on to a web application server such as WebSphere application server.


    Mapping J2EE projects to SCLM

    IBM SCLM Developer Toolkit provides the capacity to manage, build, and deploy projects in SCLM. This section describes how to configure the SCLM project structure to support distributed application development such as JAVA/J2EE.

    Many JAVA/J2EE projects result in the creation of an executable EAR file. This application is an assembly of projects, typically EJBs and web applications and, within the IDE environments, these are generally developed as individual project structures that are linked to an EAR project.

    This form of multiple-project structure does not map to SCLM directly. That is, an SCLM project cannot be linked to another SCLM project to provide some form of aggregated project structure. However, SCLM does provide a means to support this multiple project structure within a single SCLM project using types.

    SCLM projects can be defined with multiple source types. Each type can hold a single IDE project. If we tried to store multiple Eclipse IDE projects in SCLM without some form of segregation then each of the project's .classpath and .project files would be overwritten as each project was added to SCLM. The use of different source types enables these files, and all others associated with that project, to be stored safely within SCLM.

    Figure 34 shows how multiple types make it possible to support a multiple-project structure within a single SCLM project.

    Figure 34. Multiple types


    This mapping would result in the IDE projects being stored independently within SCLM using the type as the principal differentiator. For example, EJB1 is stored in the SCLM project SCLMPRJ1 under type EJB1. Using this structure, it is possible to map the IDE project structure to independent types within the SCLM project.

    Notes:

    1. It is not necessary to map a project name in the IDE to the SCLM type name; these names exist independently of each other.

    2. Type names are restricted to eight characters; therefore an IDE project called 'ProjectOne' could not have the corresponding type name of 'ProjectOne'. You can use 'Proj1' instead.

    It is therefore important that the SCLM project structure be planned to accommodate the mapping of different IDE-based projects into the single SCLM project structure. This is because, within large SCLM projects, it may be a non-trivial matter to add additional project types as this requires a change to the SCLM project definition, a rebuild of the SCLM project definition, and the allocation of data sets for the new types.

    This structure is not restricted to J2EE-style projects but could also apply to any situation where multiple projects are being developed that provide some form of dependency upon each other.

    Recommendations for mapping J2EE projects to SCLM

    The following list gives recommendations for mapping J2EE projects (and others) to SCLM:

    The use of multiple SCLM types to store individual IDE projects also relates to the operation of the ARCHDEF structure for the building of these IDE projects.

    Figure 35. SCLM build hierarchy


    The ARCHDEF file contains the list of files that make up a build. In a J2EE context a build can result in an EAR file being composed of a number of WAR and JAR files. This isolation of projects is similar to the type structure that defines the project in SCLM. By having a high-level ARCHDEF that references those 'parts' that make up the build, it is possible to have a structured build environment. This relates to the effective definition of project structure when defining the types in SCLM.

    By defining the project in a structured manner this also enables:

    When building applications with references or dependencies on other build objects such as JARs, other projects or other classes there are multiple approaches:

    1. Include the reference to the JAR via the INCLD statement in the ARCHDEF. This will build the application with the library reference into the final build package.
    2. Include the IDE project as a nested INCL SCLM project ARCHDEF
    3. Include the dependent JAR in the CLASSPATH directory
      1. Should the IDE project refer to a JAR but it is not expected to be part of the final build package then the library file can be copied to the system CLASSPATH using the Upload JARS service in Developer Toolkit. This will have the effect of making that service available from a different SCLM project. At build time the IDE project references to the JAR will be resolved. However at runtime, the JAR must be available in a PATH statement.
      2. Reference a JAR that is in the same SCLM project through the use of the CLASSPATH_JARS_FILES property in the build script.

    SCLM Developer Toolkit deployment

    SCLM Developer Toolkit provides several deployment features. You may deploy Enterprise Archive files (EAR) into any WebSphere Application Server (WAS). In addition, any component built or controlled by the SCLM Developer Toolkit may be distributed using a customizable deploy script. Sample scripts are provided that can be used to copy an EAR to a remote host using the secure copy (SCP) and secure FTP (SFTP) commands.

    At the core of deployment there are essentially two scripts. The first type of script, the one that is modified by the user, is the properties script. It contains a list of parameters for the deployment operation. The second is the action script that contains the steps required to run the deployment operation.

    Deployment is initiated from the SCLM Developer Toolkit client plug-in and the type of deployment is chosen by pressing the relevant button on the deployment screen. Depending on what deployment action is chosen will have an effect on what is populated in the properties script, For most of the scripts there is a property named SCLM_ANTXML that contains the member name of the corresponding action script. Developer Toolkit takes the generated properties script and overlays it on the action script, before invoking the resultant action script.

    Below is a list of sample Ant deployment action scripts which are provided in the SBWBSAMP library. These sample members can be copied into SCLM type J2EEBLD in the SCLM hierarchy to be referenced and used by the generated properties scripts. The generated properties scripts are property variable files that overlay the Ant XML deployment action scripts referenced below. These scripts must be stored with a text type language such as TEXT or J2EEPART.

    Member Name
    Description

    BWBDEPLA
    WAS EAR Deployment.

    BWBRDEPL
    Remote WAS EAR Deployment.

    BWBSCOPY
    Secure copy deployment. Copies a build object from one host to another using SCP.

    BWBSFTP
    Secure FTP deployment. Copies a build object from one host to another using SFTP.

    In order for these build scripts to be usable from multiple groups, the administrator must build and promote the scripts to the highest group level available in the project.

    There is slightly different processing depending on the types of scripts being generated.

    WebSphere Application Server (WAS) deployment

    For WebSphere Application Server (WAS) deployment the SCLM_ANTXML property does not point to an Ant action script, but references a JACL action script instead. Deployment to WAS on z/OS uses theAlternatively you may use the wsadmin tool that is shipped with WAS on z/OS. wsadmin requires a JACL script to guide the deployment process. If using this deploy method then the JACL script must be installed under UNIX Systems Services before the deployment process can be invoked. The JACL script must be copied into a z/OS UNIX System Services file system directory on z/OS. It is recommended to store the JACL script as /etc/SCLMDT/CONFIG/scripts/deploy.jacl (where /etc/SCLMDT is the default etc directory for SCLM Developer Toolkit). The wsadmin tool expects the JACL script to be in ASCII format.

    To copy the sample JACL script BWBJACL (that resides in the SBWBSAMP sample library) into a z/OS UNIX System Services file system directory in ASCII format, follow these steps:

    The client plug-in must be aware of the directory locations where the wsadmin tool (wsadmin.sh) and the JACL script are installed under Unix System Services. Both locations can be configured in the preference page under Team -> SCLM Preferences -> Build Script Options. The client plug-in is used to generate a deployment script which can then be built against. (The deployment process is triggered by a deploy function request against the deployment script which resides in SCLM type J2EEBLD).

    The sample action scripts that need to be stored in SCLM type J2EEBLD for WAS deployment or remote WAS deployment are BWBDEPLA and BWBRDEPL.

    SCLM to Unix System Services deployment

    SCLM developer Toolkit provides a means to deploy any files that reside in the SCLM repository to the z/OS UNIX System Services File System on the same LPAR. This provides a simple means to deploy an object built by SCLM into an environment where it can be either executed or even deployed to a remote host using the Secure Deployment described below.

    There is no sample action script for this action. By selecting the members from SCLM using the Include SCLM members button will generate the required properties script. By running this the files are copied from the selected SCLM locatation to a directory specified on the z/OS UNIX System Services File System. This directory must previously exist or an error will occur.

    Secure deployment

    This options provide a means to copy deployable objects to a remote host by utilizing the secure copy (SCP) and secure FTP (SFTP) commands. By using a combination of the Secure deploy properties script and the Include SCLM members, the required files can be selected from the SCLM hierarchy, copied to a location in the z/OS UNIX System Services File System, and then copied to the destination machine from that z/OS UNIX System Services File System location utilizing the secure copy (SCP) and secure FTP (SFTP) commands.

    The sample action scripts that need to be stored in SCLM type J2EEBLD for secure deployment are BWBSCOPY and BWBSFTP.

    In order for Developer Toolkit to use SFTP (Secure file transfer protocol) or SCP (Secure copy protocol) within ANT deploy scripts the IBM Ported Tools for z/OS (For z/OS V1.4 and above - Program number 5655-M23) product is required to be installed as a pre-requisite.

    IBM Ported Tools for z/OS is a non-priced program product designed to deliver tools and applications for the z/OS platform. These applications have been modified to operate within the z/OS environment. IBM Ported Tools for z/OS is only available to customers with a license to z/OS; it is supported on z/OS 1.4 and above.

    It provides:

    Public key authentication

    Public key authentication provides an alternative to interactive logon that can be automated as part of Developer Toolkit's secure deployment operation.

    In order for public key authentication to work as desired, you can either use a surrogate User ID for deployment or configure each user for whom you wish to provide deployment capabilities.

    For instructions on how to set up automated key-based authentication using ssh-agent and ssh-add, see the IBM Ported Tools for z/OS User's Guide. For information about using SCLM Developer Toolkit surrogate user ID, see Chapter 4, SCLM security.

    Other deployment options

    It is also possible to create your own Ant scripts to perform deployment in a number of different ways. In your scripts, by using the Ant <exec> tag you can invoke any program that is available in the z/OS UNIX System Services File System. Using this method the build scripts can call other programs, such as FTP, to perform deployment. For more information of creating Ant scripts see the online Ant documentation at http://ant.apache.org/.


    ASCII or EBCDIC storage options

    Source files transferred from the SCLM Developer Toolkit plug-in may be stored in SCLM as either ASCII or EBCDIC.

    Generally all source in SCLM is stored in EBCDIC to be viewed and edited directly from ISPF/SCLM on z/OS. Users who do not want to browse or edit code directly from the host may want to store code directly (that is, as binary transferred) where source will be stored in SCLM using the original client's ASCII/UNICODE codepage. This does have some performance benefits for large projects being stored and imported from SCLM and for JAVA/J2EE builds as an ASCII to EBCDIC translation will not be performed.

    SCLM Developer Toolkit determines if a file is binary transferred or if an ASCII to EBCDIC conversion takes place by checking the SCLM language associated with each file/member. Then SCLM Developer Toolkit checks to see if that SCLM Language has an entry in the TRANSLATE.conf file with a TRANLANG keyword.

    ASCII/EBCDIC language translators

    Figure 36. SCLM Language Translators and ASCII/EBCDIC



    SCLM

    Language

    Translator
    Description

    JAVA
    Java source members stored as EBCDIC. Created by using sample
    BWBTRAN1.

    JAVABIN
    Java source members stored as ASCII. Created by using sample
    BWBTRAN1.

    J2EEPART
    Any J2EE files where no parsing is required and stored as EBCDIC.
    Created by using sample BWBTRAN1.

    J2EEBIN
    Any J2EE files where no parsing is required and stored as binary or ASCII
    files. Created by using sample BWBTRAN1.

    TEXT
    Default TEXT translator where no parsing is required and stored as
    EBCDIC. Created by using sample BWBTRAN1.

    BINARY
    Default binary language translator where no parsing required.
    Created by using sample BWBTRAN1.

    Default usage is assumed to be ASCII/EBCDIC translation. This means that files browsed and edited in the Eclipse Plug-in may also be browsed and edited directly on host from ISPF/SCLM.

    ASCII usage (binary transferred) is recommended for project migration/import and build performance, as files require no translation. This is only suitable if editing in ISPF/SCLM is not required.

    Depending on the SCLM Language Translator used, source can be built in either ASCII or EBCDIC.

    For cross platform usability, all deployable files such as JAR, WAR and EAR are built such that all of the contained objects are of type ASCII, regardless of whether any of the source is stored as EBCDIC.

    JAVA/J2EE build note: If Java source is ASCII stored then the Build script must specify the ASCII codepage using the ENCODING property variable to correctly compile the Java source.

    For example:

      <property name="ENCODING" value="ISO8859-1"/>
    

    The Ant script called will use the Javac command with the ENCODING=ISO8859-1 to compile the ASCII source. The default ENCODING codepage is the EBCDIC codepage IBM-1047.

    $GLOBAL member

    As part of the JAVA/J2EE build process some additional information is required in order to successfully perform the builds. As the builds are performed in z/OS UNIX System Services, information such as the Java product location, Ant product location and the location of the SCLM Developer Toolkit configuration files and workarea are required.

    Additionally it may be required to use different versions of Ant or Java for different SCLM development groups, so to this end the $GLOBAL member can be group specific. The environment variables set in $GLOBAL may be overwritten by specific build script variable settings.

    A sample member BWBGLOB is provided in the SBWBSAMP library. This sample member needs to be copied into SCLM type J2EEBLD in the SCLM hierarchy as member $GLOBAL and saved with a valid non-parsing language, such as TEXT (as provided in language translator FLM@TEXT in the SISPMACS library).

    The $GLOBAL member currently makes available the following information to the JAVA/J2EE build processes:

    Figure 37. $GLOBAL variables

    Variable Description
    ANT_BIN z/OS UNIX System Services file system directory path of Ant runtime

    Example:

      <property name="ANT_BIN" value="/u/antdirectory/Ant/apache-Ant-1.6.0/bin/Ant"/>
    
    JAVA_BIN z/OS UNIX System Services file system directory path of Java compile/runtime

    Example:

      <property name="JAVA_BIN" value="/u/javadirectory/IBM/J1.4/bin"/>
    
    CGI_DTWORK The location of the SCLM Developer Toolkit WORKAREA directory

    Example:

      <property name="CGI_DTWORK" value="/var/SCLMDT"/>
    
    CGI_DTCONF The location of the SCLM Developer Toolkit CONFIG directory

    Example:

      <property name="CGI_DTCONF" value="/etc/SCLMDT"/>
    
    CLASSPATH_JARS z/OS UNIX System Services file system classpath directory used for JAVA compiles. All jars located in this directory will be used in the classpath.

    Example:

      <property name="CLASSPATH_JARS" value="/var/SCLMDT/CLASSPATH"/>
    
    TRANTABLE VSAM file containing the long/short name translations

    Example:

      <property name="TRANTABLE" value="BWB.LSTRANS.FILE"/>
    
    DEBUG_MODE Set to "on" if you want Developer Toolkit to not remove Java/J2EE build files from the z/OS UNIX System Services file system.

    This is useful if you want to see the structure of the built outputs in the USS file system for debugging purposes.

    If these variables are to be set for the all group levels in the SCLM project then it is good practice to create a single $GLOBAL member at the highest level in the hierarchy. When the JAVA/J2EE build translator runs it will look up the hierarchy from the group level performing the build and use the first $GLOBAL it finds in the J2EEBLD type.

    Note: The $GLOBAL member must be stored as a valid saved SCLM member so this hierarchy lookup can be performed.

    If different settings are required, at different development groups for example, then a $GLOBAL member can be created in each of the development groups. This may be useful if a build was required at Java 1.4 level as well as Java 1.5 level in order to test code at different Java levels.

    SITE and project-specific options

    A facility has been provided to allow certain settings to be made at a SITE installation level or at a specific SCLM project level. The options that can currently be configured are:

    All or none of these options can be set. If they are not set they will be defaulted in the programs. Some of these options can be set in the SITE file while others can be set at an SCLM project-specific level. Alternatively there can be no SITE specific file and options can be set at an SCLM project level only. For job cards the user can override the job card information by using their own specified job card entered through the IDE.

    This facility is activated by creating certain files in the z/OS UNIX System Services file system under the /etc/SCLMDT/CONFIG/PROJECT directory, or wherever you created the /CONFIG/PROJECT directory at installation time. This directory is created at project initialization time by running job BWBINST1.

    If you want to set SITE specific values then you need to create a file called SITE.conf in the /PROJECT directory. A sample SITE config file is provided in the SBWBSAMP library in member BWBSITE. Copy this member to a file named SITE.conf in this directory and tailor the values accordingly. The following figure shows the sample SITE configuration file.

    Figure 38. Sample SITE specific SCLM project setting


    *
    * ---------------- SITE SPECIFIC OPTIONS ------------------
    *
    * Below are a number of site specific options used to
    * determine the behaviour of the Eclipse front-end.
    * These can be overridden by creating a project specific
    * options file for the SCLM project that overrides some
    * or all of these options.
    *
    * SCM Approver processing applies to this project?
    BUILDAPPROVER=NONE
    PROMOTEAPPROVER=NONE
    *
    * Change Code entry on check-in is mandatory?
    CCODE=N
    *
    * Foreground or On-line builds/promotes allowed for this project?
    FOREGROUNDBUILD=Y
    FOREGROUNDPROMOTE=Y
    *
    * Batch Build default jobcard
    BATCHBUILD1=//SCLMBILD JOB (#ACCT),'SCLM BUILD',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
    BATCHBUILD2=//*
    BATCHBUILD3=//*
    BATCHBUILD4=//*
    *
    * Batch Promote default jobcard
    BATCHPROMOTE1=//SCLMPROM JOB (#ACCT),'SCLM PROMOTE',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
    BATCHPROMOTE2=//*
    BATCHPROMOTE3=//*
    BATCHPROMOTE4=//*
    *
    * Batch Migrate default jobcard
    BATCHMIGRATE1=//SCLMMIGR JOB (#ACCT),'SCLM MIGRATE',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
    BATCHMIGRATE2=//*
    BATCHMIGRATE3=//*
    BATCHMIGRATE4=//*
    

    It is also possible to have project-specific configuration settings that are used to configure a single SCLM project. These will override the SITE-specific values if a SITE.conf exists. If you want to set project-specific values then you need to create a file called project.conf in the /PROJECT directory, where project is the SCLM project name. A sample project config file is provided in the SBWBSAMP library in member BWBPROJ. Copy this member to a file named project.conf in the /PROJECT directory and tailor the values accordingly. The following figure shows the sample Project configuration file.

    Figure 39. Sample PROJECT specific SCLM project setting


    *
    * ---------------- PROJECT SPECIFIC OPTIONS ------------------
    *
    * Below are a number of project specific options used to
    * determine the behaviour of the Eclipse front-end.
    *
    * These will override the SITE.CONF file
    *
    *
    * SCM Approver processing applies to this project?
    BUILDAPPROVER=BREEZE
    PROMOTEAPPROVER=BREEZE
    *
    * Change Code entry on check-in is mandatory?
    CCODE=Y
    *
    * Foreground or On-line builds/promotes allowed for this project?
    FOREGROUNDBUILD=N
    FOREGROUNDPROMOTE=N
    *
    * Batch Build default jobcard
    BATCHBUILD1=//SCLMBILD JOB (#ACCT),'SCLM BUILD',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,
    BATCHBUILD2=// MSGLEVEL=(1,1)
    BATCHBUILD3=//*
    BATCHBUILD4=//*
    *
    * Batch Promote default jobcard
    BATCHPROMOTE1=//SCLMPROM JOB (#ACCT),'SCLM PROMOTE',CLASS=A,MSGCLASS=X,
    BATCHPROMOTE2=// MSGLEVEL=(1,1),NOTIFY=&SYSUID
    BATCHPROMOTE3=//*
    BATCHPROMOTE4=//*
    

    Options Definition

    All of the options are optional. They are set to the default values by the product. If any of the options are specified in the SITE.conf or the project.conf then they will be used.

    Figure 40. SITE/Project options

    BUILDAPPROVER=approval product/NONE Specify the name of the approval product used for the build process. Currently the only supported product is Breeze for SCLM. Default is NONE.
    PROMOTEAPPROVER=approval product/NONE Specify the name of the approval product used for the promote process. Currently the only supported product is Breeze for SCLM. If the PROMOTEAPPROVER is set to BREEZE then the Breeze specific fields will be displayed during a promote. Default is NONE.
    CCODE=N/Y Specify Y to make change code entry on check-in a mandatory field. Default is N such that Change Code entry is not mandatory.
    FOREGROUNDBUILD=Y/N Specify N to restrict foreground builds. Default is Y such that foreground builds are allowed.
    FOREGROUNDPROMOTE=Y/N Specify N to restrict foreground promotes. Default is Y such that foreground promotes are allowed.
    BATCHBUILD1=Job card 1
    BATCHBUILD2=Job Card 2
    BATCHBUILD3=Job Card 3
    BATCHBUILD4=Job Card 4
    
    Set a default batch job card for the build process. Different projects may use different account codes or Job class so the option of specifying project specific job cards allows for this scenario.
    BATCHPROMOTE1=Job card 1
    BATCHPROMOTE2=Job card 2
    BATCHPROMOTE3=Job card 3
    BATCHPROMOTE4=Job card 4
    
    Set a default batch job for the Promote process. Different projects may use different account codes or Job class so the option of specifying project specific job cards allows for this scenario.
    BATCHMIGRATE1=Job card 1
    BATCHMIGRATE2=Job card 2
    BATCHMIGRATE3=Job card 3
    BATCHMIGRATE4=Job card 4
    
    Set a default batch job for the Migrate process. Different projects may use different account codes or Job class so the option of specifying project specific job cards allows for this scenario.
    BUILDSECURITY=Y/N Specify Y to invoke SAF/RACF security call and possible surrogate ID switch. For more information about this, see Chapter 4, SCLM security.
    PROMOTESECURITY=Y/N Specify Y to invoke SAF/RACF security call and possible surrogate ID switch. For more information about this, see Chapter 4, SCLM security.
    DEPLOYSECURITY=Y/N Specify Y to invoke SAF/RACF security call and possible surrogate ID switch. For more information about this, see Chapter 4, SCLM security.
    ASCII=ASCII codepage Specify the ASCII codepage to override the ASCII codepage specified in the TRANSLATE.conf file. For example:
       ASCII=UTF-8
     
    
    EBCDIC=EBCDIC codepage Specify the EBCDIC codepage to override the EBCDIC codepage specified in the TRANSLATE.conf file. For example:
       EBCDIC=IBM-420
     
    
    TRANLANG=SCLM Language Specify a TRANLANG parameter to be added to the list of TRANLANG parameters specified in the TRANSLATE.conf. For example:
       TRANLANG=DOC
     
    
    NOTRANLANG=SCLM Language Use the NOTRANLANG keyword to remove an already specified TRANLANG from the list allowable for this SCLM project as specified in the TRANSLATE.conf. For example:
       NOTRANLANG=JAVA
     
    
    LONGLANG=SCLM Language Specify a LONGLANG parameter to be added to the list of LONGLANG parameters specified in the TRANSLATE.conf. For example:
       LONGLANG=DOC
     
    
    NOLONGLANG=SCLM Language Use the NOLONGLANG keyword to remove an already specified LONGLANG from the list allowable for this SCLM project as specified in the TRANSLATE.conf. For example:
       NOLONGLANG=JAVA
     
    
    BIDIPROP=LANG=SCLM Language/* TextOrient=LTR/RTL TextType=Visual/Logical SymetricSwap=On/Off NumericSwap=On/Off Use the BIDIPROP keyword to set BiDirectional language defaults to SCLM languages. The LANG= can be set to either all SCLM languages or to specific SCLM languages. BiDirectional support is only supported under WebSphere Developer for System z. For more information see the "WebSphere Developer for System z Host Configuration Guide".

    Example of using combinations of the TRANSLATE.conf overrides

    The TRANSLATE.conf file sets up default settings for codepage support and default SCLM language support to be applied across the installation of SCLM Developer Toolkit. So TRANSLATE.conf may have the following values:

    CODEPAGE ASCII = ISO8859-1
    CODEPAGE EBCDIC = IBM-1047
    *
    TRANLANG JAVABIN
    TRANLANG J2EEBIN
    TRANLANG J2EEOBJ
    *
    LONGLANG JAVA
    LONGLANG J2EEPART
    LONGLANG JAVABIN
    LONGLANG J2EEBIN
    LONGLANG J2EEOBJ
    

    It is then possible for different SCLM projects, that are storing different types of data, maybe in different national languages, to override these default settings. So the project configuration file for SCLM project SCLMPRJ1 may have the following TRANSLATE.conf override settings:

    * Arabic Codepage overrides
    *
    ASCII=UTF-8
    EBCDIC=IBM-420
    *
    * Project specific TRANLANG and LONGLANG entries
    *
    TRANLANG=DOC
    LONGLANG=DOC
    

    This sets codepages for source translations to the Arabic codepage pair. Additionally an SCLM Language of DOC will be added to the defaults from the TRANSLATE.conf.

    SCLM Project SCLMPRJ2 may have some different TRANSLATE.conf settings:

    * Hebrew Codepage overrides
    *
    ASCII=UTF-8
    EBCDIC=IBM-424
    *
    * Project specific TRANLANG and LONGLANG entries
    *
    TRANLANG=DOC
    TRANLANG=XLS
    NOTRANLANG=JAVABIN
    NOTRANLANG=J2EEBIN
    NOTRANLANG=J2EEOBJ
    LONGLANG=DOC
    LONGLANG=XLS
    NOLONGLANG=JAVA
    NOLONGLANG=J2EEPART
    NOLONGLANG=JAVABIN
    NOLONGLANG=J2EEBIN
    NOLONGLANG=J2EEOBJ
    

    This sets codepages for source translations to the Hebrew codepage pair. Additionally SCLM Languages of DOC and XLS are added to the defaults from the TRANSLATE.conf. In this case, however, the defaults set in TRANSLATE.conf are then removed. This is not really necessary, as having additional settings is not an issue, but it demonstrates how a project can be set up to only have the required SCLM languages for a specific SCLM project.

    Example of using combinations of the BIDIPROP overrides

    The BIDIPROP values specified in the SITE.conf file can be overridden by any of the BIDIPROP values specified in the SCLM project-specific project.conf files. For example the following is set in the SITE.conf:

    *
    * ---------------- SITE SPECIFIC BIDI OPTIONS ------------------
    *
    *
    * BiDi Language default properties
    *
    BIDIPROP=LANG=*     TextOrient=LTR TextType=Visual  SymetricSwap=Off NumericSwap=Off
    

    This sets all SCLM languages to the specified settings. Now the following can be set in the ADMIN10.conf file:

    *
    * BiDi Language default properties
    BIDIPROP=LANG=JAVA  TextOrient=RTL TextType=Visual  SymetricSwap=On  NumericSwap=Off
    BIDIPROP=LANG=COBOL TextOrient=RTL TextType=Logical SymetricSwap=Off NumericSwap=Off
    

    These settings will override the settings in the SITE.conf for the JAVA and COBOL language definitions. All other languages will have the default settings specified in the SITE.conf.


    Chapter 4. SCLM security

    The SCLM Developer Toolkit offers optional security functionality if required for the Build, Promote, and Deploy functions.


    Build/Promote/Deploy security flag and process flow

    Customers may set a Build, Promote, Deploy security flag in the SITE/PROJECT configuration files which specifies additional SAF security checking for that function and possible processing under a surrogate user ID.

    If the security flag is set:


    Security rules and surrogate user ID

    The SCLM Build, Promote, and Deploy function security is to be defined using the SAF/RACROUTE security interface. The following security products are known to support this interface: RACF, ACF2, and TOP SECRET.

    The examples that follow are modelled on RACF using the definition and permission commands RDEFINE and PERMIT. Other security products supporting SAF will have their own commands for equivalent definitions. Refer to the appropriate security product documentation for these definitions.

    Build rule format

    Below is the format for the SCLM profile definition for Builds.

    SCLM.BUILD.project.projdef.group.type.member
     
    

    Field sub-parameter details:

    Promote rule format

    Below is the format for the SCLM profile definition for Promotes.

       SCLM.PROMOTE.project.projdef.group.type.member
     
    

    Field sub-parameter details:

    Deploy rule format

    Below is the format for the SCLM profile definition for deployment:

       SCLM.DEPLOY.server.application.node.cell.project.projdef.group.type
     
    

    Field sub-parameter details:


    SAF/RACF BUILD, PROMOTE, DEPLOY, and PROFILE rules

    Below is an example for a Build profile rule using class XFACILIT which would be defined by the security administrator. The same sample may be used for a PROMOTE rule by replacing the SCLM.BUILD.* rule with the SCLM.PROMOTE.* rule.

    Note: As with standard RACF rules instead of specific parameters generic '*' fields may be used. Users matching the appropriate SAF/RACF rule will be allowed BUILD access if they have READ access on the rule . The default access for the rule will be NONE -> UACC(NONE). Users access rule is defined by the PERMIT command.

    The following rule secures all members for build in project=TESTPROJ at group level prod. Also a surrogate user ID is stored in the rule under application data - APPLDATA('SUID=xxxxx').

    RDEFINE XFACILIT SCLM.BUILD.TESTPROJ.TESTPROJ.PROD.*.* UACC(NONE) APPLDATA('SUID=PMEANEY')
    

    This example defines an SCLM build profile where:

    Note: A surrogate user ID of PMEANEY is stored in the application data.

    The following example shows security permissions defined for individual users and user groups for the above example. This is also defined by the security administrator.

    PERMIT  SCLM.BUILD.TESTPROJ.*.*.*.*  CLASS(XFACILIT) ID(HOGES) ACCESS(READ)
    

    Through the use of wildcard characters, the PERMIT matches the original RDEFINE profile and permits user HOGES to build any member from project TESTPROJ and group PROD. Since there is a surrogate user ID stored in the 'APPLICATION DATA' of the matching rule then the BUILD is processed under that surrogate user ID (in this case PMEANEY).

    Below is an example for a deployment profile using class XFACILIT which would be defined by the security administrator:

    RDEFINE
    XFACILIT SCLM.DEPLOY.servery.testapp.node1.cell1.TESTPROJ.TESTPROJ.PROD.J2EEDEP
    UACC(NONE)
    

    This defines an SCLM deploy profile for WAS:
    server name = servery
    application name = testapp
    node name = node1
    Cell name = cell1

    SCLM project details:
    Project = TESTPROJ
    Alternate project definition = TESTPROJ
    Sclm group = PROD
    Sclm type = J2EEDEP

    The following two examples show different security permissions defined for individual users and user groups for the above example. This would also be defined by the security administrator. UACC authority for the profiles would be ACCESS(NONE):

    PERMIT SCLM.DEPLOY.servery.testapp.*.*.*.*.*.* CLASS(XFACILIT) ID(HOGES) ACCESS(READ)
    

    Through the use of wildcard characters, the PERMIT matches the original RDEFINE profile and permits user HOGES to deploy on WAS server=servery, application=testapp, node=node1, cell=cell1, SCLM project=TESTPROJ, projdef=TESTPROJ, group=PROD, and type=J2EEDEP.

    PERMIT  SCLM.DEPLOY.*.*.*.*.*.*.*.*.  CLASS(XFACILIT) ID(J2EEGRP) ACCESS(read)
    

    This matches the original RDEFINE profile and permits any user who belongs to the RACF group J2EEGRP to deploy on the above server and from the same SCLM project details.


    Chapter 5. CRON-initiated Builds and Promotes

    Although most Builds and Promotes are initiated via the Developer Toolkit client, there is a provision to set up Build and Promote configuration files within the z/OS UNIX System Services file system and to initiate these builds or promotes via the CRON (time) service within UNIX System Services. Using this method, the SCLM Developer Toolkit Client is not required, as the relevant Build and Promote parameters are read from a z/OS UNIX System Services file system configuration file and passed to the Developer Toolkit Host component for SCLM processing.

    Below is a description of the SCLM Developer Toolkit samples that provide CRON-initiated Builds and Promotes. These samples are available in the installed Developer Toolkit SBWBSAMP data set.

    Figure 41. Sample CRON members



    Sample member
    Description

    BWBCRON1
    This REXX sample calls the SCLM Developer Toolkit host interface and
    passes the function parameters.
    Output from the function process by default is displayed to STDOUT but may be
    re-directed to a z/OS UNIX System Services file system file or log.

    This sample may be copied into the z/OS UNIX System Services file system
    into a directory path of the user's choice to run. The sample will
    need to be customized as detailed within the sample.

    This REXX sample must be run in conjunction with input from sample BWBCRONB
    for a build or sample BWBCRONP for a promote.

    BWBCRONB
    This REXX sample sets up the Build parameter input string which is passed
    to module BWBCRON1.


    The sample requires user customization to update all required build
    parameters.

    This sample must be copied into a user determined z/OS UNIX System Services
    file system directory (optionally renamed) to be run with sample
    BWBCRON1.

    BWBCRONP
    This REXX sample sets up the Promote parameter input string which will be
    passed to module BWBCRON1.


    The sample requires user customization to update all required promote
    parameters.

    This sample must be copied into a user determined z/OS UNIX System Services
    file system directory (optionally renamed) to be run with sample
    BWBCRON1.



    STEPLIB and PATH requirements

    The PATH and STEPLIB variables in either the system wide profile (/etc/profile) or the users profile (/u/userid/.profile) will need to be set to locate the CRON jobs ($PATH) and locate the SCLM Developer Toolkit modules ($STEPLIB) if the SCLM Developer Toolkit data set is not in the LINKLIST.

    Example:

    The samples BWBCRON1 and BWBCRONB are copied to a test directory /var/SCLMDT/CRONJOBS. The following z/OS UNIX System Services file system PATH and STEPLIB variables are set in /etc/profile:

      PATH=/var/SCLMDT/CRONJOBS:$PATH
      STEPLIB=BWB.SBWBLOAD:$STEPLIB
    

    CRON Build job execution

    Once the CRON jobs are added to the PATH variable they can be run by piping the output from the parameter_exec into the processing_exec. The output can then be directed to an output log file.

    Syntax

    parameter_exec | processing_exec > output.log
    

    The "|" is the z/OS UNIX System Services pipe symbol.

    Invocation Example:

    Using the sample names as provided the CRON build exec can be invoked as follows:

      BWBCRONB | BWBCRON1 >bwbcronb.log
    

    Additionally this sample Build execution can be added to a CRONTAB file to run at 7.30pm Monday- Friday:

      30 19 * * 1-5 BWBCRONB|BWBCRON1 >bwbcronb.log ;
    

    For further information about the CRON services available and the CRONTAB format see the following manuals:

    Alternatively use the online manual help (man) under z/OS UNIX System Services:

    CRON Build job samples

    Below are the BWBCRON1 and BWBCRONB job samples as provided in the SBWBSAMP library.

    Figure 42. Sample CRON Build Exec


    /* REXX */
    /* Customize STEPLIB and CGI_VCMPATH BELOW */
    /*
    The STEPLIB should reflect the install load library for SCLM Developer
    toolkit.
    If this data set resides in the LINKLIST then set STEPLIB to '' .
    */
    STEPLIB = 'BWB.V1R1M0.SBWBLOAD'
    /*
    The Environment variable CGI_VCMPATH determines the HOME directory
    path where the configuration files reside for SCLM Developer Toolkit.
    This was determined by the installation directory specified in installation
    job BWBINST1. By default /var/SCLMDT .
    */
    CGI_VCMPATH = '/var/SCLMDT'
    /* */
    /* SAMPLE USEAGE */
    /*
    COMMAND : BWBCRONB|BWBCRON1 >BWBCRONB.log
    (passes build parameter list to BWBCRON1 & outputs to BWBCRONB.log)
    */
    /* DO NOT ALTER BELOW */
    CALL ENVIRONMENT 'STEPLIB',STEPLIB
    CALL ENVIRONMENT 'CGI_VCMPATH',CGI_VCMPATH
    CALL BWBINT
    EXIT
    

    Figure 43. Sample Build parameter file


    /* REXX */
    /* SAMPLE BUILD PARAMETER FILE USED FOR CRON INITIATED BUILDS */
    /* Update Build parameters below */
    /* if parameter required as Blank then set as '' */
    FUNCTION = 'BUILD'
    PROJECT  = 'PROJ1'   /* SCLM Project            */
    PROJDEF  = ''        /* Alt proj definition     */
    TYPE     = 'SOURCE'  /* SCLM Type               */
    MEMBER   = 'TESTMEM' /* SCLM Member name        */
    GROUP    = 'DEV1'    /* SCLM Group              */
    GROUPBLD = ''        /* Build at Group          */
    REPDGRP  = 'DEV1'    /* Users Development group */
    BLDREPT  = 'Y'       /* Generate Build report   */
    BLDLIST  = 'Y'       /* Generate List on error  */
    BLDMSG   = 'Y'       /* Generate Build Messages */
    BLDSCOPE = 'N'       /* Build Scope E/L/N/S     */
    BLDMODE  = 'C'       /* Build Mode C/F/R/U      */
    BLDMSGDS = ''        /* Message data set        */
    BLDRPTDS = ''        /* Report data set         */
    BLDLSTDS = ''        /* list data set           */
    BLDEXTDS = ''        /* Exit data set           */
    SUBMIT   = 'BATCH'   /* Online or Batch         */
    /* DO NOT ALTER PARM BUILD VARIABLE BELOW */
    PARM1 = 'SCLMFUNC='FUNCTION'&PROJECT='PROJECT'&PROJDEF='PROJDEF||,
    '&TYPE='TYPE'&MEMBER='MEMBER'&GROUP='GROUP'&GROUPBLD='GROUPBLD||,
    '&REPDGRP='REPDGRP'&BLDREPT='BLDREPT'&BLDLIST='BLDLIST||,
    '&BLDMSG='BLDMSG'&BLDSCOPE='BLDSCOPE'&BLDMODE='BLDMODE||,
    '&BLDMSGDS='BLDMSGDS'&BLDRPTDS='BLDRPTDS'&BLDLSTDS='BLDLSTDS||,
    '&BLDEXTDS='BLDEXTDS'&SUBMIT='SUBMIT
    /* outputs parameter string as input to BWBCRON1 */
    SAY PARM1
    

    Part 3. Appendixes


    Appendix A. SCLM overview

    IBM SCLM Developer Toolkit provides the means by which distributed applications written in Eclipse can be managed and built using SCLM, the IBM z/OS source code management system.

    The language and tools used by distributed and mainframe users is as different as the environments they employ. By identifying and understanding key concepts of both environments then it is possible to successfully integrate these into a cohesive structure.

    In terms of application structure Developer Toolkit is a series of Eclipse plug-ins with corresponding z/OS host code that enables both the use of HTTP and RSE transports. Operationally an Eclipse developer registers a workspace project with SCLM. Files in the project can be added to an SCLM project, checked in and out, and optionally built and deployed. All these services are driven via the Team Actions menu. From the SCLM administrators point of view, they can create projects, types, languages and associated built translators. Features such as change and authorization codes are dependent on requirements.


    SCLM Concepts

    From a Java/J2EE developers perspective, the following concepts help describe SCLM.

    File naming

    The z/OS file system only supports file name lengths of eight characters. The Developer Toolkit interface provides a translation service that enables normal Java long name conventions to be supported. There are files specific to SCLM that must comply with the naming restriction. These relate principally to the ARCHDEF structure described in J2EE ARCHDEF.

    Type

    Each file (known as a member in SCLM terminology) that is stored in an SCLM project is stored in a data set. The data set where the file is stored is identified by SCLM type. The type is part of the data set name, made up as far as SCLM is concerned by SCLM Project.Group.Type. with a language associated with it. There can be many types defined in an SCLM project . These types provide a means whereby two files with the same name can be stored in the same SCLM project. Each project can contain many types. By applying the use of type it is possible to store multiple Eclipse projects in the one SCLM project even though each IDE project potentially has a .project and .classpath file. If we do not segregate these files using type, then only one copy of these files exists in SCLM.

    The SCLM administrator is responsible for the definition of the SCLM types. When you share a project with SCLM you need to know what type you are to use when storing objects in SCLM.

    Language

    When you add a file to SCLM you must store it with a certain language definition. Again the SCLM administrator is responsible for the definition of languages. This definition controls the behaviour of SCLM as files are transferred to and from the host system. Using the language definition it is possible to define whether a certain file type is long-name translated, stored as a binary object, or translated into ASCII or EBCDIC (native z/OS encoding). For example a language definition of JAVABIN may relate to a long name translated binary object. Alternatively, WEBHTML can be defined as representing a long-name translated, text file to be stored in ASCII. The number of language definitions is defined per project. Understanding which language to use is necessary to ensure that the file is stored and can be retrieved correctly from SCLM. The language also defines how SCLM builds an object.

    SCLM properties

    Any file that is under SCLM control will have a number of properties associated with it. These properties are effectively the mapping mechanism between the IDE file and its corresponding SCLM properties. When service calls are made to SCLM, this data is read to formulate the appropriate service parameters. You can view these from the Properties menu when you highlight an SCLM-controlled member from Eclipse.

    SCLM project structure

    When you share a project with SCLM you also need to nominate what development group you belong to. SCLM project structures are hierarchical in nature. A typical hierarchy can be:

    Figure 44. Multiple types


    Code is initially stored at the DEVELOPMENT level. After it has been successfully built and tested it may be promoted up to TEST. Following successful testing it may then be promoted to PRODUCTION. This generally represents the developed product. If a defect is found in the Production level code then those files that must be edited to fix the defect are copied down to the Development level and the build process starts again. All the code that makes up the application is not copied down to the Development level. SCLM keeps track of the elements that make up the build and at what level they reside.

    Within the Development level there may be multiple groups. This provides a means of separating out code stored at the development level. SCLM also provides controls for determining the behaviour of code stored in different development groups in terms of the ability to promote.

    ARCHDEF

    The structure of the IDE project is generally one composed of one or more IDE projects. By storing each of these IDE projects in a different SCLM type this structure is maintained. The ARCHDEF file then effectively defines the files that make up an IDE project. Each SCLM project can have multiple ARCHDEFs. It is possible for an ARCHDEF to reference other ARCHDEFs so that this multiple IDE project structure can be defined to the build process, the ARCHDEF being the principal means of defining a build list to SCLM. The closest analogy of this is that of a make process. The ARCHDEF lists the files that make up the build in addition to specifying a build script that will allow you to specify the location of external JARs or classes. For more information about this, see the User Manual section of the Online Help System.


    JAVA/J2EE concepts

    When an IDE project is created in the workspace, a project description file is automatically generated and stored under the name .project. This XML document contains descriptions of any 'builders' or 'natures' associated with the project. 'Builders' are incremental project builders that create some built state based on the project contents. As the contents of the project changes, this file will be updated. 'Natures' define and manage the association between a given project and a particular plug-in or feature.

    The .classpath file is a file that describes the path which is used to find external jars and classes that are referenced by the source code in your IDE project. The equivalent function during a build through SCLM Developer is defined with the CLASSPATH_JARS directive in the Ant build scripts. This directive will describe the path on the z/OS host that is used to find external jars and classes that are referenced by the source code in your IDE project.

    Both .classpath and .project are used to preserve your IDE project configuration so that it can be recreated in another workspace. For this reason it is recommended that both are checked into SCLM as part of the IDE project.

    An important aspect of project development, particularly in J2EE projects, is that a number of different forms of application executables can be created. Java project executables are often packaged as JAR, WAR, RAR or EAR files.

    JAR files typically relate to standard Java applications or Enterprise Java Beans (EJB).

    WAR files are created for web applications. Typically these are composed of Java servlets, JSPs, and HTML files. WAR applications are often the front end of web-based applications. These applications may reference other JARs such as EJBs for specific services. Each WAR file contains a web.xml file. This describes the composition of the WAR application in terms of Java, HTML, and the library services that it uses.

    RAR file development is not currently supported in Developer Toolkit.

    EAR files represent enterprise applications. These applications are composed of JAR and WAR files. In J2EE language, the creation of the EAR file is the assembly of its constituent JAR and WAR files. This method of assembly allows EAR applications to be created which are in effect made up of specific components (JAR/WAR). The actual composition of the application is described in the application.xml file. The EAR file itself is not a standalone executable object. The EAR file must be installed in a J2EE container such as Websphere Application Server (WAS). The installation of the EAR file is referred to as deployment. A deployed EAR application can be accessed via the WAS environment. Deployment is a separate process from that of the build. Deployment involves the physical installation of the EAR application.

    When developing J2EE applications it is therefore possible that it will involve the development of a number of separate components such as WAR and JAR files. These files are then assembled together into an EAR file. The EAR file is then ready for deployment into a J2EE container (for example, WAS) for operation.

    Within the Eclipse workspace the projects are effectively proximate, that is within the IDE environment they can effectively refer to other IDE projects readily in terms of packaging. Within SCLM, each of these IDE projects (for example, WAR, JAR and EAR projects) need to be mapped into a single SCLM project, with each project differentiated through the use of a different SCLM type. The reason for this is that there are common file names used in many IDE projects such as .project, .classpath, web.xml and application.xml, so use of separate types allows these same named parts to exist in the same SCLM project. For more information about mapping, see Mapping J2EE projects to SCLM.

    From an SCLM perspective the development of the EAR application is best referenced through the use of a high-level ARCHDEF structure. Within SCLM the high-level ARCHDEFs, in many SCLM projects referred to as a package, are the apex of the ARCHDEF structure followed by the EAR application and lower level references (WAR and JAR files) that make up the EAR application. This structure enables the use of builds at both high and low level and also the use of full or conditional builds. The ARCHDEFs thus provide a means by which it is also possible to define the J2EE project elements within the SCLM project.


    Appendix B. Long/short name translation table

    Currently core SCLM does not support the use of code storage with file (member) names greater than eight characters.

    Code such as Java and other PC client code inherently have much greater name lengths and even incorporate path information (packaging) as part of the name. This causes the need for code with named parts greater than eight characters to go through a long/short name conversion utility to enable these parts to be stored within SCLM with an eight character (or less) name length.

    A longname to shortname translation table stores the matching longnames (real name) against the short names (as stored in SCLM). These tables are controlled and accessed by SCLM and reside in a VSAM data set. This functionality has been introduced into SCLM with the PTF that addresses APAR OA11426 for z/OS V1.4 and later. For z/OS V1.8 and later, this PTF is not required.

    The conversion algorithm follows these steps:

    1. The translate prefix consists of the first two characters (uppercase) of the long program/file name (that is, the last file name after "/" character in multi-packaging format). If the first two characters are not valid as a prefix for a host member name (because they contain invalid special characters) then the prefix is "XX". Special cases, such as a single character alphabetic name (/u/test/A or /u/test/A.java), are also assigned the prefix of "XX".
    2. The last six characters are numerically assigned the next numeric sequential number available in the translate table.

    For example:

    Longname Shortname in SCLM PDS or PDSE
    com/ibm/workbench/testprogram.java TE000001
    source/plugins/Phantom/.classpath XX000001

    Technical summary of the SCLM Translate program

    SCLM program FLMLSTRN was created to read and update the VSAM translation table. SCLM Developer Toolkit uses this program to read and update correlating longnames and shortnames.

    The VSAM file used to store the translation table is a variable length KSDS with an alternative index and path defined. A sample job is provided in SCLM to allocate this VSAM file.

    The internal structure of the VSAM cluster is:

      1 ls_record,
        3 ls_short_name  char(08),
        3 ls_lngname_key char(50),
        3 ls_long_name   char(1024);
    

    Sample JCL to allocate the Long/Short name translation VSAM file can be seen in Step 6: Configure long/short name table VSAM file.

    Note: The following technical information about SCLM Translate table function calls is supplied as information only and is not required to enable any SCLM Developer Toolkit functionality.

    The program FLMLSTRN is invoked via the ISPF SELECT service passing one of the parameters listed in Figure 45.

    Syntax

      "SELECT PGM(FLMLSTRN) PARM(keyword)"
    

    Invocation example:

      "SELECT PGM(FLMLSTRN) PARM(TRANSLATE)"
    

    Figure 45.

    Long/Short name translation parameters
    Keyword Record Processing Description
    FINDLONG Single Find a long name for a given short name
    FINDSHORT Single Find a short name for a given longname
    TRANSLATE Single Find a short name if it exists or allocate a new short name if it does not exist
    MIGRATE Multiple Search for multiple longnames
    IMPORT Multiple Search for multiple shortnames

    Single long/short name record processing

    FINDLONG Processing

    FINDSHORT Processing

    TRANSLATE Processing

    The processing is the same as for FINDSHORT.


    Multiple long/short name record processing

    MIGRATE and IMPORT are functions that were introduced to improve performance with large numbers of longnames being translated (MIGRATE) or large numbers of shortnames being searched for (IMPORT).

    Both functions, "MIGRATE" and "IMPORT", read a variable blocked sequential file with LRECL=1036 which is allocated as DD LSTRNPRC.

    Before invocation this file will contain the shortnames or longnames depending on the function called and in the correct format and column.

    After invocation LSTRNPRC will contain both the shortname and correlating longname.

    The format of the file is:

      1 pr_record,
        3 pr_short_name  char(08),
        3 pr_long_name   char(1024);
    

    IMPORT processing

    MIGRATE processing

    Here is some sample REXX to invoke the long/short name translation process:

    Figure 46. Sample REXX for Translate module invocation


    /* REXX **************************************************************/
    /* Sample to translate longname to a shortname */
    /*********************************************************************/
       Address TSO
       "FREE FI(LSTRANS)"
       "FREE FI(LSTRNPTH)"
       "ALLOC DD(LSTRANS) DA('BWB.LSTRANS.FILE') SHR REUSE"
       "ALLOC DD(LSTRNPTH) DA('BWB.LSTRANS.FILE.PATH') SHR REUSE"
       /* Create shortname for longname com/ibm/phantom.txt */
       FLMLSLNG = "com/ibm/phantom.txt"
       Address ISPEXEC "VPUT (FLMLSLNG) PROFILE"
       Address ISPEXEC "SELECT PGM(FLMLSTRN) PARM(TRANSLATE)"
       LSRC=RC
       If LSRC > 0 Then
       Do
          Address ISPEXEC "VGET (FLMLSERR,FLMLSER1) PROFILE"
          Say "LS ERROR LINE 1 ==>" FLMLSERR
          Say "LS ERROR LINE 2 ==>" FLMLSER1
          Return
       End
       Else
       Do
          Address ISPEXEC "VGET (FLMLSSHR,FLMLSLNG) PROFILE"
          Say " Shortname = " FLMLSSHR
          Say " Longname = " FLMLSLNG
       End
       Address TSO
       "FREE FI(LSTRANS)"
       "FREE FI(LSTRNPTH)"
    

    Appendix C. Messages and codes

    BWB00001ERROR in Allocation/Write to : data set name

    Explanation: An attempt to write the client parameter input to a temporary data set has failed.

    User Response: Review the operations log to further determine any errors.

    BWB00002Processing terminates

    Explanation: The requested function is cancelled and the ISPF/SCLM session is ended.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00003Following function has failed : function

    Explanation: Indicated the failing Function or operation request.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00004ISPF initialization has failed

    Explanation: The ISPF/SCLM session has failed to initialize. Processing on that function request is terminated.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00005Review your ISPF properties and Loadlib

    Explanation: Additional error messaging to indicate a reason for ISPF/SCLM initialization failure.

    User Response: The Systems programmer should review the ISPF.conf configuration file in the z/OS UNIX System Services file system CONFIG directory to determine the correct ISPF data set allocations have been set.

    BWB00006Ensure the Loadlib data set is APF authorized

    Explanation: The SCLM Developer Toolkit Loadlib data set may not be APF authorized resulting in ISPF/SCLM initialization failure.

    User Response: The Systems programmer should ensure the Loadlib is APF authorized or that no non-APF authorized data sets have been included in the HTTP server STEPLIB.

    BWB00007ISPF or SCLM service has abended

    Explanation: An ISPF/SCLM internal error has caused the session to end. The function request is cancelled.

    User Response: Review the operations log to further determine any errors.

    BWB00008Review Log for error details

    Explanation: Review the Client operations log for further messages or error analysis.

    User Response: To review the operations log, right click and select TEAM then operations log.

    BWB00009Error reading ISPF.conf

    Explanation: The configuration file ISPF.conf located in the z/OS UNIX System Services file system at installdirectory/ISPF.conf can not be read

    User Response: The Systems Programmer should ensure the configuration file exists and the user has read access.

    BWB00010Ensure file exists in directory specified by environment variable CGI_VCMPATH set in the server configuration

    Explanation: Configuration files such as ISPF.conf should be located in the directory specified by CGI_VCMPATH

    User Response: The Systems Programmer should check CGI_VCMPATH in httpd.env.

    BWB00011If error on ISPSPROF table then a background session may already be using the profile data set : data set name

    Explanation: Two concurrent sessions have been initiated and using the same ISPF profile data set.

    User Response: Check that another session is not running concurrently and preventing this session to establish.

    BWB00012Error in ISPF data set allocation : See error message below

    Explanation: An error in one of the ISPF data set allocations. Specific allocation error messages follow.

    User Response: The Systems Programmer should check ISPF.conf to ensure valid ISPF DD names and correct ISPF data sets.

    BWB00013Error in allocating the following DD and data set names : error message

    Explanation: The following data set can not be allocated to that DD name.

    User Response: The Systems Programmer should review the DD and data set allocation (ISPF.conf).

    BWB00014Verify that the ISPF configuration file ISPF.conf on the host is correct

    Explanation: An error in the ISPF data set allocations has occurred.

    User Response: The Systems Programmer should check ISPF.conf to ensure valid ISPF DD names and correct ISPF data sets.

    BWB00015*** Edit cancelled ***

    Explanation: EDIT processing has been cancelled due to an error.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00016Selected group not in development group hierarchy

    Explanation: The group selected is not valid as it does not reside in the USERS development hierarchy.

    User Response: Choose a valid group or operate from a different development group.

    BWB00017Unable to locate data set for : project group type

    Explanation: An error has occurred in locating a valid data set for that particular project/group/type.

    User Response: The SCLM administrator should check that a valid data set exists for that project/group/type.

    BWB00018*** Edit/Browse cancelled ***

    Explanation: An error has occurred in EDIT/BROWSE and the function is cancelled.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00019Member selected resides in lower hierarchy group

    Explanation: Selected member is not valid for operation as a valid member resides in a lower hierarchy group.

    User Response: Select member from lower hierarchy group.

    BWB00020The member should be selected from group: group

    Explanation: Additional messaging indicating which member should be selected for this operation.

    User Response: Select recommended member and repeat function.

    BWB00021Repository view mismatch

    Explanation: The USERS repository view and SCLM are not synchronized.

    User Response: Re-populate project to synchronize the view with SCLM.

    BWB00022Re-filter using Populate SCLM Project View or re-synchronize IDE view

    Explanation: The repository view or IDE view are not synchronized with SCLM.

    User Response: Re-populate project if explorer mode or developer mode are not synchronized. Otherwise re-synchronize IDE view.

    BWB00023*** Add new member function cancelled ***

    Explanation: The Add new member function has been cancelled due to errors.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00024Member does not reside in user's development group

    Explanation: The SCLM operation carried out is not valid as the member does not reside in the user's development group.

    User Response: Select a valid member.

    BWB00025*** No member to Browse ***

    Explanation: A valid SCLM member with text was not found.

    User Response: None

    BWB00026*** Member copy into z/OS UNIX System Services file system failed ***

    Explanation: The operation involves copying the member to the z/OS UNIX System Services file system. This operation failed.

    User Response: The Systems programmer should review the operations log for further explanation of this error.

    BWB00027Edit failed - copy failure : data set name(member) to data set name

    Explanation: As part of the EDIT function a copy of the SCLM member to a temporary data set has failed.

    User Response: Review additional error messages and the operations log for further information.

    BWB00028Error returned on member lock

    Explanation: SCLM lock on member for edit failed. Member may already be locked for edit by another user.

    User Response: Issue an SCLM status to determine if member is locked for EDIT by another user.

    BWB00029Binary formatted members not valid for Edit

    Explanation: Binary object type members of NON-EDIT are not eligible to be selected for EDIT. Function cancelled.

    User Response: None

    BWB00030*** Copy to z/OS UNIX System Services file system failed ***

    Explanation: The operation involves copying the member to the z/OS UNIX System Services file system. This operation failed.

    User Response: The Systems programmer should review the operations log for further explanation of this error.

    BWB00031*** Error in ASCII/EBCDIC translation ***

    Explanation: An error has occurred in the translation from ASCII to EBCDIC when checking in a file.

    User Response: Ensure the file to be checked in is not empty or contains valid special characters. Otherwise the ASCII EBCDIC code pages used should be verified.

    BWB00032*** Error in member copy to SCLM ***

    Explanation: The member being checked in wasn't successfully copied into the z/OS data set. The operation has failed.

    User Response: The Systems programmer should review the operations log for further explanation of this error.

    BWB00033*** Save function failed ***

    Explanation: The SAVE function has failed.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00034*** Save function cancelled ***

    Explanation: The check-in function to SCLM was cancelled.

    User Response: Review additional error messages and the operations log to determine reason.

    BWB00035Member not previously locked for Edit

    Explanation: Associated with the SAVE / CHECK-IN function where a member has to be SCLM locked or checked out first.

    User Response: The USER should lock or check-out the member first using the EDIT function.

    BWB00036Error returned from ACCTINFO status on member

    Explanation: The requested function internally performs an SCLM ACCTINFO request which has failed.

    User Response: Review additional error messages and the operations log to determine error.

    Check the validity of the member.

    BWB00037*** Save function successful ***

    Explanation: The SAVE or Check-in operation was successful.

    User Response: None

    BWB00038Error returned on SAVE for :


    MEMBER = member
    PROJECT = project
    GROUP = group
    TYPE = type

    User Response: Lists member details for the failed SAVE request.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00039Delete successful for member : member

    Explanation: The selected member was deleted successfully.

    User Response: None

    BWB00040Delete failed for member : member

    Explanation: Delete function failed for requested member.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00041Error returned on delete

    Explanation: The SCLM delete command has returned a non-zero return code.

    User Response: Review additional error messages and the operations log to determine error.

    BWB00042Please check log file for information messages

    Explanation: Additional messaging may be contained in the operations log.

    User Response: To review the operations log, right click and select TEAM then operations log.

    BWB00043Unlock failed for member : member

    Explanation: The SCLM unlock command on a cancel EDIT request has failed.

    User Response: Review the SCLM status of the member.

    BWB00044Unlock successful for member : member

    Explanation: A member previously locked for EDIT has been successfully unlocked.

    User Response: None

    BWB00045Failed allocation of build parms DSN : data set name

    Explanation: The temporary data set USERID.TEMP.VCMISPF containing the build parameters can not be allocated as DISP=SHR. Processing terminates.

    User Response: The Systems programmer should review the operations log for additional error messages.

    BWB00046Unable to read build parameters

    Explanation: The temporary data set containing the build parameters was allocated but an error occurred while reading or the data set was empty.

    User Response: The Systems programmer should review the operations log for further explanation of this error.

    BWB00047Warning - Unable to allocate build messages data set

    Explanation: The specified Build message data set can not be allocated. Processing continues.

    User Response: Review the Build messages data set that was specified by the user from the Build request. Review z/OS SYSLOG for any security violations.

    BWB00048Warning - Unable to allocate build report data set

    Explanation: The specified Build report data set can not be allocated. Processing continues.

    User Response: Review the Build report data set that was specified by the user from the Build request. Review z/OS SYSLOG for any security violations.

    BWB00049Warning - Unable to allocate build list data set

    Explanation: The specified Build list data set can not be allocated. Processing continues.

    User Response: Review the Build list data set that was specified by the user from the Build request. Review z/OS SYSLOG for any security violations

    BWB00050Warning - Unable to allocate build exit data set

    Explanation: The specified Build exit data set can not be allocated. Processing continues.

    User Response: Review the Build exit data set that was specified by the user from the Build request. Review z/OS SYSLOG for any security violations

    BWB00051Build failed

    Explanation: The build request has failed

    User Response: Review additional error messages and the operations log to determine error.

    BWB00052Error reading build messages

    Explanation: The Build messages data set can not be read.

    User Response: Review operations log for successful data set allocation.

    BWB00053Error reading build report

    Explanation: The Build report data set can not be read.

    User Response: Review operations log for successful data set allocation.

    BWB00054Error reading build listing

    Explanation: The Build listing data set can not be read.

    User Response: Review operations log for successful data set allocation.

    BWB00055Error reading J2EEBLD report

    Explanation: The Build J2EEBLD report data set can not be read.

    User Response: Review operations log for successful data set allocation.

    BWB00056BATCH skeleton error (Administrator customization error)

    Explanation: The SCLM batch skeletons FLMDSU$ FLMB$ can not be included. Build processing terminates.

    User Response: Review MSG BWB00057

    BWB00057Check SCLMDT Skeleton concatenated in ISPSLIB as specified in the file ISPF.conf

    Explanation: Extended messaging from MSG BWB00056.

    User Response: The Systems programmer should check that the base SCLM skeletons are allocated to ISPSLIB in the z/OS UNIX System Services file system configuration file ISPF.conf

    BWB00058No BATCH submission information returned

    Explanation: No BATCH Job information was returned or captured from TSO.

    User Response: Review the z/OS SYSLOG to determine if a batch job was submitted successfully or the Job resides in an SDSF queue

    BWB00059*** Promote cancelled ***

    Explanation: The Promote function has been cancelled.

    User Response: Review MSG BWB00016

    BWB00060Warning - Unable to allocate messages data set

    Explanation: The temporary data set to receive SCLM messages USERID.VCM.TEMP.FLMMSG can not be allocated. Processing continues.

    User Response: The Systems programmer should review the operations or z/OS log for additional error messages.

    BWB00061Failed allocation of promote parms DSN : data set name

    Explanation: The temporary data set USERID.TEMP.VCMISPF containing the build parameters can not be allocated as DISP=SHR. Processing terminates.

    User Response: The Systems programmer should review the operations log for additional error messages.

    BWB00062Unable to read promote parameters data set

    Explanation: The temporary data set containing the build parameters was allocated but an error occurred while reading or the data set was empty.

    User Response: The Systems programmer should review the operations log for further explanation of this error.

    BWB00063Warning - Unable to allocate promote messages data set

    Explanation: The specified Promote message data set can not be allocated. Processing continues.

    User Response: Review the Promote messages data set that was specified by the user from the promote request. Review z/OS SYSLOG for any security violations.

    BWB00064Warning - Unable to allocate promote report data set

    Explanation: The specified Promote report data set can not be allocated. Processing continues.

    User Response: Review the Promote report data set that was specified by the user from the promote request. Review z/OS SYSLOG for any security violations

    BWB00065Warning - Unable to allocate promote exit data set

    Explanation: The specified Promote exit data set can not be allocated. Processing continues.

    User Response: Review the Promote exit data set that was specified by the user from the promote request. Review z/OS SYSLOG for any security violations

    BWB00066Warning - Unable to allocate Authcode messages data set

    Explanation: The temporary authcode messages data set USERID.VCM.TEMP.AUTHMSG can not be allocated. Processing continues.

    User Response: Review z/OS SYSLOG for any security violations

    BWB00067Ensure build was successful

    Explanation: Promote failed. Possible reason is incorrect Build map.

    User Response: Review previous build request or view build map.

    BWB00068Breeze is configured for this project, check log for Breeze messages

    Explanation: Informational message that the Breeze flag is set and to review additional Breeze messages.

    User Response: None

    BWB00069Error reading promote messages

    Explanation: The Promote messages data set can not be read.

    User Response: Review operations log for successful data set allocation.

    BWB00070Error reading promote report

    Explanation: The Promote report data set can not be read.

    User Response: Review operations log for successful data set allocation.

    BWB00071Populate view of project failed

    Explanation: Either Project Initialization has failed or the development group specified is not valid for the project.

    User Response: Review any additional SCLM messages in the operation log and check your development group, Project and filter parameters.

    BWB00072Reading ARCHDEF directly as no BLDMAP found

    Explanation: Populate project by ARCHDEF will generate the request using DBUTIL and the build map for the ARCHDEF. If no build map exists (that is, the ARCHDEF has not been built) then members will be read directly from the ARCHDEF.

    User Response: None

    BWB00073Only members in lowest hierarchy (latest) listed

    Explanation: Additional to MSG BWB00072. As there is no ARCHDEF build map from which to generate the report, the populate will only report on members at the lowest group in the hierarchy.

    User Response: If not acceptable then use a populate project filter other than ARCHDEF or build the ARCHDEF first to populate full list.

    BWB00074No Project view information returned

    Explanation: No project information was returned using the specified filters.

    User Response: Review your filter parameters.

    BWB00075Review your filter parameters

    Explanation: Information to MSG BWB00074.

    User Response: None

    BWB00076The following ARCHDEF include was not found in the hierarchy : include name

    Explanation: An INCLD statement for a member was found in the selected ARCHDEF but the member was not found in any group up the development hierarchy.

    User Response: If old or incorrect member then remove from ARCHDEF.

    BWB00077*** Update function failed ***

    Explanation: The update function failed as the member can not be locked for edit/update.

    User Response: Review SCLM status of member.

    BWB00078Error returned on LOCK

    Explanation: Unable to obtain lock on member for EDIT or Update.

    Member may already be locked (checked out) by another user.

    User Response: Review SCLM status of member.

    BWB00079*** Update function cancelled ***

    Explanation: Update is cancelled as member was not previously locked for edit.

    User Response: Review SCLM status of member.

    BWB00080Member not previously locked for edit

    Explanation: informational

    User Response: Retry function.

    BWB00081*** Update function successful ***

    Explanation: informational

    User Response: None

    BWB00082*** AUTHCODE retrieval failed ***

    Explanation: Unable to retrieve authcode on selected member.

    User Response: Review SCLM status of member.

    Review any SCLM messages in operation log.

    BWB00083*** AUTHCODE update failed ***

    Explanation: The update of authcode on the member has failed. Processing terminates.

    User Response: Review SCLM status of member.

    Review any SCLM messages in the operations log.

    BWB00084*** VERINFO command failed ***

    Explanation: The VERINFO request failed with a return code > 8.

    User Response: Review any SCLM messages in the operations log.

    BWB00085No Version records were found matching criteria

    Explanation: Informational

    User Response: None

    BWB00086*** VERRECOV command failed ***

    Explanation: A version recover request has failed with a return code > 0.

    User Response: Review any SCLM messages in the operations log.

    BWB00087*** VERDEL command failed ***

    Explanation: A version delete request has failed with return code > 0.

    User Response: Review any SCLM messages in the operations log.

    BWB00088Severe error in catalog search routine

    Explanation: An error has occurred in the IGGCSI00 Catalog search program with a project list request.

    User Response: The Systems programmer should review the operations and z/OS log for further error messages. Retry request.

    BWB00089Warning - No Projects returned on filter : project filter

    Explanation: Informational.

    User Response: Review project filter request.

    BWB00090Error reading translate table : file name

    Explanation: An error has occurred reading the translate table. Processing continues but there will be errors in the longname to shortname retrieval and updates.

    User Response: The Systems Programmer should verify correct translate table name: CGI_TRANTABLE variable in the httpd.env configuration file.

    Run the IVP to also verify installation.

    BWB00091Long/short name translation may be in error

    Explanation: A previous error with the Longname to shortname translation file has occurred.

    User Response: The Systems programmer should review the operations log for further error messages.

    BWB00092Error reading file : file name

    Explanation: The displayed z/OS UNIX System Services file system file contained the files to migrate can not be read. Migration terminates.

    User Response: Review the operations log for further error messages.

    BWB00093Error returned from SCLMINFO file allocation

    Explanation: Error on allocation of new temporary data set userid.vcm.temp.projinf

    DCB: SPACE(1,1,20) TRKS RECFM(FB) LRECL(40) BLKSIZE(27960) VIO

    User Response: Review the z/OS SYSLOG for additional messages for data set allocation failure.

    BWB00094Error returned from SCLMLOAD file allocation

    Explanation: Unable to allocate DISP=SHR the data set Project.projdefs.load.

    User Response: Determine the data set Project.projdefs.load exists, where project is the project name specified.

    BWB00095Error returned on call to ISRFLMGI

    Explanation: Unable to call ISPF/SCLM module ISRFLMGI for retrieving group information for project.

    User Response: None

    BWB00096Unable to re-allocate SCLMINFO (no groups returned)

    Explanation: Unable to allocate temporary data set for project group information retrieval.

    User Response: Review the operations log for further error messages.

    BWB00097Unable to read SCLMINFO (no groups returned)

    Explanation: Unable to read allocated SCLMINFO temporary data set. No project information will be returned.

    User Response: Review the operations log for further error messages.

    BWB00098Unable to retrieve the list of groups in the specified project

    Explanation: No group information for selected project is returned due to function failure.

    User Response: Review the operations log for further error messages.

    BWB00099Build map deleted for member : member

    Explanation: Informational.

    Delete request has deleted build map.

    User Response: None

    BWB00100Jobid must have valid Jobname in request

    Explanation: No Job name was passed through in JOB status request with Job ID.

    User Response: Retry with valid JOB Name specified.

    BWB00101No job name was specified. Your user id will be used by default

    Explanation: No Job name or Job ID details were passed. Function will report on all jobs starting with USERID as Jobname.

    User Response: None

    BWB00102For job retrieval a valid Jobname and Jobid must be provided

    Explanation: No valid Job name / Job ID was passed for Job output retrieval.

    User Response: Retry with valid Job name / Job ID.

    BWB00103No job output found

    Explanation: The requested Batch job was not found on the SDSF queue.

    User Response: Check on z/OS in SDSF if the batch job still resides on an output queue or has been purged.

    BWB00104Warning - Refer to additional SCLM messages

    Explanation: Additional SCLM warning messages have been issued.

    User Response: View additional SCLM messages in the operations log.

    BWB00105Error - SCLM is unable to load the SCLM table

    Explanation: Error on SCLMINFO call for project/Project definition.

    User Response: Check that Project and project definition are valid.

    BWB00106Check that the following project definition is valid: Project

    Explanation: Informational.

    Extends MSG BWB00105.

    User Response: Check that Project and project definition are valid.

    BWB00107Error - The maximum application ID limit was exceeded

    Explanation: SCLMINFO request has returned return code 12.

    User Response: Check that Project and project definition are valid. Inform SCLM administrator of error.

    BWB00108Errors initializing project : Project

    Explanation: Extends MSG BWB00107

    User Response: Reference MSG BWB00107.

    BWB00109Error - An incorrect version of the SCLM table was loaded

    Explanation: SCLMINFO request has returned return code 16.

    User Response: Check that Project and project definition are valid. Inform SCLM administrator of error.

    BWB00110Error - An incorrect parameter list was passed

    Explanation: SCLMINFO request has returned return code 32.

    User Response: Check that Project and project definition are valid. Inform SCLM administrator of error.

    BWB00111Error - Refer to SCLM messages manual on SCLMINFO codes

    Explanation: The SCLM messages manual will give additional information about the SCLMINFO return codes.

    User Response: Review the SCLM messages manual.

    BWB00112No project specific entries in project config file : file name

    Explanation: Informational: The SITE.conf file has not been tailored for use.

    User Response: None

    BWB00113Failed allocation of migrate parameters DSN : data set name

    Explanation: The temporary MIGRATE data set USERID.TEMP.MIGRATE.VCMISPF can not be allocated DISP=SHR. Processing terminates.

    User Response: The Systems programmer should review the operations log for additional error messages.

    BWB00114Failed read of migrate parameters

    Explanation: Error reading allocated parameter data set.

    User Response: The Systems programmer should review the operations log for additional error messages.

    BWB00115Error on directory : directory name

    Explanation: Error in creating or locating specified directory in z/OS UNIX System Services file system which is used to process the current function.

    User Response: The Systems programmer should review the operations log for additional error messages.

    BWB00116PUT command failed for the following : member info

    Explanation: A copy of a member from an SCLM data set into a z/OS UNIX System Services file system directory has failed.

    User Response: Check SCLM status of member.

    Review the operations log for additional error messages.

    BWB00117Error threshold of 5 errors reached in copy

    Explanation: An error threshold of 5 bad member copies between SCLM and the z/OS UNIX System Services file system directory has occurred in the Java/J2ee build translators. Processing terminates.

    User Response: Review the operations log for additional error messages.

    Rectify problem and try function request again.

    BWB00118Errors in code page conversions - Review LOG

    Explanation: Errors have occurred in the ASCII / EBCDIC code page conversions.

    User Response: Review the operations log for additional error messages.

    BWB00119The JAR command was unable to create file name

    Explanation: An error has occurred in creating a java JAR file. This function uses java to JAR up a compression file for transferring files across the network.

    User Response: Review the operations log for additional error messages.

    The Systems Programmer should ensure a valid java path exists in httpd.env and check for space problems within the z/OS UNIX System Services file system directory WORKAREA.

    BWB00120JAVA PATH in httpd.env file may not be valid. Check with your Administrator

    Explanation: An error has occurred is issuing a JAVA command.

    User Response: The Systems Programmer should ensure a valid java path exists in httpd.env for the HTTP server.

    BWB00121Error found in DBUTIL report - Review LOG

    Explanation: A failure has occurred with an SCLM DBUTIL request for producing a member list. Further error messages may be displayed.

    User Response: Review the operations log for additional error messages.

    BWB00122No project information returned by filter

    Explanation: The USER specified filter list has returned no project information.

    User Response: Review your filter parameters and try again.

    BWB00123SCLM import successful for the following number of members : number of members

    Explanation: Informational

    User Response: None

    BWB00124No files to migrate specified in migrate file : file name

    Explanation: No files were found to be migrated.

    User Response: If an error review the operations log for additional error messages.

    BWB00125Invalid Host name convention for : long name

    Explanation: The file to be stored is not defined as a long language definition but is not a valid Host name (8 characters or less). This file will not be stored in SCLM.

    User Response: If the file needs to be stored as a long language definition, (that is, converted to a short name) then ensure the language definition matches the LONGLANG keywords in TRANSLATE.conf (see the administrator).

    BWB00126Invalid shortname conversion for : long name

    Explanation: An error occurred within the translate file in creating a shortname.

    User Response: Review the operations log for further errors. Report this problem to the system programmer or SCLM administrator.

    BWB00127Check access permissions on translate table : file name

    Explanation: Redundant message.

    User Response: Ignore

    BWB00128Error threshold reached in short name

    Explanation: The error threshold of 5 shortname error conversions has been reached, the migrate process terminates.

    User Response: Review the operations log for further errors. Report this problem to the system programmer or SCLM administrator.

    BWB00129Member being migrated already exists - not migrated. Member : member

    Explanation: An attempt to migrate in a member was made where the member already exists in the group hierarchy and the force option was not used.

    User Response: If needed members can be force migrated setting the 'force' flag on from the migrate panel. Warning: this is not advised as normal checkout/checkin processing should be used as existing members will be overlayed.

    BWB00130Copy failed : data set name 1 to data set name 2

    Explanation: A copy of an SCLM member from the z/OS UNIX System Services file system to an SCLM data set has failed.

    User Response: The Systems Programmer should check the output data set is valid and there are no space problems or security violations.

    BWB00131Check MVS SYSLOG for possible security violation

    Explanation: Informational: extends BWB00130.

    User Response: Inform Systems Programmer of this message.

    BWB00132Error threshold of 20 errors reached in copy

    Explanation: For a migrate or import the error threshold of 20 has been reached for copy failures from z/OS UNIX System Services file system to/from SCLM. Processing terminates.

    User Response: Review the operations log for further errors. Report this problem to the system programmer or SCLM administrator.

    BWB00133Error reading migrate Messages

    Explanation: In Migrate processing an error occurred when reading the Messages data set. Processing continues but Migrate messages will not be included in the display output.

    User Response: Review the operations log for additional error messages.

    BWB00134SCLM migration successful for the following number of files : number of files

    Explanation: Informational

    User Response: None

    BWB00135Migration message data set : data set name

    Explanation: Informational

    User Response: None

    BWB00136Migration report data set : data set name

    Explanation: Informational

    User Response: None

    BWB00137SCLM migration unsuccessful for the following number of files : number of files

    Explanation: Errors occurred with a number of files during migration processing and are listed here. Migration may have only partially succeeded for some files/members.

    User Response: Review the operations log for additional error messages.

    BWB00138Refer to migration message data set : data set name

    Explanation: Migration messages have been written to this data set on z/OS for reference.

    User Response: Review the migration data set if required.

    BWB00139SCLM Update error for project architecture definition : ARCHDEF name

    Explanation: An ARCHDEF was selected to add migrating members to but the SCLM update to the ARCHDEF has failed.

    User Response: Check the ARCHDEF selected within SCLM for errors and review the operations log for further errors. Archdef may have to be manually updated with members if required.

    BWB00140Following project ARCHDEF updated : ARCHDEF name

    Explanation: Informational:

    Indicated ARCHDEF has been updated with migration members.

    User Response: None

    BWB00141Error occurred reading ARCHDEF : ARCHDEF name

    Explanation: The ARCHDEF member to be updated with migrating members already exists but the read has failed. Migration continues without ARCHDEF update.

    User Response: Check the validity of the selected ARCHDEF. Archdef may have to be manually updated with members if required.

    BWB00142Error occurred updating ARCHDEF : ARCHDEF name

    Explanation: An ARCHDEF was selected to add migrating members to but the SCLM update to the ARCHDEF has failed.

    Bad allocation of ARCHDEF member at the development level.

    User Response: Check the ARCHDEF selected within SCLM for errors and review the operations log for further errors. Archdef may have to be manually updated with members if required.

    BWB00143UNJAR failed on following file : file name

    Explanation: An error has occurred in unzipping a file using the java JAR command. This function uses java to UNJAR a compression file for transferring files across the network.

    User Response: Review the operations log for additional error messages.

    The Systems Programmer should ensure a valid java path exists in httpd.env and check for space problems within the z/OS UNIX System Services file system directory WORKAREA.

    BWB00144Check CGI_DTWORK variable in httpd.env with your administrator

    Explanation: The VCMPATH specified in the httpd.env file may not be correct.

    The Environment variable CGI_VCMPATH determines the HOME directory path where the configuration files reside for SCLM Developer Toolkit.

    This was determined by the installation directory specified in installation job BWBINST1. By default /var/SCLMDT.

    User Response: Systems programmer to investigate customization.

    BWB00145J2EEPUT in httpd.conf must be CGI_DTWORK/WORKAREA/*

    Explanation: The httpd.conf directive must be correct for J2EEPUT.

    User Response: Systems programmer to investigate customization

    BWB00146Error reading listing file : file name

    Explanation: Files to be migrated are contained in a z/OS UNIX System Services file system listing file. An error occurred while reading this file and migration processing terminates.

    User Response: Systems programmer should check z/OS UNIX System Services file system file permissions for specified user and available space.

    BWB00147Error in ASCII/EBCDIC conversion : file name

    Explanation: An error has occurred during an ASCII to EBCDIC file conversion. DT uses the iconv routine within z/OS UNIX System Services file system to code page convert.

    User Response: Systems programmer should check ASCII/EBCDIC customization parameters in TRANSLATE.conf. Check file being converted for special characters or empty file.

    BWB00148Invalid hostname structure (directory/filename)

    Explanation: Host file structure does not contain a '/' as first character.

    User Response: Review operations log to view Host File name passed to transfer routine.

    BWB00149 An incorrect value was received by the file transfer service: DIRECTION= direction

    Explanation: The direction keyword is not valid for file transfer. Valid direction keywords are TOHOST or FROMHOST.

    User Response: Review operations log for direction keyword passed and try again.

    BWB00150An incorrect value was received by the file transfer service: FILETYPE= file type

    Explanation: The filetype keyword for transfer is not valid. Valid filetype is BINARY or TEXT.

    User Response: Review operations log for filetype keyword passed and try again.

    BWB00151ZIP option only valid for TOHOST transfer

    Explanation: ZIP option (ZIP = yes) is only valid for transfer direction TOHOST.

    User Response: Retry operation without ZIP flag set if transferring from host.

    BWB00152ZIP option only valid for BINARY transfer

    Explanation: ZIP = YES has been set for transferring a file other than of filetype BINARY. This is not valid.

    User Response: Retry operation without ZIP flag set if transferring text file.

    BWB00153Check valid host name or file permissions

    Explanation: Accompanies MSG BWB00130.

    Copy has failed.

    User Response: Review that the file permissions on the z/OS UNIX System Services file system directories or Host file name are valid.

    BWB00154Unable to locate host directory : host directory

    Explanation: The host directory is part of the HOSTFILE name specified. The z/OS UNIX System Services file system directory does not exist.

    User Response: Systems programmer should check the z/OS UNIX System Services file system directory name specified.

    BWB00155UNZIP Failed on following file : host file

    Explanation: An unzip has failed on the transferred file. SCLMDT uses the java JAR command to unzip (unjar) this file.

    User Response: The Systems Programmer should ensure a valid java path exists in httpd.env and check for space problems within the z/OS UNIX System Services file system directory WORKAREA.

    BWB00156ZIP File copied: directory

    Explanation: Informational

    User Response: None

    BWB00157Unable to delete z/OS UNIX System Services file system file : file name

    Explanation: The cleanup routine to delete z/OS UNIX System Services file system workarea files after operation has completed has failed.

    User Response: Systems programmer should check listed file and delete/remove manually if required.

    BWB00158Select DETAILS>> button for build messages, reports, listings

    Explanation: Informational

    User Response: Select DETAILS to view build messages, reports and listings.

    BWB00159Select DETAILS>> button for promote messages and reports

    Explanation: Informational

    User Response: Select DETAILS to view build messages, reports and listings.

    BWB00160Failed read of migrate job data set

    Explanation: The temporary skeleton file that is used for creating the batch job can not be read: USERID.TEMP.DWSKEL.

    Migration processing terminates.

    User Response: Review the operations log for additional error messages.

    BWB00161*** Temporary recover data set allocation failed ***

    Explanation: In version processing a temporary recovery data set: USERID.VCM.TEMP.RECOVER can not be allocated.

    User Response: Systems programmer should review the z/OS log for any data set allocation failures.

    BWB00162Ant build failure

    Explanation: In a Java or J2EE build an error has occurred running the Ant script in z/OS UNIX System Services file system. This may just be Java compile errors.

    User Response: Review the Ant build listing returned in the operations log to resolve any build errors.

    BWB00163Review Ant Listing in Log

    Explanation: Informational

    User Response: Review listing.

    BWB00164Review failure - Build continues

    Explanation: A copy of a member from an z/OS data set to a z/OS UNIX System Services file system file has failed. Build processing continues.

    User Response: Review the operations log for further error messages.

    BWB00165Member account record deleted from development group

    Explanation: During a checkout (lock) an SCLM member account record was created in the development group. The unlock or lock failure results in the account record being deleted.

    User Response: None

    BWB00166ADD new member cancelled as member exists at group : group

    Explanation: An add new member was attempted but the member already resides up the group hierarchy chain. Processing terminates.

    User Response: None

    BWB00167Error in shortname translation

    Explanation: An error has occurred in translating the longname file to an SCLM host shortname.

    User Response: Review the operations log for further error messages.

    BWB00168Ensure check-in member was not an empty file

    Explanation: A code page translation error occurred when saving a file/member. Ensure the file saved was not an empty file.

    User Response: Check file not empty otherwise review operations log for further error messages.

    BWB00169Member being migrated already exists - not migrated. Member : member

    Explanation: A member was selected to be migrated but already exists in the group hierarchy chain.

    User Response: Use normal EDIT/checkout processing, otherwise use the migrate command with the force flag set. Warning this is not advised as previous versions of the member may be overwritten.

    BWB00170Error threshold of 5 errors reached in ASCII/EBCDIC conversion

    Explanation: An error threshold of 5 members being migrated has resulted in code page conversion errors. Migrate processing terminates.

    User Response: Review the operations log to determine errors with migrated members.

    BWB00171No members selected to copy and migrate

    Explanation: There were no valid members selected to be migrated into SCLM. Processing terminates.

    User Response: If this is an error then review the operations log for further error messages.

    BWB00172Promote has Failed - Check Promote messages

    Explanation: The promote has failed. Promote messages will be returned in the log or reside in the promote messages data set if specified in the request.

    User Response: Review the failing messages.

    BWB00173ERROR - Unable to allocate temp translate data set

    Explanation: For migrate and import the files requiring long/short name conversion are written to a temporary sequential data set DD LSTRNPRC of attributes SPACE(1,1) RECFM=VB LRECL=1036 UNIT=VIO. This data set can not be allocated. Processing terminates.

    User Response: Systems Programmer should check the z/OS SYSLOG for any data set allocation errors or violations.

    BWB00174ERROR - In translate table routine : FLMLSTRN

    Explanation: A shortname longname translation has occurred calling the translate module FLMLSTRAN. Additional error messages will be displayed.

    User Response: Review the operations log for additional error messages and reasons provided.

    BWB00175No associated longnames will be displayed

    Explanation: A previous error in retrieving longnames has occurred and any longnames associated with an SCLM host shortname will not be displayed in the project view.

    User Response: Review the operations log for other error messages pertaining to translation services.

    BWB00176WARNING in EBCDIC/ASCII conversion. Unprintable characters or empty file

    Explanation: An EBCDIC to ASCII code page translation error has occurred. Likely causes are unprintable special characters or an empty file.

    User Response: View the member being translated. Special characters or null characters (X'00') may cause this error when browsing/editing a file.

    BWB00178Warning - Unable to allocate data set:

    Explanation: Failure in allocating data set on z/OS host

    User Response: Review operations and z/OS systems log for further error messages . Contact your SCLM administrator for assistance.

    BWB00179No records returned for DBUTIL report

    Explanation: An SCLM DBUTIL report was run for this function call but failed to return any records.

    User Response: Warning only - Review your filters or parameters in request.

    BWB00180Accounting record and Build map deleted for member:

    Explanation: The SCLM accounting record and build map have been deleted for that member at the requested group.

    User Response: Informational only.

    BWB00181Failed allocation of DBUTIL parameter data set:

    Explanation: Failure in allocating data set PREFIX.SCLMDT.VCMISPF on z/OS host. Function failed.

    User Response: Review operations and z/OS systems log for further error messages. Contact your SCLM administrator for assistance.

    BWB00182Failed read of DBUTIL parameters

    Explanation: Failure in read of temporary data set PREFIX.SCLMDT.VCMISPF . Function failed.

    User Response: Review operations and z/OS systems log for further error messages. Contact your SCLM administrator for assistance.

    BWB00183Selected file does not exist in SCLM project

    Explanation: The CLASS, JAR, WAR, or EAR specified in the request was not located in the SCLM project hierarchy.

    User Response: Review your file name requested. Re-run request.

    BWB00184The classpath directory specified in request is not valid.

    Explanation: The CLASS, JAR, WAR, or EAR specified in the request was not located in the SCLM project hierarchy.

    User Response: Ask the System administrator to check in the z/OS UNIX System Services that the directory specified exists. Also check that write access permissions on that data set for your user ID are set.

    BWB00185Read of member $GLOBAL of type J2EEBLD failed

    Explanation: Failure in trying to read the member $GLOBAL that should reside in SCLM type J2EEBLD.

    User Response: Ensure a $GLOBAL member exists in the SCLM project hierarchy in SCLM type J2EEBLD. Contact your SCLM administrator for assistance.

    BWB00186Ensure variables CGI_DTCONF, CGI_DTWORK, ANT_BIN and JAVA_BIN are set in $GLOBAL

    Explanation: One of the above property variables is not set in $GLOBAL. Function cancelled.

    User Response: Check all property variables are set and the format is correct. Re-run request. Contact your SCLM administrator for assistance.

    BWB00187Error reading J2EE build script member

    Explanation: Failure on reading the J2EE build script member specified in Type J2EEBLD.

    User Response: Review the operations log for further details on the build script. Ensure that the build script which is referenced by the ARCHDEF keyword SINC exists in the SCLM project in type J2EEBLD. Contact your SCLM administrator for assistance.

    BWB00188Variable SCLM_ARCHDEF not set in build script member

    Explanation: The property variable SCLM_ARCHDEF is not set in the J2EE build script or the format is incorrect.

    User Response: Review the operations log to read the J2EE build script mentioned. Ensure that property is set and re-run function request.

    BWB00189Ant build failed - Review Ant Listing in log

    Explanation: The JAVA/J2EE build has failed in the Ant build step on z/OS.

    User Response: Review the Ant listing which will list the compilation or build errors . Rectify project errors and re-run.

    BWB00190Variable SCLM_ANTXML not set in build script member

    Explanation: The property variable SCLM_ANTXML was not set in the build script or the format was wrong.

    User Response: Ensure the variable is set. SCLM_ANTXML should reference a skeleton Ant XML member in type J2EEBLD.

    BWB00191Error copying Ant XML member into z/OS UNIX System Services file system

    Explanation: An error occurred while copying the Ant XML member into the z/OS Unix file system for processing.

    User Response: Review the operations log for further errors. This copy is part of the build process. Contact your SCLM administrator for assistance.

    BWB00192Error reading Translation configuration file TRANSLATE.conf

    Explanation: Error in reading the TRANSLATE.conf configuration file located in the SCLMDT CONFIGURATION directory in the z/OS Unix file system.

    User Response: Ask the systems administrator to check a valid TRANSLATE.conf exists at the configuration directory (by default /etc/SCLMDT/CONFIG. Contact your SCLM administrator for assistance.

    BWB00193Errors in copying source members to z/OS UNIX System Services file system for build

    Explanation: There was an error in copying SCLM source members into the z/OS Unix file system for processing.

    User Response: Review the operations log to determine the members that failed. Ensure these members exist in SCLM . Review the z/OS systems log for further error messages. Contact your SCLM administrator for assistance.

    BWB00194Errors in processing HL architecture definition includes

    Explanation: Errors occurred while processing an INCL ARCHDEF within the ARCHDEF.

    User Response: Check with the SCLM administrator that the included ARCHDEF is valid. Review the operations log for further error messages.

    BWB00195Error on account record call (ACCTINFO) for J2EEBLD member

    Explanation: Error occurred on an SCLM ACCTINFO function request on the member.

    User Response: Ensure the member has a valid SCLM account record. It is possible the member may be corrupted. Contact your SCLM administrator for assistance.

    BWB00196No JAR, WAR, or EAR property name set in Build script

    Explanation: The function was expecting either JAR_FILE_NAME, WAR_NAME, or EAR_NAME properties to be set in build script.

    User Response: Check the nature of the project and ensure a valid property variable is set for that project in the build script.

    BWB00197Error in storing JAR, WAR or EAR details in profile variable

    Explanation: Internal error in build process occurred while storing archive file information in an ISPF profile variable.

    User Response: Review operations log for further error messages such as JAR, WAR or EAR was not created or other build failures. Contact your SCLM administrator for assistance.

    BWB00198BWBJ2OBJ - no generated Jar, War, or Ear found

    Explanation: The ARCHDEF translator J2EEOBJ can not locate a generated JAR WAR or EAR to store back into SCLM.

    User Response: Review the operations log for other build failure messages. Contact your SCLM administrator for assistance.

    BWB00199BWBJ2OBJ - LISTING file not copied to SCLM

    Explanation: Error encountered in copying build listing file into SCLM . Error occurred in ARCHDEF translator J2EEOBJ.

    User Response: Review the operations log for other build failure messages. Contact your SCLM administrator for assistance.

    BWB00200BWBJ2OBJ - Error in copying Jar, War, or Ear into SCLM

    Explanation: Error in copy of generated archive object (JAR, WAR,EAR) from z/OS Unix file system into SCLM.

    User Response: Review the operations log for other build failure messages. Contact your SCLM administrator for assistance.

    BWB00201Error copying object file from SCLM to z/OS UNIX System Services file system

    Explanation: An error occurred during the copy from SCLM of a class, JAR, WAR, or EAR into the classpath directory specified as part of the function request.

    User Response: Review the operations log for other error messages. From the log determine the SCLM file and ensure the member is valid. Check the destination classpath directory in the z/OS UNIX System Services file system exists and write permissions are set. Contact your SCLM administrator for assistance.

    BWB00202Error encountered for property SCLM_ANTXML in build script

    Explanation: Error occurred copying the customized Ant script referenced by property SCLM_ANTXML from SCLM into the z/OS Unix Services file system in the ANTCOPY procedure of the build.

    User Response: Review the operations log for further error messages. Ensure the member referenced by property SCLM_ANTXML in the build script exists in the SCLM hierarchy. Contact your SCLM administrator for assistance.

    BWB00204Warning - File(s) copied from higher in hierarchy than selected development group

    Explanation: The selected member was not found in the users development group but retrieved from further up the group hierarchy in SCLM.

    User Response: Informational only. The Messages or operations log should detail what group the member was retrieved from.

    BWB00205Invalid J2EE INCL architecture definition (no SINC keyword specified)

    Explanation: An INCL ARCHDEF was found inside the J2EE ARCHDEF which was not a valid J2EE ARCHDEF.This was determined not to be a valid JAVA/J2EE ARCHDEF as the SINC keyword was missing. Processing terminates.

    User Response: Validate that the INCL ARCHDEF is a JAVA/J2EE ARCHDEF . Ensure the format of the ARCHDEF is correct (Valid SINC , LKED, & OUT1 keywords).

    BWB00206Member referenced by SCLM_ANTXML in build script not found

    Explanation: The member referenced by property variable SCLM_ANTXML in the JAVA/J2EE build script was not found in the SCLM hierarchy.

    User Response: Ensure a valid member exists in the SCLM hierarchy and resides in SCLM type of J2EEBLD.

    BWB00207Verification error from SCLM user exit routine (CCVFY or VERCC)

    Explanation: The member referenced by property variable SCLM_ANTXML in the JAVA/J2EE build script was not found in the SCLM hierarchy.

    User Response: Check the log for any messages the local user exit may have provided. If the problem is not visable from the messages returned by the user exit contact your SCLM project administrator for assistance.

    BWB00208Report MODE only selected for DEPLOY

    Explanation: The user has initiated a DEPLOY in report mode only. Information on the Deploy script , destination and selected options will be returned. No Deploy processing takes place.

    User Response: Informational only.

    BWB00209Error reading J2EE Deploy script member

    Explanation: An error occurred reading the selected J2EE Deploy script from the SCLM hierarchy.

    User Response: Ensure the selected Deploy script exists and is valid in the SCLM hierarchy and resides in SCLM type J2EEBLD. Contact your SCLM administrator for assistance.

    BWB00210EAR file deployed from selected group

    Explanation: The EAR file was successfully deployed from the selected group.

    User Response: Information only

    BWB00211Deploy of EAR file has failed

    Explanation: The Deploy of the selected EAR file has failed.

    User Response: Review the operations log for further error details. Contact your SCLM administrator for assistance.

    BWB00212Review deploy listing if available

    Explanation: Review the deploy listing in the operations log for detailed information regarding success or failure of the deploy operation. The Deploy listing is the listing output from the Ant deploy script.

    User Response: Review the operations log for further error details. Contact your SCLM administrator for assistance.

    BWB00213Deploy of EAR file successful

    Explanation: The Deploy of the selected EAR has been successful.

    User Response: Review the messages or operations log for further information regarding the Deploy operation.

    BWB00214Error in copying Deploy Ant XML to z/OS UNIX System Services file system

    Explanation: An error occurred while copying the dynamically customized deploy Ant script from SCLM into the z/OS Unix Services file system for processing.

    User Response: Review the operations log for further error messages. Contact your SCLM administrator for assistance.

    BWB00215Error allocating Translate table

    Explanation: An error occurred while trying to allocate the short name / long name translate table in the deploy function.

    User Response: Reason messages regarding this error will be found in the operations log. Either ensure Variable TRANTABLE in $GLOBAL is set or check the data set referenced by variable TRANTABLE is correct. Contact your SCLM administrator for assistance.

    BWB00217Warning - No Data sets returned on filter:

    Explanation: The catalog search routine failed to return any data sets on the users requested data set filter.

    User Response: Revise the data set filter used and re-run.

    BWB00218Warning - No Members returned on filter:

    Explanation: No members were returned from the data set using the selected member filter.

    User Response: Informational only. If required revise selected filters.

    BWB00219Severe error in Library Management routines

    Explanation: While trying to list members by filter from the selected data set the Library managements services routines returned an error.

    User Response: Review the Operations log for further error messages. Review your member filter and re-run. Contact your SCLM administrator for assistance.

    BWB00220User not authorized for requested build

    Explanation: Build security is on for this project and the requesting user ID does not have security access for this selected build request. Processing terminates.

    User Response: Check with the SCLM security administrator.

    BWB00221User not authorized for requested promote

    Explanation: Promote security is on for this project and the requesting user ID does not have security access for this selected promote request. Processing terminates.

    User Response: Check with the SCLM security administrator.

    BWB00222See your SCLM security administrator

    Explanation: Informational regarding a function request security failure.

    User Response: Check with the SCLM security administrator.

    BWB00223If running in batch, check region size is greater than or equal to 128m

    Explanation: The Batch job has failed and the reason can be a memory allocation problem.

    User Response: Ensure the Region size is at least 128M (REGION=128M on the JOBCARD). Some J2EE applications may even require a minimum region size of 512M.


    Bibliography

    Publications referred to in this document:

    HTTP Server Planning, Installing and Using, SC31-8690

    P/390, R/390, S/390 Integrated Server: OS/390 New User's Cookbook, SG24-4757

    z/OS ISPF Software Configuration and Library Manager Project Manager's and Developer's Guide, SC34-4817

    z/OS ISPF Software Configuration and Library Manager Reference, SC34-4818

    z/OS Information Roadmap, SA22-7500

    z/OS UNIX System Services Command Reference, GA22-7802

    z/OS UNIX System Services Messages and Codes, GA22-7807

    z/OS UNIX System Services Planning, GA22-7800


    Notices

    This information was developed for products and services offered in the U.S.A.

    IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information about the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

    IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

    IBM Director of Licensing
    IBM Corporation
    North Castle Drive
    Armonk, NY 10504-1785
    U.S.A.

    Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one), and (ii) the mutual use of the information which has been exchanged, should contact:

    IBM Corporation
    Mail Station P300
    2455 South Road
    Poughkeepsie New York 12601-5400
    U.S.A.

    Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

    The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

    For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

    IBM World Trade Asia Corporation
    Licensing
    2-31 Roppongi 3-chome, Minato-ku
    Tokyo 106-0032, Japan

    The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

    This information can include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

    Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

    If you are viewing this information softcopy, the photographs and color illustrations may not appear.


    Trademarks

    The following are trademarks of International Business Machines Corporation in the United States, or other countries, or both.
    AIX
    CICS
    DB2
    Domino
    eServer
    IBM
    Intel
    Library Reader
    Lotus
    MVS
    OS/390
    Passport Advantage
    RACF
    Redbooks
    S/390
    WebSphere
    z/OS
    zSeries

    Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

    Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

    UNIX is a registered trademark of The Open Group in the United States and other countries.

    Windows is a trademark of Microsoft Corporation in the United States, other countries, or both.

    Other company, product, and service names may be trademarks or service marks of others.


    Glossary

    A

    accounting record
    An SCLM control data record containing statistical, historical, and dependency information for a member under SCLM control.

    alternate project definition
    A project definition that provides a version of the project environment which differs from the default project definition.

    architecture definition
    A means of organizing components of an application into conceptual units. It is SCLM's method of defining an application's configuration. It describes how the components of an application fit together and how they are used to drive both the build and promote functions. Architecture definitions are used to group components into applications, sub-applications, and load modules.

    architecture member
    Defines an individual software component, which may be a collection of other architecture members, by specifying its relationship to other software components of an application.

    authcode
    An identifier used by SCLM to control authority to update and promote members within a hierarchy. These codes can be used to allow concurrent development without the risk of module collisions (overlaid changes).

    authorization code
    See authcode.

    B

    bidirectional (bi-di)
    Pertaining to scripts such as Arabic and Hebrew that generally run from right to left, except for numbers, which run from left to right.

    bidirectional attribute
    Text type, text orientation, numeric swapping, and symmetric swapping.

    build
    The process of transforming inputs into outputs through the invocation of translators specified in the language definition. Compilers, preprocessors, and linkage editors are examples of translators that might be invoked at build time.

    build map
    Internal data record containing a complete analysis of the database at the time of the build; it includes the names of all referenced members and the last change date and version number of each member.

    C

    change code
    An 8-character identifier used to indicate the reason for an update or modification to a member controlled by SCLM.

    component
    Any input or output member associated with an application, which together make up all or a member of the application.

    container
    In J2EE, an entity that provides life-cycle management, security, deployment, and runtime services to components. Each type of container (EJB, Web, JSP, servlet, applet, and application client) also provides component-specific services.

    D

    development group
    Groups that are in the lowest level of the hierarchy. These groups represent end-nodes with no other lower groups promoting into them.

    E

    EAR
    See Enterprise Archive.

    EJB
    See Enterprise Java Beans.

    Enterprise Archive
    A specialized type of JAR file, defined by the J2EE standard, used to deploy J2EE applications to J2EE application servers. An EAR file contains EJB components, a deployment descriptor, and Web archive (WAR) files for individual Web applications.

    Enterprise JavaBeans
    JavaBeans are reusable objects, like subroutines. EJBs take this a step further and are designed to be platform independent.

    G

    group
    A set of project data sets with the same middle-level qualifier in the SCLM logical naming convention.

    H

    hierarchy
    The organization of groups in a ranked order, where each group is subordinate to the one above it.

    I

    IDE project
    A project developed in the Eclipse IDE.

    J

    J2EE
    Java 2 Platform, Enterprise Edition. It defines the standard for developing component-based multi-tier enterprise applications.

    J2EE project
    A project developed in the Eclipse IDE specifically related to Java/J2EE.

    JAR
    See Java Archive.

    Java Enterprise
    A file format for storing information for or about Java programs.

    L

    language definition
    Specifies the set of translators to be run for SCLM functions PARSE, VERIFY, BUILD, COPY, and PURGE. A language definition is composed of one FLMLANGL macro followed by an FLMTRNSL macro for each translator to be run for members of SCLM libraries whose language attribute matches the value of the LANG keyword in the FLMLANGL macro.

    level
    A given tier of the hierarchy, made up of groups, of equivalent rank.

    library
    In z/OS, a partitioned data set.

    lock
    When a user locks a member, only that user can change it. All other users are unable to change that member until the member is promoted or unlocked. When a member is locked, an authorization code is specified. If two users need to change a part, two different authorization codes can be used.

    M

    member
    The discreet element of an SCLM database, representing a single data type of a software component.

    migrate
    Registering software components in SCLM: this includes identifying the component language, and possibly the change code and authorization code.

    migration
    The process of introducing members into SCLM control. Migration locks the member, parses it according to the requested language, and stores the information in the accounting database. The migration utility can be used to enter a large number of members into a project's database, such as during conversion to SCLM.

    P

    perspective
    A group of views that show various aspects of the resources in the workbench. The workbench user can switch perspectives, depending on the task at hand, and customize the layout of views and editors within the perspective.

    project
    A collection of libraries representing an integrated SCLM database, under a single high-level qualifier.

    project administrator
    The person who maintains an SCLM project.

    project definition
    Defines the SCLM library structure, project control information, and language definitions. A project definition is a load module used by SCLM at run time. The source code for a project definition is composed of macros.

    project definition data
    Project definitions and language definitions which are used to create and control an SCLM project.

    promote
    The process of moving an application or its components from one level in the project hierarchy to the next. Promotion out of a development group removes the lock on editable members that were successfully promoted.

    S

    SCLM administrator
    The person who maintains an SCLM project.

    scope
    The set of members (including architecture definitions) that will be processed (for example verified, copied, compiled, or purged) by build or promote.

    service
    An SCLM function available via a command or programming interface.

    T

    translator
    A load module, CLIST, or REXX program that receives control from SCLM for execution. The name of the translator is specified as the value of the COMPILE keyword for the FLMTRNSL macro. Examples of translators are compilers, assemblers, linkage editors, text processors, DB2(R) preprocessors, CICS(R) preprocessors, utilities, and customer tools.

    type
    The third qualifier of the SCLM naming convention for project-partitioned data sets. Typically identifies the kind of data maintained for a project hierarchy. Examples of types are SOURCE, OBJECT, and LOAD.

    U

    unlock
    To make a member (formerly locked out) available for updating (usually associated with promote).

    unlock service
    Removes the restriction (unlocks) on a member to a development group.

    V

    version
    A copy of a member as it existed at a previous point in time.

    versioning
    A function that enables the retrieval of a version of a member. This is useful for backing out changes.

    W

    WAR
    See Web Archive.

    Web Archive
    A file format for storing information for or about web type applications.

    Index

    Special characters
    A B C D E F G H I J K L M N O P R S T U W Z
    Special characters A B C D E F G H I J K L M N O P R S T U W Z