IBM Rational Developer for System z

Host Configuration Guide

Version 7.6
SC23-7658-03
Note

Before using this document, read the general information under Documentation notices for IBM Rational Developer for System z.

Fourth edition (September 2009)

This edition applies to IBM Rational Developer for System z Version 7.6 (program number 5724-T07) and to all subsequent releases and modifications until otherwise indicated in new editions.

Order publications by phone or fax. IBM Software Manufacturing Solutions takes publication orders between 8:30 a.m. and 7:00 p.m. eastern standard time (EST). The phone number is (800) 879-2755. The fax number is (800) 445-9269. Faxes should be sent Attn: Publications, 3rd floor.

You can also order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address below.

IBM welcomes your comments. You can send your comments by mail to the following address:

IBM Corporation
Attn: Information Development Department 53NA
Building 501 P.O. Box 12195
Research Triangle Park NC 27709-2195
USA

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

Note to U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Copyright International Business Machines Corporation 2005, 2009.
US Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Figures
Tables
About this document
Who should use this document
Developer for System z customization
Planning
Migration considerations
Planning considerations
Product overview
Skill requirements
Time requirements
Preinstallation considerations
Setup choice
Requisite products
Required resources
Pre-configuration considerations
Resource usage and system limits
Required configuration of requisite products
User ID considerations
Server considerations
Predeployment considerations
Client checklist
Basic customization
Requirements and checklist
Customization setup
PARMLIB changes
Set z/OS UNIX limits in BPXPRMxx
Add started tasks to COMMNDxx
LPA definitions in LPALSTxx
APF authorizations in PROGxx
LINKLIST definitions in PROGxx
Requisite LINKLIST and LPA definitions
LINKLIST definitions for other products
PROCLIB changes
JES Job Monitor
RSE daemon
Lock daemon
JCL limitations for the PARM variable
ELAXF* remote build procedures
Security definitions
FEJJCNFG, JES Job Monitor configuration file
rsed.envvars, RSE configuration file
Defining the PORTRANGE available for RSE
Defining extra Java startup parameters with _RSE_JAVAOPTS
Defining extra Java startup parameters with _RSE_CMDSERV_OPTS
ISPF.conf, ISPF's TSO/ISPF Client Gateway configuration file
Optional components
(Optional) Common Access Repository Manager (CARMA)
Requirements and checklist
CARMA components
RSE interface to CARMA
CARMA server startup using batch submit
Adjust CRASRV.properties
Adjust CRASUBMT
(Optional) Alternative CARMA server startup using CRASTART
Adjust CRASRV.properties
Adjust crastart.conf
(Optional) Alternative CARMA server startup using TSO/ISPF Client Gateway
Adjust CRASRV.properties
Adjust ISPF.conf
(Optional) Activating the sample Repository Access Managers (RAMs)
Activating the PDS RAM
Activating the SCLM RAM
Activating the skeleton RAM
(Optional) Activating the CA Endevor® RAM
Define the CA Endevor® RAM
Update the CARMA server startup - batch submit
Update the CARMA server startup - CRASTART
(Optional) IRXJCL versus CRAXJCL
Create CRAXJCL
(Optional) Application Deployment Manager
Requirements and checklist
CRD repository
CICS administrative utility
RESTful versus Web Service
CRD server using the RESTful interface
CICS primary connection region
CICS non-primary connection regions
(Optional) Customize CRD server transaction IDs
CRD server using the Web Service interface
Pipeline message handler
CICS primary connection region
CICS non-primary connection regions
(Optional) Manifest repository
(Optional) SCLM Developer Toolkit
Requirements and checklist
Prerequisites
ISPF.conf updates for SCLMDT
rsed.envvars updates for SCLMDT
(Optional) Long/short name translation
Create LSTRANS.FILE, the long/short name translation VSAM
rsed.envvars updates for long/short name translation
(Optional) Install and customize Ant
SCLM updates for SCLMDT
Remove old files from WORKAREA
(Optional) Other customization tasks
(Optional) DB2 stored procedure
Workload Manager (WLM) changes
PROCLIB changes
DB2 changes
(Optional) Enterprise Service Tools (EST) support
(Optional) CICS bidirectional language support
(Optional) Diagnostic IRZ error messages
(Optional) RSE SSL encryption
(Optional) RSE tracing
(Optional) Host based property groups
(Optional) Host based projects
(Optional) File Manager integration
(Optional) Uneditable characters
(Optional) Using REXEC (or SSH)
Remote (host-based) actions for z/OS UNIX subprojects
Alternate RSE connection method
REXEC (or SSH) set up
(Optional) APPC transaction for the TSO Commands service
Preparation
Implementation
APPC usage considerations
(Optional) WORKAREA cleanup
Installation verification
Verify started tasks
JMON, JES Job Monitor
LOCKD, Lock daemon
RSED, RSE daemon
Verify services
IVP initialization
Port availability
TCP/IP setup
RSE daemon connection
JES Job Monitor connection
Lock daemon connection
ISPF's TSO/ISPF Client Gateway connection
(Optional) TSO Commands service connection using APPC
(Optional) SCLMDT connection
(Optional) REXEC connection
(Optional) REXEC/SSH shell script
Developer for System z information
Operator commands
Start (S)
JES Job Monitor
RSE daemon
Lock daemon
Modify (F)
JES Job Monitor
RSE daemon
Lock daemon
Stop (P)
Console messages
JES Job Monitor
RSE daemon, RSE thread pool server, and lock daemon
How to read a syntax diagram
Symbols
Operands
Syntax example
Nonalphanumeric characters and blank spaces
Selecting more than one operand
Longer than one line
Syntax fragments
Troubleshooting configuration problems
Log and setup analysis using FEKLOGS
Log files
JES Job Monitor logging
Lock daemon logging
RSE daemon and thread pool logging
RSE user logging
Fault Analyzer Integration logging
File Manager Integration logging
SCLM Developer Toolkit logging
CARMA logging
APPC transaction (TSO Commands service) logging
fekfivpi IVP test logging
fekfivps IVP test logging
Dump files
MVS dumps
Java dumps
z/OS UNIX dump locations
Tracing
JES Job Monitor tracing
RSE tracing
Lock daemon tracing
CARMA tracing
Error feedback tracing
z/OS UNIX permission bits
SETUID file system attribute
Program Control authorization
Sticky bit
Reserved TCP/IP ports
Address Space size
startup JCL requirements
Limitations set in SYS1.PARMLIB(BPXPRMxx)
Limitations stored in the security profile
Limitations enforced by system exits
APPC transaction and TSO Commands service
Miscellaneous information
System limits
Known requisite issues
Host Connect Emulator
Security considerations
Authentication methods
User ID and password
User ID and one-time password
X.509 certificate
JES Job Monitor authentication
Connection security
Limit external communication to specified ports
Communication encryption using SSL
Port Of Entry checking
TCP/IP ports
External communication
Internal communication
CARMA and TCP/IP ports
Using PassTickets
Audit logging
Audit control
Audit data
JES security
Actions against jobs - target limitations
Actions against jobs - execution limitations
Access to spool files
SSL encrypted communication
Client authentication using X.509 certificates
Certificate Authority (CA) validation
(Optional) Query a Certificate Revocation List (CRL)
Authentication by your security software
Authentication by RSE daemon
Port Of Entry (POE) checking
CICSTS security
CRD repository
CICS transactions
SSL encrypted communication
SCLM security
Developer for System z configuration files
JES Job Monitor - FEJJCNFG
RSE - rsed.envvars
RSE - ssl.properties
Security definitions
Requirements and checklist
Activate security settings and classes
Define an OMVS segment for Developer for System z users
Define data set profiles
Define the Developer for System z started tasks
Define JES command security
Define RSE as a secure z/OS UNIX server
Define MVS program controlled libraries for RSE
Define application protection for RSE
Define PassTicket support for RSE
Define z/OS UNIX program controlled files for RSE
Verify security settings
Understanding Developer for System z
Component overview
RSE as a Java application
Connection flow
Lock daemon
Freeing a lock
z/OS UNIX directory structure
Update privileges for non-system administrators
Tuning considerations
Resource usage
Overview
Address space count
Process count
Thread count
Storage usage
Java heap size limit
Address space size limit
Size estimate guidelines
Sample storage usage analysis
z/OS UNIX file system space usage
Key resource definitions
/etc/rdz/rsed.envvars
SYS1.PARMLIB(BPXPRMxx)
Various resource definitions
EXEC card in the server JCL
FEK.#CUST.PARMLIB(FEJJCNFG)
SYS1.PARMLIB(IEASYSxx)
SYS1.PARMLIB(IVTPRMxx)
SYS1.PARMLIB(ASCHPMxx)
Monitoring
Monitoring RSE
Monitoring z/OS UNIX
Monitoring the network
Monitoring z/OS UNIX file systems
Sample setup
Thread pool count
Determine minimum limits
Defining limits
Performance considerations
Use zFS file systems
Avoid use of STEPLIB
Improve access to system libraries
Language Environment (LE) runtime libraries
Application development
Improving performance of security checking
Workload management
Fixed Java heap size
Java -Xquickstart option
Class sharing between JVMs
Enable class sharing
Cache size limits
Cache security
SYS1.PARMLIB(BPXPRMxx)
Disk space
Cache management utilities
CICSTS considerations
RESTful versus Web Service
Primary versus non-primary connection regions
CICS resource install logging
Application Deployment Manager security
CRD repository security
Pipeline security
Transaction security
SSL encrypted communication
Resource security
Administrative utility
Administrative utility messages
Customizing the TSO environment
The TSO Commands service
Access methods
Using the TSO/ISPF Client Gateway access method
Basic customization - ISPF.conf
Advanced - Use existing ISPF profiles
Advanced - Using an allocation exec
Advanced - Use multiple allocation execs
Advanced - Multiple ISPF.conf files with multiple Developer for System z setups
Using the APPC access method
Basic customization - APPC transaction JCL
Advanced - Use existing ISPF profiles
Advanced - Using an allocation exec
Advanced - Multiple APPC transactions with multiple Developer for System z setups
Running multiple instances
Identical setup across a sysplex
Identical software level, different configuration files
All other situations
Migration guide
Migration considerations
Backing up previously configured files
Migrate from version 7.5 to version 7.6
IBM Rational Developer for System z, FMID HHOP760
Configurable files
Migrate from version 7.1 to version 7.5
IBM Rational Developer for System z, FMID HHOP750
Configurable files
Migrate from version 7.0 to version 7.1
IBM Rational Developer for System z, FMID HHOP710
IBM Common Access Repository Manager (CARMA), FMID HCMA710
Configurable files
Appendixes
Appendix A. Setting up SSL and X.509 authentication
Decide where to store private keys and certificates
Create a key ring with RACF
(Optional) Using a signed certificate
Clone the existing RSE setup
Update rsed.envvars to enable coexistence
Update ssl.properties to enable SSL
Activate SSL by creating a new RSE daemon
Test the connection
(Optional) Add X.509 client authentication support
(Optional) Create a key database with gskkyman
(Optional) Create a key store with keytool
Appendix B. Setting up TCP/IP
Hostname dependency
Understanding resolvers
Understanding search orders of configuration information
Search orders used in the z/OS UNIX environment
Base resolver configuration files
Translate tables
Local host tables
Applying this set up information to Developer for System z
Host address is not resolved correctly
Appendix C. Setting up INETD
inetd.conf
ETC.SERVICES
Search order used in the z/OS UNIX environment
Search order used in the native MVS environment
PROFILE.TCPIP port definitions
/etc/inetd.pid
Startup
/etc/rc
/etc/inittab
BPXBATCH
Shell session
Security
Developer for System z requirements
INETD
REXEC (or SSH)
Appendix D. Setting up APPC
VSAM
VTAM
SYS1.PARMLIB(APPCPMxx)
SYS1.PARMLIB(ASCHPMxx)
Activating APPC changes
Defining the TSO Commands service transaction
(Optional) Alternative setup options
Alternative transaction name
Multiple LUs
LU security
Appendix E. Requisites
z/OS host prerequisites
z/OS
SMP/E
SDK for z/OS Java 2 Technology Edition
z/OS host corequisites
z/OS
COBOL compiler
PL/I compiler
Debug Tool for z/OS
CICS Transaction Server
IMS
DB2 for z/OS
Rational Team Concert for System z
File Manager
Fault Analyzer
REXX
Ported tools
Ant
Bibliography
Referenced publications
Informational publications
Glossary
Documentation notices for IBM Rational Developer for System z
Copyright license
Trademark acknowledgments
Index

Figures

  1. JMON - JES Job Monitor started task
  2. RSED - RSE daemon started task
  3. LOCKD - Lock daemon started task
  4. RSED - alternate RSE daemon startup
  5. rsed.stdin.sh - alternate RSE daemon startup
  6. FEJJCNFG, JES Job Monitor configuration file
  7. rsed.envvars - RSE configuration file
  8. (continued)
  9. ISPF.conf - ISPF configuration file
  10. CRASRV.properties - CARMA configuration file
  11. CRASRV.properties - CARMA startup using batch submit
  12. CRASUBMT - CARMA startup using batch submit
  13. CRASRV.properties - *CRASTART alternative CARMA startup
  14. crastart.conf - *CRASTART alternative CARMA startup
  15. CRASRV.properties - *ISPF alternative CARMA startup
  16. ISPF.conf - *ISPF alternative CARMA startup
  17. ISPF.conf updates for SCLMDT
  18. rsed.envvars updates for SCLMDT
  19. FLM02LST - long/short name translation setup JCL
  20. ELAXMSAM - DB2 stored procedure task
  21. ELAXMJCL - DB2 stored procedure definition
  22. ssl.properties - SSL configuration file
  23. rsecomm.properties - Logging configuration file
  24. propertiescfg.properties - Host-based property groups configuration file
  25. projectcfg.properties - Host-based projects configuration file
  26. FMIEXT.properties - File Manager configuration file
  27. uchars.settings - Uneditable characters configuration file
  28. REXX for APPC ISPF panels
  29. START JMON operator command
  30. START RSED operator command
  31. START LOCKD operator command
  32. MODIFY JMON operator command
  33. MODIFY RSED operator command
  34. MODIFY LOCKD operator command
  35. STOP operator command
  36. TCP/IP ports
  37. Component overview
  38. RSE as a Java application
  39. Connection flow
  40. Lock daemon flow
  41. z/OS UNIX directory structure
  42. Maximum number of address spaces
  43. Number of address spaces per client
  44. Maximum number of processes
  45. Number of processes per client
  46. Maximum number of RSE thread pool threads
  47. Maximum number of JES Job Monitor threads
  48. Resource usage with 5 logons
  49. Resource usage with 5 logons (continued)
  50. Resource usage while editing a PDS member
  51. z/OS UNIX file system space usage
  52. ADNJSPAU - CICSTS administrative utility
  53. FEKAPPCC - create a second APPC transaction
  54. RSEDSSL - RSE daemon user job for SSL
  55. Import Host Certificate dialog
  56. Preferences dialog - SSL
  57. INETD startup JCL
  58. JCL to create APPC VSAMs
  59. SYS1.SAMPLIB(ATBAPPL)
  60. SYS1.PARMLIB(APPCPMxx)
  61. SYS1.PARMLIB(ASCHPMxx)

Tables

  1. Required resources
  2. Optional resources
  3. Administrators needed for required tasks
  4. Administrators needed for optional tasks
  5. Client checklist - mandatory parts
  6. Client checklist - optional parts
  7. Sample ELAXF* procedures
  8. ELAXF* high level qualifier checklist
  9. LIMIT_COMMANDS command permission matrix
  10. crastart.conf variables
  11. Default CRD server transaction IDs
  12. Default CRD server transaction IDs
  13. SCLM administrator checklist
  14. SSL certificate storage mechanisms
  15. Valid keystore types
  16. APPC transaction checklist
  17. IVPs for services
  18. Thread pool error status
  19. RSE console messages
  20. JAVA_DUMP_TDUMP_PATTERN variables
  21. JES Job Monitor console commands
  22. LIMIT_COMMANDS command permission matrix
  23. Extended JESSPOOL profiles
  24. LIMIT_VIEW browse permission matrix
  25. SSL certificate storage mechanisms
  26. Security setup variables
  27. JES2 Job Monitor operator commands
  28. JES3 Job Monitor operator commands
  29. Common resource usage
  30. User-specific requisite resource usage
  31. User-specific resource usage
  32. Address space count
  33. Address space limits
  34. Process count
  35. Process limits
  36. Thread count
  37. Thread limits
  38. Log output directives
  39. Version 7.6 customizations
  40. Version 7.5 customizations
  41. Version 7.1 customizations
  42. SSL certificate storage mechanisms
  43. Local definitions available to resolver
  44. Referenced publications
  45. Referenced Web sites
  46. Informational publications

About this document

This document discusses the configuration of the IBM Rational Developer for System z functions. It includes instructions on how to configure IBM Rational Developer for System z Version 7.6 on your z/OS® host system.

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

For earlier releases, including IBM WebSphere Developer for System z, IBM WebSphere Developer for zSeries and IBM® WebSphere Studio Enterprise Developer, use the configuration information found in the Host Configuration Guide and Program Directories for those releases.

Who should use this document

This document is intended for system programmers installing and configuring IBM Rational Developer for System z Version 7.6, FMID HHOP760, on their z/OS host system.

It lists in detail the different steps needed to do a full setup of the product, including some non-default scenarios. To use this document, you need to be familiar with the z/OS UNIX System Services and MVS™ host systems.

Developer for System z customization

Planning

Use the information in this chapter, together with the information in Appendix E. Requisites, to plan the installation and deployment of Developer for System z®. The following subjects are described:

Migration considerations

Migration guide describes installation and configuration changes compared to previous releases of the product. Use this information to plan your migration to the current release of Developer for System z.

Notes:
  1. If you are a previous user of IBM Rational Developer for System z, IBM WebSphere Developer for System z, IBM WebSphere Developer for zSeries or IBM WebSphere Studio Enterprise Developer, it is recommended that you save the related customized files BEFORE installing IBM Rational Developer for System z Version 7.6. Refer to Migration guide for an overview of files that required customization.
  2. Refer to Running multiple instances, if you plan on running multiple instances of Developer for System z.

Planning considerations

Product overview

Developer for System z consists of a client, installed on the user's personal computer, and a server, installed on one or more hosts. This documentation will focus on the host being a z/OS system. However, other operating systems, such as AIX® and z/Linux, are also supported.

The client provides developers an Eclipse-based development environment that facilitates a uniform graphical interface to the host, and that, among other things, can offload work from the host to the client, saving resources on the host.

The host portion consists of several permanently active tasks and tasks that are started ad-hoc. These tasks allow the client to work with the various components of your z/OS host, such as MVS data sets, TSO commands, z/OS UNIX files and commands, job submit, and job output.

Developer for System z can also interact with subsystems and other application software on the host, such as CICS, Debug Tool, and Software Configuration Managers (SCMs), if Developer for system z is configured to do so, and if these (corequisite) products are available.

Refer to Understanding Developer for System z to get a basic understanding of the Developer for System z design.

Refer to the Developer for System z website, http://www-01.ibm.com/software/awdtools/rdz/, or your local IBM representative to learn more about the functionality offered by Developer for System z.

Skill requirements

Minimal SMP/E skills are needed for a Developer for System z host installation.

The configuration of Developer for System z requires more than the typical system programming permissions and expertise, so assistance from others may be needed. Table 3 and Table 4 list the administrators needed for the required and optional customization tasks.

Time requirements

The amount of time required to install and configure the Developer for System z host components depends on various factors, such as:

Experience has shown that the installation and configuration process of the Developer for System z host requires from one to four days to complete. This time requirement is for a clean installation performed by an experienced system programmer. If problems are encountered, or if the required skills are not available, then the setup will take longer.

Preinstallation considerations

Refer to Program Directory for IBM Rational® Developer for System z (GI11-8298) for detailed instructions on the SMP/E installation of the product.

Note:
The file system (HFS or zFS) in which Developer for System z is installed must be mounted with the SETUID permission bit on (this is the system default). Mounting the file system with the NOSETUID parameter will prevent Developer for System z from creating the user's security environment, and will fail the connection request of the client.

Refer to Running multiple instances if you plan on running multiple instances of Developer for System z.

Setup choice

Developer for System z provides a choice on how to access the TSO Commands service. The choice made here impacts the required configuration of prerequisites. One of the following methods must be selected and configured:

Note:
ISPF's TSO/ISPF Client Gateway is also used by SCLM Developer Toolkit and optionally by an alternative startup method for Common Access Repository Manager (CARMA).

Requisite products

Appendix E. Requisites has a list of prerequisite software that must be installed and operational before Developer for System z will work. There is also a list of corequisite software to support specific features of Developer for System z. These requisites must be installed and operational at runtime for the corresponding feature to work as designed.

Refer to Rational Developer for System z Prerequisites (SC23-7659) in the Developer for System z online library at http://www-01.ibm.com/software/awdtools/rdz/library/ for an up-to-date list of prerequisite and corequisite products for your version of Developer for System z. Plan ahead to have these requisite products available, as it might take some time, depending on the policies at your site. The key requisites for a basic setup are the following:

Note:
64-bit Java is NOT supported.

Required resources

Developer for System z requires the allocation of the systems resources listed in Table 1. The resources listed in Table 2 are required for optional services. Plan ahead to have these resources available, as it might take some time to get them, depending on the policies at your site.

Note:
Developer for System z consists of multiple tasks that communicate with each other and the client. These tasks use various timers to detect communication loss with their partner or partners. This implies that timeout issues can arise (due to lack of CPU time during the timeout window) on systems with a heavy CPU load or incorrect Workload Management (WLM) settings for Developer for system z.
Table 1. Required resources
Resource Default value Information
APF authorized data set FEK.SFEKAUTH APF authorizations in PROGxx
started task JMON, RSED, and LOCKD Server considerations
port for host-confined use 6715 FEJJCNFG, JES Job Monitor configuration file
port for host-confined use 4036 rsed.envvars, RSE configuration file
port for client-host communication 4035 PROCLIB changes
port range for client-host communication any available port is used Defining the PORTRANGE available for RSE
Table 2. Optional resources
Resource Default value Information
LINKLIST data set FEK.SFEKAUTH and FEK.SFEKLOAD (Optional) SCLM Developer Toolkit
LPA data set FEK.SFEKLPA (Optional) Common Access Repository Manager (CARMA)
port range for host-confined use 5227-5326 (100 ports) (Optional) Common Access Repository Manager (CARMA)
ports for host-confined use any available port is used (Optional) APPC transaction for the TSO Commands service
port for client-host communication no default (Optional) Application Deployment Manager
CICS CSD update multiple values (Optional) Application Deployment Manager
CICS JCL update FEK.SFEKLOAD

The configuration of Developer for System z requires more than the typical system programming permissions and expertise, so minimal assistance from others may be needed. Table 3 and Table 4 list the administrators needed for the required and optional customization tasks.

Table 3. Administrators needed for required tasks
Administrator Task Information
System Typical system programmer actions are required for all customization tasks N/A
Security
  • Define OMVS segment for Developer for System z users
  • Define data set profiles
  • Define started tasks
  • Define operator command security
  • Define z/OS UNIX server profiles
  • Define application security
  • Define PassTicket support
  • Define program controlled data sets
  • Define program controlled z/OS UNIX files
Security considerations
TCP/IP Define new TCP/IP ports TCP/IP ports
WLM Assign started task goals to the servers and their child processes PROCLIB changes
Table 4. Administrators needed for optional tasks
Administrator Task Information
System Typical system programmer actions are required for all customization tasks N/A
Security
  • Define data set profiles
  • Define program controlled data sets
  • Define permission to submit xxx* jobs
  • Define CICS transaction security
  • Add certificate for SSL
  • Define X.509 client certificate support
TCP/IP Define new TCP/IP ports TCP/IP ports
SCLM
  • Define SCLM language translators for JAVA/J2EE support
  • Define SCLM types for JAVA/J2EE support
(Optional) SCLM Developer Toolkit
CICS TS
  • Update CICS region JCL
  • Update CICS region CSD
  • Define CICS group
  • Define CICS transaction names
  • Define a program to CICS
DB2® Define a DB2 stored procedure (Optional) DB2 stored procedure
WLM
  • Assign goals to a DB2 stored procedure
  • Assign TSO-like goals to an APPC transaction
APPC Define an APPC transaction (Optional) APPC transaction for the TSO Commands service

Pre-configuration considerations

Resource usage and system limits

When in use, Developer for System z will use a variable number of system resources like address spaces and z/OS UNIX processes and threads. The availability of these resources is limited by various system definitions. Refer to Tuning considerations to estimate the usage of key resources, so you can plan your system configuration accordingly.

Required configuration of requisite products

Consult your MVS system programmer, security administrator and TCP/IP administrator to check if the requisite products and software are installed, tested, and working. Some requisite customization tasks that are easily overlooked are listed below:

User ID considerations

The user ID of a Developer for System z user must have (at least) the following attributes:

Server considerations

Developer for System z consists of 3 permanently active servers, which can be started tasks or user jobs. These servers provide the requested services themselves, or start other servers (as z/OS UNIX threads or user jobs) to provide the service.

JES Job Monitor (JMON) provides all JES related services.

Remote Systems Explorer (RSE) is the Developer for System z component that provides core services such as connecting the client to the host.

As documented in TCP/IP ports, certain host services, and thus their ports, must be available for the client to connect to, and must be defined to your firewall protecting the host. All other ports used by Developer for System z have host-only traffic. Listed below are the ports needed for a basic Developer for System z setup.

Note:
Previous clients (version 7.0 and older) communicate directly with JES Job Monitor (using the tcp protocol), default port 6715.

Predeployment considerations

Developer for System z supports cloning an installation to a different system, avoiding the need for a SMP/E install on each system.

The following data sets, directories, and files are mandatory for deployment to other systems. If you copied a file to a different location, then this file must replace its counterpart in the lists below.

Note:
The list below does not cover the deployment needs of the pre- and corequisite software.
Notes:
  1. FEK and /usr/lpp/rdz are the high level qualifier and path used during the installation of the product. FEK.#CUST, /etc/rdz and /var/rdz are the default locations used during the customization of the product (see Customization setup for more information).
  2. You should install Developer for System z in a private file system (HFS or zFS) to easy deploying the z/OS UNIX parts of the product.
  3. If you can not use a private file system, you should use an archiving tool such as the z/OS UNIX tar command to transport the z/OS UNIX directories from system to system. This to preserve the attributes (such as program control) for the Developer for System z files and directories.

    Refer to UNIX System Services Command Reference (SA22-7802) for more information on the following sample commands to archive and restore the Developer for System z installation directory.

Client checklist

Users of the Developer for System z client must know the result of certain host customizations, such as TCP/IP port numbers, for the client to work properly. Use these checklists to gather the information needed.

The checklist in Table 5 lists the required results of mandatory customization steps. Table 6 list the required results of optional customization steps.

Table 5. Client checklist - mandatory parts
Customization Value
JES Job Monitor server port number (default 6715):

See SERV_PORT in FEJJCNFG, JES Job Monitor configuration file.

RSE daemon TCP/IP port number (default 4035):

See RSE daemon.

Table 6. Client checklist - optional parts
Customization Value
Location of the ELAXF* procedures if they are not in a system procedure library:

See note on JCLLIB in ELAXF* remote build procedures.

Procedure or step names of the ELAXF* procedures if they were changed:

See note on changing them in ELAXF* remote build procedures.

DB2 stored procedure name (default ELAXMSAM):

See information on DB2 stored procedures in Running multiple instances.

Location of the DB2 stored procedure if it is not in a system procedure library:

See (Optional) DB2 stored procedure.

(corequisite) TN3270 port number for Host Connect Emulator (default 23).

See Security considerations

(corequisite) REXEC or SSH port number (default 512 or 22, respectively):

See (Optional) Using REXEC (or SSH).

Location of the server.zseries file if the REXEC/SSH connection method is used (default /etc/rdz).

See (Optional) Using REXEC (or SSH).

Location of the CRA#ASLM JCL for CARMA SCLM RAM data set allocations (default FEK.#CUST.JCL):

See note on CRA#ASLM in Activating the SCLM RAM.

Basic customization

The customization steps below are for a basic Developer for System z setup. Refer to the chapters about the optional components for their customization requirements.

Requirements and checklist

You will need the assistance of a security administrator and a TCP/IP administrator to complete this customization task, which requires the following resources and special customization tasks:

In order to verify the installation and to start using Developer for System z at your site, you must perform the following tasks. Unless otherwise indicated, all tasks are mandatory.

  1. Create customizable copies of samples and create the work environment for Developer for system z. For details, see Customization setup.
  2. Update z/OS UNIX system limits, start started tasks, define APF authorized and LINKLIST data sets and optionally LPA data sets. For details, see PARMLIB changes.
  3. Create started task procedures and compile/link procedures. For details, see PROCLIB changes.
  4. Update security definitions. For details, see Security definitions. You must also be aware of and understand how PassTickets are used to establish thread security. See Using PassTickets for details.
  5. Customize Developer for System z configuration files. For details, see:

Customization setup

Developer for System z comes with several sample configuration files and sample JCL. To avoid overwriting your customizations when applying maintenance, you should copy all these members and z/OS UNIX files to a different location and to customize the copy.

Some functions of Developer for System z also require the existence of certain directories in z/OS UNIX, which must be created during the customization of the product. To ease the installation effort, a sample job, FEKSETUP, is provided to create the copies and the required directories.

Customize and submit sample member FEKSETUP in data set FEK.SFEKSAMP to create customizable copies of configuration files and configuration JCL, and to create required z/OS UNIX directories. The required customization steps are described within the member.

This job performs the following tasks:

Notes:
  1. The configuration steps in this publication use the member/file locations created by the FEKSETUP job, unless noted otherwise. The original samples, which should not be updated, can be found in FEK.SFEKSAMP and /usr/lpp/rdz/samples/.
  2. If you want to keep all Developer for System z z/OS UNIX files in the same file system (HFS or zFS), but also want the configuration files placed in /etc/rdz, you can use symbolic links to solve this problem. The following sample z/OS UNIX commands create a new directory in the existing file system (/usr/lpp/rdz/cust) and define a symbolic link (/etc/rdz) to it:
    mkdir /usr/lpp/rdz/cust
    ln -s /usr/lpp/rdz/cust /etc/rdz

PARMLIB changes

Refer to MVS Initialization and Tuning Reference (SA22-7592) for more information on the PARMLIB definitions listed below. Refer to MVS System Commands (SA22-7627) for more information on the sample console commands.

Set z/OS UNIX limits in BPXPRMxx

Remote Systems Explorer (RSE), which provides core services such as connecting the client to the host, is a z/OS UNIX based process. Therefore it is important to set correct values for the z/OS UNIX system limits in BPXPRMxx, based upon the number of concurrently active Developer for System z users and their average workload.

Refer to Tuning considerations for more information on different BPXPRMxx defined limits and their impact on Developer for System z.

MAXASSIZE specifies the maximum address space (process) region size. Set MAXASSIZE in SYS1.PARMLIB(BPXPRMxx) to 2G. This is the maximum value allowed. This is a system-wide limit, and thus active for all z/OS UNIX address spaces. If this is not what you want, then you can set the limit also just for Developer for System z in your security software, as described in Define the Developer for System z started tasks.

MAXTHREADS specifies the maximum number of active threads for a single process. Set MAXTHREADS in SYS1.PARMLIB(BPXPRMxx) to 1500 or higher. This is a system-wide limit, and thus active for all z/OS UNIX address spaces. If this is not what you want, then you can set the limit also just for Developer for System z in your security software, as described in Define the Developer for System z started tasks.

MAXTHREADTASKS specifies the maximum number of active MVS tasks for a single process. Set MAXTHREADTASKS in SYS1.PARMLIB(BPXPRMxx) to 1500 or higher. This is a system-wide limit, and thus active for all z/OS UNIX address spaces. If this is not what you want, then you can set the limit also just for Developer for System z in your security software, as described in Define the Developer for System z started tasks.

MAXPROCUSER specifies the maximum number of processes that a single z/OS UNIX user ID can have concurrently active. Set MAXPROCUSER in SYS1.PARMLIB(BPXPRMxx) to 50 or higher. This setting is intended to be a system-wide limit, as it should be active for each client using Developer for System z.

These values can be checked and set dynamically (until the next IPL) with the following console commands:

Notes:
  1. Refer to Address Space size for more information on other locations where address space sizes can be set or limited.
  2. The MAXPROCUSER value used above is based upon users having a unique z/OS UNIX user ID (UID). Increase this value if your users share the same UID.
  3. Ensure that other BPXPRMxx values, such as those for MAXPROCSYS and MAXUIDS, are sufficient to handle the expected amount of concurrently active Developer for System z users. Refer to Tuning considerations for more details.

Add started tasks to COMMNDxx

Add start commands for the Developer for System z RSED, LOCKD, and JMON servers to SYS1.PARMLIB(COMMANDxx) to start them automatically at next system IPL.

Once the servers are defined and configured, they can be started dynamically (until the next IPL) with the following console commands:

Note:
The lock daemon should be started before Developer for System z users log on to the RSE daemon. This is so the lock daemon can track the data set lock requests by these users. Therefore you should start the lock daemon at system startup.

LPA definitions in LPALSTxx

The (optional) Common Access Repository Manager (CARMA) service supports alternative server startup methods that do not require the usage of a JES initiator. The most flexible of these alternatives requires that module CRASTART in the FEK.SFEKLPA load library is in the Link Pack Area (LPA).

LPA data sets are defined in SYS1.PARMLIB(LPALSTxx).

LPA definitions can be set dynamically (until the next IPL) with the following console commands:

APF authorizations in PROGxx

In order for JES Job Monitor to access JES spool files, module FEJJMON in the FEK.SFEKAUTH load library and the Language Environment® (LE) runtime libraries (CEE.SCEERUN*) must be APF authorized.

In order for the (optional) SCLM Developer Toolkit service to work, module BWBTSOW in the FEK.SFEKAUTH load library and the REXX™ runtime library (REXX.*.SEAGLPA) must be APF authorized.

In order for ISPF to create the TSO/ISPF Client Gateway, module ISPZTSO in SYS1.LINKLIB must be APF authorized. The TSO/ISPF Client Gateway is used by Developer for System z's TSO Commands service, SCLM Developer Toolkit and optionally CARMA.

APF authorizations are defined in SYS1.PARMLIB(PROGxx), if your site followed IBM recommendations.

APF authorizations can be set dynamically (until the next IPL) with the following console commands, where volser is the volume on which the data set resides if it is not SMS managed:

Notes:
  1. When you use the Alternate Library for REXX product package, the default REXX runtime library name is REXX.*.SEAGALT, instead of REXX.*.SEAGLPA as used in the preceding sample.
  2. LPA libraries, such as REXX.*.SEAGLPA, are automatically APF authorized when located in LPA, and thus do not require explicit definitions.
  3. Some of the corequisite products, such as IBM Debug Tool, also require APF authorization. Refer to the related product customization guides for more information on this.

LINKLIST definitions in PROGxx

LINKLIST definitions for Developer for System z can be grouped in 3 categories:

In order for the (optional) SCLM Developer Toolkit service to work, all BWB* modules in the FEK.SFEKAUTH and FEK.SFEKLOAD load libraries must be made available either through STEPLIB or LINKLIST.

If you opt to use STEPLIB, you must define the libraries not available through LINKLIST in the STEPLIB directive of rsed.envvars, the RSE configuration file. Be aware, however, that:

LINKLIST data sets are defined in SYS1.PARMLIB(PROGxx), if your site followed IBM recommendations.

The required definitions will look like the following, where listname is the name of the LINKLIST set that will be activated, and volser is the volume on which the data set resides if it is not cataloged in the master catalog:

LINKLIST definitions can be created dynamically (until the next IPL) with the following group of console commands, where listname is the name of the current LINKLIST set, and volser is the volume on which the data set resides if it is not cataloged in the master catalog:

  1. LNKLST DEFINE,NAME=LLTMP,COPYFROM=CURRENT
  2. LNKLST ADD NAME=LLTMP,DSN=FEK.SFEKAUTH,VOL=volser
  3. LNKLST ADD NAME=LLTMP,DSN=FEK.SFEKLOAD
  4. LNKLST ACTIVATE,NAME=LLTMP
  5. LNKLST UNDEFINE,NAME=listname
  6. LNKLST UPDATE,JOB=*

Requisite LINKLIST and LPA definitions

Remote Systems Explorer (RSE) is a z/OS UNIX process that requires access to MVS load libraries. The following (prerequisite) libraries must be made available, either through STEPLIB or LINKLIST/LPALIB:

The following additional libraries must be made available, either through STEPLIB or LINKLIST/LPALIB, to support the use of optional services. This list does not include data sets that are specific to a product that Developer for System z interacts with, such as IBM Debug Tool:

Notes:
  1. When you use the Alternate Library for REXX product package, the default REXX runtime library name is REXX.*.SEAGALT, instead of REXX.*.SEAGLPA as used in the preceding sample.
  2. Libraries that are designed for LPA placement, such as REXX.*.SEAGLPA, might require additional program control and/or APF authorizations if they are accessed through LINKLIST or STEPLIB.
  3. Some of the corequisite products, such as IBM Debug Tool, also require STEPLIB or LINKLIST/LPALIB definitions. Refer to the related product customization guides for more information on this.
  4. If CEE.SCEELKED is in LINKLIST or STEPLIB, TCPIP.SEZALOAD must be placed before CEE.SCEELKED. Failure to do so will result in a 0C1 system abend for the TCP/IP REXX socket calls.

LINKLIST data sets are defined in SYS1.PARMLIB(PROGxx), if your site followed IBM recommendations. LPA data sets are defined in SYS1.PARMLIB(LPALSTxx).

If you opt to use STEPLIB, you must define the libraries not available through LINKLIST/LPALIB in the STEPLIB directive of rsed.envvars, the RSE configuration file. Be aware, however, that:

LINKLIST definitions for other products

The Developer for System z client has a code generation component called Enterprise Service Tools (EST). In order for the generated code to issue diagnostic error messages, all IRZ* and IIRZ* modules in the FEK.SFEKLOAD load library must be made available either through STEPLIB or LINKLIST.

LINKLIST data sets are defined in SYS1.PARMLIB(PROGxx), if your site followed IBM recommendations.

If you opt to use STEPLIB, you must define the libraries not available through LINKLIST in the STEPLIB directive of the task that executes the code (IMS™ or batch job). However, be aware of the following:

PROCLIB changes

The started task and remote build procedures listed below must reside in a system procedure library defined to your JES subsystem. In the instructions below, the IBM default procedure library, SYS1.PROCLIB, is used.

JES Job Monitor

Customize the sample started task member FEK.#CUST.PROCLIB(JMON), as described within the member, and copy it to SYS1.PROCLIB. As shown in the code sample below, you have to provide the following:

Figure 1. JMON - JES Job Monitor started task
//*
//* JES JOB MONITOR
//*
//JMON     PROC PRM=,             * PRM='-TV' TO START TRACING
//            LEPRM='RPTOPTS(ON)', 
//            HLQ=FEK,
//            CFG=FEK.#CUST.PARMLIB(FEJJCNFG)
//*
//JMON     EXEC PGM=FEJJMON,REGION=0M,TIME=NOLIMIT,
//            PARM=('&LEPRM,ENVAR("_CEE_ENVFILE=DD:ENVIRON")/&PRM')
//STEPLIB  DD DISP=SHR,DSN=&HLQ..SFEKAUTH
//ENVIRON  DD DISP=SHR,DSN=&CFG
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//         PEND
//*
Notes:
  1. Refer to Operator commands for more information on the startup parameters.
  2. The sample JCL is initially shipped as FEK.SFEKSAMP(FEJJJCL) and is renamed to FEK.#CUST.PROCLIB(JMON) in Customization setup.
  3. Tracing can also be controlled by console commands, as described in Operator commands.
  4. This task must be assigned to SYSSTC or equivalent goal in Workload Manager (WLM).

RSE daemon

Customize the sample started task member FEK.#CUST.PROCLIB(RSED), as described within the member, and copy it to SYS1.PROCLIB. As shown in the code sample below, you have to provide the following:

Figure 2. RSED - RSE daemon started task
//*
//* RSE DAEMON
//*
//RSED     PROC IVP='',              * 'IVP' to do an IVP test
//            PORT=4035,
//            HOME='/usr/lpp/rdz',
//            CNFG='/etc/rdz'
//*
//RSE      EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT,
//            PARM='PGM  &HOME/bin/rsed.sh &IVP &PORT &CNFG'
//STDERR   DD SYSOUT=*
//STDOUT   DD SYSOUT=*
//         PEND
//*
Notes:
  1. Refer to Operator commands for more information on the startup parameters.
  2. The sample JCL is initially shipped as FEK.SFEKSAMP(FEKRSED) and is renamed to FEK.#CUST.PROCLIB(RSED) in Customization setup.
  3. Limit the length of the job name to 7 characters or less. The modify and stop operator commands will fail with message "IEE342I MODIFY REJECTED-TASK BUSY" if an 8 character name is used. This behavior is caused by the z/OS UNIX design for child processes.
  4. This task, and the child processes it creates, must be assigned to SYSSTC or equivalent goal in Workload Manager (WLM). The child processes have the same name as the parent task, RSED, appended with a random 1-digit number, for example RSED8.

Lock daemon

Customize the sample started task member FEK.#CUST.PROCLIB(LOCKD), as described within the member, and copy it to SYS1.PROCLIB. As shown in the code sample below, you have to provide the following:

Figure 3. LOCKD - Lock daemon started task
//*
//* RSE LOCK DAEMON
//*
//LOCKD    PROC HOME='/usr/lpp/rdz',
//            CNFG='etc/rdz',
//            LOG=1
//*
//LOCKD    EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT,
              PARM=PGM &HOME./bin/lockd.sh &CNFG &LOG'
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//         PEND
//*
Notes:
  1. Refer to Operator commands for more information on the startup parameters.
  2. The sample JCL is initially shipped as FEK.SFEKSAMP(FEKLOCKD) and is renamed to FEK.#CUST.PROCLIB(LOCKD) in Customization setup.
  3. This task must be assigned to SYSSTC or equivalent goal in Workload Manager (WLM).

JCL limitations for the PARM variable

The maximum length for the PARM variable is 100 characters, which might cause problems if you use custom directory names. To bypass this problem, you can either:

ELAXF* remote build procedures

Developer for System z provides sample JCL procedures that can be used for the JCL generation, remote project builds, and remote syntax check features of CICS BMS maps, IMS MFS screens, COBOL, PL/I, Assembler, and C/C++ programs. These procedures allow installations to apply their own standards, and ensure that developers use the same procedures with the same compiler options and compiler levels.

The sample procedures and their function are listed in Table 7.

Table 7. Sample ELAXF* procedures
Member Purpose
ELAXFADT Sample procedure for assembling and debugging High Level assembler programs.
ELAXFASM Sample procedure for assembling High Level assembler programs.
ELAXFBMS Sample procedure for creating CICS BMS object and corresponding copy, dsect, or include member.
ELAXFCOC Sample procedure for doing COBOL Compiles, Integrated CICS translate and integrated DB2 translate.
ELAXFCOP Sample procedure for doing DB2 preprocess of EXEC SQL statements embedded in COBOL programs.
ELAXFCOT Sample procedure for doing CICS translation for EXEC CICS statements embedded in COBOL programs.
ELAXFCPC Sample procedure for doing C compiles.
ELAXFCPP Sample procedure for doing C++ compiles.
ELAXFCP1 Sample procedure for COBOL compiles with SCM preprocessor statements (-INC and ++INCLUDE).
ELAXFGO Sample procedure for the GO step.
ELAXFLNK Sample procedure for linking C/C++, COBOL. PLI and High Level Assembler programs.
ELAXFMFS Sample procedure for creating IMS MFS screens.
ELAXFPLP Sample procedure for doing DB2 preprocess of EXEC SQL statements embedded in PLI programs.
ELAXFPLT Sample procedure for doing CICS translation of EXEC CICS statements embedded in PLI programs.
ELAXFPL1 Sample procedure for doing PL/I compiles, integrated CICS translate and integrated DB2 translate.
ELAXFPP1 Sample procedure for PL/I compiles with SCM preprocessor statements (-INC and ++INCLUDE).
ELAXFTSO Sample procedure for running/debugging generated DB2 code in TSO mode.
ELAXFUOP Sample procedure for generating the UOPT step when building programs that run in CICS or IMS subsystems.

The names of the procedures and the names of the steps in the procedures match the default properties that are shipped with the Developer for System z client. If you decide to change the name of a procedure or the name of a step in a procedure, the corresponding properties file on all the clients should also be updated. We recommend that you do not change the procedure and step names.

Customize the sample build procedure members, FEK.#CUST.PROCLIB(ELAXF*), as described within the members, and copy them to SYS1.PROCLIB. You have to provide the correct high level qualifiers for different product libraries, as described in Table 8.

Table 8. ELAXF* high level qualifier checklist
Product Default HLQ Value
Developer for System z FEK
CICS CICSTS32.CICS
DB2 DSN910
IMS IMS
COBOL IGY.V4R1M0
PL/I IBMZ.V3R8M0
C/C++ CBC
LE CEE
system LINKLIB SYS1
system MACLIB SYS1

If the ELAXF* procedures cannot be copied into a system procedure library, ask the Developer for System z users to add a JCLLIB card (right after the JOB card) to the job properties on the client.

//MYJOB    JOB <job parameters>
//PROCS    JCLLIB ORDER=(FEK.#CUST.PROCLIB)

Security definitions

Customize and submit sample member FEKRACF in data set FEK.#CUST.JCL to create the security definitions for Developer for System z. The user submitting this job must have security administrator privileges, such as being RACF SPECIAL.

Note:

The following list of mandatory and optional security-related definitions for Developer for System z are discussed in detail in Security considerations. This chapter also discusses general security-related aspects of Developer for System z, including security aspects of requisite products that are not covered by the sample FEKRACF job.

Note:
The sample FEKRACF job holds more than just RACF commands. The last step of the security definitions consists of making a z/OS UNIX file program controlled. Depending on the policies at your site, this might be a task for the system programmer and not the security administrator.

FEJJCNFG, JES Job Monitor configuration file

JES Job Monitor (JMON) provides all JES-related services. The behavior of JES Job Monitor can be controlled with the definitions in FEJJCNFG.

FEJJCNFG is located in FEK.#CUST.PARMLIB, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Customize the sample JES Job Monitor configuration member FEJJCNFG, as shown in the following sample. Comment lines start with a pound sign (#), when using a US code page. Data lines can only have a directive and its assigned value, comments are not allowed on the same line.

Note:
The JMON started task must be restarted to pick up any changes you make.
Figure 6. FEJJCNFG, JES Job Monitor configuration file
HOST_CODEPAGE=IBM-1047
SERV_PORT=6715
TZ=EST5EDT
#_BPXK_SETIBMOPT_TRANSPORT=TCPIP
#APPLID=FEKAPPL
#AUTHMETHOD=SAF
#CODEPAGE=UTF-8
#CONCHAR=$
#CONSOLE_NAME=JMON
#GEN_CONSOLE_NAME=OFF
#LIMIT_COMMANDS=NOLIMIT
#LIMIT_VIEW=USERID
#LISTEN_QUEUE_LENGTH=5
#MAX_DATASETS=32
#MAX_THREADS=200
#TIMEOUT=3600
#TIMEOUT_INTERVAL=1200
#SUBMITMETHOD=TSO
#TSO_TEMPLATE=FEK.#CUST.CNTL(FEJTSO)
HOST_CODEPAGE
The host codepage. The default is IBM-1047. Change to match your host codepage.
SERV_PORT

The port number for JES Job Monitor host server. The default port is 6715. Change as desired, however, BOTH the server and the Developer for System z clients must be configured with the same port number. If you change the server port number, all clients must also change the JES Job Monitor port for this system in the Remote Systems View.

Notes:
  1. Before selecting a port, verify that the port is available on your system with the TSO commands NETSTAT and NETSTAT PORTL.
  2. When using a version 7.1 or higher client, all communication on this port is confined to your z/OS host machine.
TZ
Time zone selector. The default is EST5EDT. The default time zone is UTC +5 hours (Eastern Standard Time (EST) Eastern Daylight Savings Time (EDT)). Change this to represent your time zone. Additional information can be found in the UNIX System Services Command Reference (SA22-7802).

The following definitions are optional. If omitted, default values will be used as specified below:

_BPXK_SETIBMOPT_TRANSPORT=<tcpip stack name>
Specifies the name of the TCPIP stack to be used. The default is TCPIP. Uncomment and change to the requested TCPIP stack name, as defined in the TCPIPJOBNAME statement in the related TCPIP.DATA.
Note:
Coding a SYSTCPD DD statement in the server JCL does not set the requested stack affinity.
APPLID
Specifies the application identifier used for identifying JES Job Monitor to your security software. The default is FEKAPPL. Uncomment and change to the desired application ID.
Note:
This value must match the application ID set for RSE in the rsed.envvars configuration file. If these values differ, RSE cannot connect the client to JES Job Monitor.
AUTHMETHOD
The default is SAF, which means that the System Authorization Facility (SAF) security interface is used. Do not change unless directed to do so by the IBM support center.
CODEPAGE
The workstation codepage. The default is UTF-8. The workstation codepage is set to UTF-8 and generally should not be changed. You might need to uncomment the directive and change UTF-8 to match the workstation's codepage if you have difficulty with NLS characters, such as the currency symbol.
CONCHAR
Specifies the JES console command character. CONCHAR defaults to CONCHAR=$ for JES2, or CONCHAR=* for JES3. Uncomment and change to the requested command character.
CONSOLE_NAME
Specifies the name of the EMCS console used for issuing commands against jobs (Hold, Release, Cancel, and Purge). The default is JMON. Uncomment and change to the desired console name, using the guidelines below.

No matter which console name is used, the user ID of the client requesting the command is used as the LU of the console, leaving a trace in syslog messages IEA630I and IEA631.

IEA630I OPERATOR console NOW ACTIVE,   SYSTEM=sysid, LU=id
IEA631I OPERATOR console NOW INACTIVE, SYSTEM=sysid, LU=id
GEN_CONSOLE_NAME
Enables or disables automatic generating of alternative console names. The default is OFF. Uncomment and change to ON to enable alternative console names.

This directive is only used when CONSOLE_NAME equals &USERID and the user ID is not available as console name.

If GEN_CONSOLE_NAME=ON, an alternative console name is generated by appending a single numeric digit to the user ID. The digits 0 through 9 are attempted. If no available console is found, the command issued by the client fails.

If GEN_CONSOLE_NAME=OFF, the command issued by the client fails.

Note:
The only valid settings are ON and OFF.
LIMIT_COMMANDS
Defines against which jobs the user can issue selected JES commands (Show JCL, Hold, Release, Cancel, and Purge). The default (LIMIT_COMMANDS=USERID) limits the commands to jobs owned by the user. Uncomment this directive and specify LIMITED or NOLIMIT to allow the user to issue commands against all spool files, if permitted by your security product.
Table 9. LIMIT_COMMANDS command permission matrix
Job owner
LIMIT_COMMANDS User Other
USERID (default) Allowed Not allowed
LIMITED Allowed Allowed only if explicitly permitted by security profiles
NOLIMIT Allowed Allowed if permitted by security profiles or when the JESSPOOL class is not active
Note:
The only valid settings are USERID, LIMITED, and NOLIMIT.
LIMIT_VIEW
Defines what output the user can view. The default (LIMIT_VIEW=NOLIMIT) allows the user to view all JES output, if permitted by your security product. Uncomment this directive and specify USERID to limit the view to output owned by the user.
Note:
The only valid settings are USERID and NOLIMIT.
LISTEN_QUEUE_LENGTH
The TCP/IP listen queue length. The default is 5. Do not change unless directed to do so by the IBM support center.
MAX_DATASETS
The maximum number of spooled output data sets that JES Job Monitor will return to the client (for example, SYSOUT, SYSPRINT, SYS00001, and so on). The default is 32. The maximum value is 2147483647.
MAX_THREADS
Maximum number of users that can be using one JES Job Monitor at a time. The default is 200. The maximum value is 2147483647. Increasing this number may require you to increase the size of the JES Job Monitor address space.
TIMEOUT
The length of time, in seconds, before a thread is killed due to lack of interaction with the client. The default is 3600 (1 hour). The maximum value is 2147483647. TIMEOUT=0 disables the function.
TIMEOUT_INTERVAL
The number of seconds between timeout checks. The default is 1200. The maximum value is 2147483647.
SUBMITMETHOD=TSO
Submit jobs through TSO. The default (SUBMITMETHOD=JES) submits jobs directly into JES. Uncomment this directive and specify TSO to submit the job through TSO SUBMIT command. This method allows TSO exits to be invoked; however, it has a performance drawback and for that reason it is not recommended.
Notes:
  1. The only valid settings are TSO and JES.
  2. If SUBMITMETHOD=TSO is specified, then TSO_TEMPLATE must also be defined.
TSO_TEMPLATE
Wrapper JCL for submitting the job through TSO. The default value is FEK.#CUST.CNTL(FEJTSO). This statement refers to the fully qualified member name of the JCL to be used as a wrapper for the TSO submit. See the SUBMITMETHOD statement for more information.
Notes:
  1. A sample wrapper job is provided in FEK.#CUST.CNTL(FEJTSO). Refer to this member for more information on the customization needed.
  2. TSO_TEMPLATE has no effect unless SUBMITMETHOD=TSO is also specified.

rsed.envvars, RSE configuration file

The RSE lock daemon and the RSE server processes (RSE daemon, RSE thread pool, and RSE server) use the definitions in rsed.envvars. Optional Developer for System z and third-party services can use this configuration file also to define environment variables for their use.

Remote Systems Explorer (RSE) provides core services such as connecting the client to the host and starting other servers for specific services. Lock daemon provides tracking services for data set locks.

rsed.envvars is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

See the following sample rsed.envvars file, which must be customized to match your system environment. Comment lines start with a pound sign (#), when using a US code page. Data lines can only have a directive and its assigned value, comments are not allowed on the same line. Line continuations and spaces around the equal sign (=) are not supported.

Note:
The RSED and LOCKD started tasks must be restarted to pick up any changes you make.
Figure 7. rsed.envvars - RSE configuration file
#=============================================================
# (1) required definitions
JAVA_HOME=/usr/lpp/java/J5.0
RSE_HOME=/usr/lpp/rdz
_RSE_LOCKD_PORT=4036
_RSE_HOST_CODEPAGE=IBM-1047
TZ=EST5EDT
LANG=C
PATH=/bin:/usr/sbin
_CEE_DMPTARG=/tmp
STEPLIB=NONE
#STEPLIB=$STEPLIB:CEE.SCEERUN:CEE.SCEERUN2:CBC.SCLBDLL
_RSE_SAF_CLASS=/usr/include/java_classes/IRRRacf.jar
_RSE_JAVAOPTS=""
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xms1m -Xmx256m"
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Ddaemon.log=/var/rdz/logs"
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Duser.log=/var/rdz/logs"
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_LOG_DIRECTORY="
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.clients=60"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.threads=1000"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dminimum.threadpool.process=1"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.threadpool.process=100"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dipv6=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dkeep.last.log=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.standard.log=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.port.of.entry=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.certificate.mapping=false"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.audit.log=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Daudit.cycle=30"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Daudit.retention.period=0"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DAPPLID=OMVSAPPL"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDENY_PASSWORD_SAVE=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DHIDE_ZOS_UNIX=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_IDLE_SHUTDOWN_TIMEOUT=3600000"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_TRACING_ON=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_MEMLOGGING_ON=true"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DTSO_SERVER=APPC"
#=============================================================
# (2) required definitions for TSO/ISPF Client Gateway
_CMDSERV_BASE_HOME=/usr/lpp/ispf
_CMDSERV_CONF_HOME=/etc/rdz
_CMDSERV_WORK_HOME=/var/rdz
#STEPLIB=$STEPLIB:ISP.SISPLOAD:ISP.SISPLPA:SYS1.LINKLIB
_RSE_CMDSERV_OPTS=""
#_RSE_CMDSERV_OPTS="$_RSE_CMDSERV_OPTS&ISPPROF=&SYSUID..ISPPROF" 
#============================================================= 
# (3) required definitions for SCLM Developer Toolkit 
_SCLMDT_CONF_HOME=/var/rdz/sclmdt   
#STEPLIB=$STEPLIB:FEK.SFEKAUTH:FEK.SFEKLOAD  
#_SCLMDT_TRANTABLE=FEK.#CUST.LSTRANS.FILE  
#ANT_HOME=/usr/lpp/Apache/Ant/apache-ant-1.7.1  
#=============================================================  
# (4) optional definitions  
#_RSE_PORTRANGE=8108-8118  
#_BPXK_SETIBMOPT_TRANSPORT=TCPIP  
#_FEKFSCMD_TP_NAME_=FEKFRSRV 
#_FEKFSCMD_PARTNER_LU_=lu_name 
#GSK_CRL_SECURITY_LEVEL=HIGH 
#GSK_LDAP_SERVER=ldap_server_url 
#GSK_LDAP_PORT=ldap_server_port 
#GSK_LDAP_USER=ldap_userid 
#GSK_LDAP_PASSWORD=ldap_server_password 
#============================================================= 
Figure 8. (continued)
# (5) do not change unless directed by IBM support center 
_CEE_RUNOPTS="ALL31(ON) HEAP(32M,32K,ANYWHERE,KEEP,,) TRAP(ON)" 
_BPX_SHAREAS=YES 
_BPX_SPAWN_SCRIPT=YES 
JAVA_PROPAGATE=NO 
RSE_LIB=$RSE_HOME/lib 
PATH=.:$JAVA_HOME/bin:$RSE_HOME/bin:$_CMDSERV_BASE_HOME/bin:$PATH 
LIBPATH=$JAVA_HOME/bin:$JAVA_HOME/bin/classic:$RSE_LIB:$RSE_LIB/icuc 
LIBPATH=.:/usr/lib:$LIBPATH 
CLASSPATH=$RSE_LIB:$RSE_LIB/dstore_core.jar:$RSE_LIB/clientserver.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/dstore_extra_server.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/zosserver.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/dstore_miners.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/universalminers.jar:$RSE_LIB/mvsminers.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/carma.jar:$RSE_LIB/luceneminer.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/mvsluceneminer.jar:$RSE_LIB/cdzminer.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/mvscdzminer.jar:$RSE_LIB/jesminers.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/FAMiner.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/mvsutil.jar:$RSE_LIB/jesutils.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/lucene-core-2.3.2.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/cdtparser.jar 
CLASSPATH=$CLASSPATH:$RSE_LIB/wdzBidi.jar:$RSE_LIB/fmiExtensions.jar 
CLASSPATH=$CLASSPATH:$_RSE_SAF_CLASS 
CLASSPATH=.:$CLASSPATH 
_RSE_CMDSERV_OPTS="&SESSION=SPAWN$_RSE_CMDSERV_OPTS"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DISPF_OPTS='$_RSE_CMDSERV_OPTS'" 
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DA_PLUGIN_PATH=$RSE_LIB"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xbootclasspath/p:$RSE_LIB/bidiTools.jar"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dfile.encoding=$_RSE_HOST_CODEPAGE" 
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dconsole.encoding=$_RSE_HOST_CODEPAGE"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_SPIRIT_ON=true"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DSPIRIT_EXPIRY_TIME=6" 
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DSPIRIT_INTERVAL_TIME=6"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dcom.ibm.cacheLocalHost=true"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Duser.home=$HOME"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dclient.username=$RSE_USER_ID" 
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dlow.heap.usage.ratio=15"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.heap.usage.ratio=40"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_KEEPALIVE_ENABLED=true"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_KEEPALIVE_RESPONSE_TIMEOUT=60000" 
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_IO_SOCKET_READ_TIMEOUT=180000"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dlock.daemon.port=$_RSE_LOCKD_PORT"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dlock.daemon.cleanup.interval=1440"  
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -showversion"  
_RSE_SERVER_CLASS=org.eclipse.dstore.core.server.Server  
_RSE_DAEMON_CLASS=com.ibm.etools.zos.server.RseDaemon  
_RSE_POOL_SERVER_CLASS=com.ibm.etools.zos.server.ThreadPoolProcess  
_RSE_LOCKD_CLASS=com.ibm.ftt.rse.mvs.server.miners.MVSLockDaemon 
_RSE_SERVER_TIMEOUT=120000 
_SCLMDT_BASE_HOME=$RSE_HOME 
_SCLMDT_WORK_HOME=$_CMDSERV_WORK_HOME 
CGI_DTWORK=$_SCLMDT_WORK_HOME 
#============================================================= 
# (6) additional environment variables
Note:
Symbolic links are allowed when specifying directories in rsed.envvars.

The following definitions are required:

JAVA_HOME
Java home directory. The default is /usr/lpp/java/J5.0. Change to match your Java installation.
RSE_HOME
RSE home directory. The default is /usr/lpp/rdz. Change to match your Developer for System z installation.
_RSE_LOCKD_PORT
RSE lock daemon port number. The default is 4036. Can be changed if desired.
Notes:
  1. Before selecting a port, verify that the port is available on your system with the TSO commands NETSTAT and NETSTAT PORTL.
  2. All communication on this port is confined to your z/OS host machine.
_RSE_HOST_CODEPAGE
The host codepage. The default is IBM-1047. Change to match your host codepage.
TZ
Time zone selector. The default is EST5EDT. The default time zone is UTC +5 hours (Eastern Standard Time (EST) Eastern Daylight Savings Time (EDT)). Change to match your time zone.

Additional information can be found in the UNIX System Services Command Reference (SA22-7802).

LANG
Specifies the name of the default locale. The default is C. C specifies the POSIX locale and (for example) Ja_JP specifies the Japanese locale. Change to match your locale.
PATH
Command path. The default is /bin:/usr/sbin:.. Can be changed if desired.
_CEE_DMPTARG
Language Environment (LE) z/OS UNIX dump location used by the Java Virtual Machine (JVM). The default is /tmp.
STEPLIB
Access MVS data sets not in LINKLIST/LPALIB. The default is NONE.

You can bypass the need of having (prerequisite) libraries in LINKLIST/LPALIB by uncommenting and customizing one or more of the following STEPLIB directives. Refer to PARMLIB changes for more information on the usage of the libraries listed below:

STEPLIB=$STEPLIB:CEE.SCEERUN:CEE.SCEERUN2:CBC.SCLBDLL
STEPLIB=$STEPLIB:ISP.SISPLOAD:ISP.SISPLPA:SYS1.LINKLIB
STEPLIB=$STEPLIB:FEK.SFEKAUTH:FEK.SFEKLOAD
Note:
  • Using STEPLIB in z/OS UNIX has a negative performance impact.
  • If one STEPLIB library is APF authorized, then all must be authorized. Libraries lose their APF authorization when they are mixed with non-authorized libraries in STEPLIB.
  • Libraries that are designed for LPA placement might require additional program control and APF authorizations if they are accessed through LINKLIST or STEPLIB.
  • Coding a STEPLIB DD statement in the server JCL does not set the requested STEPLIB concatenation.
RSE_SAF_CLASS
Specifies the Java interface to your security product. The default is /usr/include/java_classes/IRRRacf.jar. Change to match your security software setup.
Note:
Since z/OS 1.10, /usr/include/java_classes/IRRRacf.jar is part of SAF, which ships with base z/OS, so it is available also to non-RACF customers.
RSE_JAVAOPTS
Additional RSE-specific Java options. . See Defining extra Java startup parameters with _RSE_JAVAOPTS for more information on this definition.

Developer for System z uses ISPF's TSO/ISPF Client Gateway by default for the TSO Commands service. An APPC transaction is used instead when the following _RSE_JAVAOPTS option is uncommented:

RSE_JAVAOPTS="$_RSE_JAVAOPTS -DTSO_SERVER=APPC"

The following definitions are required if ISPF's TSO/ISPF Client Gateway is used for the TSO Commands service, SCLM Developer Toolkit or CARMA.

_CMDSERV_BASE_HOME
Home directory for the ISPF code that provides the TSO/ISPF Client Gateway service. The default is /usr/lpp/ispf. Change to match your ISPF installation. This directive is only required when ISPF's TSO/ISPF Client Gateway is used.
_CMDSERV_CONF_HOME
ISPF base configuration directory. The default is /etc/rdz. Change to match the location of ISPF.conf, the TSO/ISPF Client Gateway customization file. This directive is only required when ISPF's TSO/ISPF Client Gateway is used.
_CMDSERV_WORK_HOME
ISPF base work directory. The default is /var/rdz. Change to match the location of the WORKAREA directory used by the TSO/ISPF Client Gateway. This directive is only required when ISPF's TSO/ISPF Client Gateway is used.

Notes®:

STEPLIB
STEPLIB is described previously in the required definitions section.
RSE_CMDSERV_OPTS
Additional TSO/ISPF Client Gateway specific Java options. The default is "". See Defining extra Java startup parameters with _RSE_CMDSERV_OPTS for more information on this definition. This directive is only required when ISPF's TSO/ISPF Client Gateway is used.

The following definitions are required if SCLM Developer Toolkit is used.

SCLMDT_CONF_HOME
SCLM Developer Toolkit base configuration directory. The default is /var/rdz/sclmdt. Change to match the location of the CONFIG directory used by SCLMDT to store SCLM project information. This directive is only required when SCLMDT is used.
Note:
SCLMDT will add /CONFIG and /CONFIG/PROJECT to the path specified in SCLMDT_CNF_HOME. Do not add it yourself.
STEPLIB
STEPLIB is described previously in the required definitions section.
_SCLMDT_TRANTABLE
Name of the long/short name translation VSAM. The default is FEK.#CUST.LSTRANS.FILE. Uncomment and change to match the name used in the SCLM sample job ISP.SISPSAMP(FLM02LST). This directive is only required if the long/short name translation in SCLM Developer Toolkit is used.
ANT_HOME
Home directory for your Ant installation. The default is /usr/lpp/Apache/Ant/apache-ant-1.7.1. Change to match your Ant installation. This directive is only required when the JAVA/J2EE build support is used with SCLM Developer Toolkit.

The following definitions are optional. If omitted, default values will be used:

_RSE_PORTRANGE
Specifies the port range that the RSE server can open for communication with a client. Any port can be used by default. See Defining the PORTRANGE available for RSE for more information on this definition. This is an optional directive.
BPXK_SETIBMOPT_TRANSPORT
Specifies the name of the TCP/IP stack to be used. The default is TCPIP. Uncomment and change to the requested TCP/IP stack name, as defined in the TCPIPJOBNAME statement in the related TCPIP.DATA. . This is an optional directive.
Note:
Coding a SYSTCPD DD statement in the server JCL does not set the requested stack affinity.
_FEKFSCMD_TP_NAME_
APPC transaction program name. The default value is FEKFRSRV. Uncomment and change this definition if you did not use the default transaction program name when defining the APPC transaction. This is an optional directive.
_FEKFSCMD_PARTNER_LU_
Force RSE server to use this APPC partner LU. The default is the base LU specified during APPC configuration. This is an optional directive.
GSK_CRL_SECURITY_LEVEL
Specifies the level of security SSL applications will use when contacting LDAP servers to check CRLs for revoked certificates during certificate validation. The default is MEDIUM. Uncomment and change to enforce the usage of the specified value. This is an optional directive. The following values are valid:
Note:
This directive requires z/OS 1.9 or higher.
GSK_LDAP_SERVER
Specifies one or more blank-separated LDAP server host names. Uncomment and change to enforce the usage of the specified LDAP servers to obtain their CRL. This is an optional directive.

The host name can either be a TCP/IP address or an URL. Each host name can contain an optional port number separated from the host name by a colon (:).

GSK_LDAP_PORT
Specifies the LDAP server port. The default is 389. Uncomment and change to enforce the usage of the specified value. This is an optional directive.
GSK_LDAP_USER
Specifies the distinguished name to use when connecting to the LDAP server. Uncomment and change to enforce the usage of the specified value. This is an optional directive.
GSK_LDAP_PASSWORD
Specifies the password to use when connecting to the LDAP server. Uncomment and change to enforce the usage of the specified value. This is an optional directive.

The following definitions are required, and should not be changed unless directed by the IBM support center:

_CEE_RUNOPTS
Language Environment (LE) runtime options. The default is "ALL31(ON) HEAP(32M,32K,ANYWHERE,KEEP,,) TRAP(ON)". Do not modify.
_BPX_SHAREAS
Run foreground processes in the same address space as the shell. The default is YES. Do not modify.
_BPX_SPAWN_SCRIPT
Run shell scripts directly from the spawn() function. The default is YES. Do not modify.
JAVA_PROPAGATE
Propagates the security and workload context during thread creation (Java version 1.4 and older only). The default is NO. Do not modify.
RSE_LIB
RSE library path. The default is $RSE_HOME/lib. Do not modify.
PATH
Command path. The default is .:$JAVA_HOME/bin:$RSE_HOME/bin:$_CMDSERV_BASE_HOME/bin:$PATH. Do not modify.
LIBPATH
Library path. The default is too long to repeat. Do not modify.
CLASSPATH
Class path. The default is too long to repeat. Do not modify.
_RSE_CMDSERV_OPTS
Additional TSO Commands service-specific Java options. The default is "&SESSION=SPAWN$_RSE_CMDSERV_OPTS". Do not modify.
_RSE_JAVAOPTS
Additional RSE-specific Java options. The default is too long to repeat. Do not modify.
_RSE_SERVER_CLASS
Java class for the RSE server. The default is org.eclipse.dstore.core.server.Server. Do not modify.
_RSE_DAEMON_CLASS
Java class for the RSE daemon. The default is com.ibm.etools.zos.server.RseDaemon. Do not modify.
_RSE_POOL_SERVER_CLASS
Java class for the RSE thread pool. The default is com.ibm.etools.zos.server.ThreadPoolProcess. Do not modify.
_RSE_LOCKD_CLASS
Java class for the RSE lock daemon. The default is com.ibm.ftt.rse.mvs.server.miners.MVSLockDaemon. Do not modify.
_RSE_SERVER_TIMEOUT
Time out value for the RSE server (waiting on the client) in milliseconds. The default is 120000 (2 minutes). Do not modify.
SCLMDT_BASE_HOME
Home directory for SCLM Developer Toolkit code. The default is $RSE_HOME. Do not modify.
SCLMDT_WORK_HOME
SCLM Developer Toolkit base work directory. The default is $_CMDSERV_WORK_HOME. Do not modify.
CGI_DTWORK
SCLM Developer Toolkit support for older clients. The default is $_SCLMDT_WORK_HOME. Do not modify.

Defining the PORTRANGE available for RSE

This is a part of rsed.envvars customization that specifies the ports on which the RSE server can communicate with the client. This range of ports has no connection with the RSE daemon port.

To help understand the port usage, a brief description of RSE's connection process follows:

  1. The client connects to host port 4035, RSE daemon.
  2. The RSE daemon creates an RSE server thread.
  3. The RSE server opens a host port for the client to connect. The selection of this port can be configured by the user, either on the client in the subsystem properties tab (this is not recommended) or through the _RSE_PORTRANGE definition in rsed.envvars.
  4. The RSE daemon returns the port number to the client.
  5. The client connects to the host port.
Note:

To specify the port range, for the client to communicate with z/OS, uncomment and customize the following line in rsed.envvars:

#_RSE_PORTRANGE=8108-8118
Note:
Before selecting a port range, verify that the range is available on your system with the NETSTAT and NETSTAT PORTL commands.

The format of PORTRANGE is: _RSE_PORTRANGE=min-max (max is non-inclusive; for example _RSE_PORTRANGE=8108-8118 means port numbers from 8108 up to 8117 are usable). The port number used by the RSE server is determined in the following order:

  1. If a nonzero port number is specified in the subsystem properties on the client, then the specified port number is used. If the port is not available connect will fail. This setup is not recommended.
  2. If the port number in the subsystem properties is 0, and if _RSE_PORTRANGE is specified in rsed.envvars, then the port range specified by _RSE_PORTRANGE is used. If no port in the range is available, connect will fail.
  3. If the port number in the subsystem properties is 0, and _RSE_PORTRANGE is not specified in rsed.envvars, then any available port is used.
Note:
When a server opens a port and is listening, the port number cannot be used by another server, but once it is connected, the same port number can be used again. This means that the number of ports in the range does not limit the number of users connected concurrently.

Defining extra Java startup parameters with _RSE_JAVAOPTS

With the different _RSE_*OPTS directives, rsed.envvars provides the possibility to give extra parameters to Java when it starts the RSE processes. The sample options included in rsed.envvars can be activated by uncommenting them.

_RSE_JAVAOPTS defines standard and RSE-specific Java options.

_RSE_JAVAOPTS=""
Variable initialization. Do not modify.
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xms1m -Xmx256m"
Set initial (Xms) and maximum (Xmx) heap size. The defaults are 1M and 256M respectively. Change to enforce the desired heap size values. If this directive is commented out, the Java default values will be used, which are 1M and 64M respectively.
Note:
Refer to Tuning considerations to determine the optimal values for this directive.
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Ddaemon.log=/var/rdz/logs"
Directory holding the RSE daemon and server logging and RSE audit data. The default is /var/rdz/logs. Change to enforce the desired location. If this directive is commented out, the home directory of the user ID assigned to RSE daemon will be used. The home directory is defined in the OMVS security segment of the user ID.
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Duser.log=/var/rdz/logs"
Directory leading to the user-specific logs. The default is /var/rdz/logs. Change to enforce the desired location. If this directive is commented out, the home directory of the client user ID will be used. The home directory is defined in the OMVS security segment of the user ID.
Notes:
  1. The complete path to the user logs is userlog/dstorelog/$LOGNAME/, where userlog is the value of the user.log directive, dstorelog is the value of the DSTORE_LOG_DIRECTORY directive and $LOGNAME is the client's user ID in uppercase.
  2. Ensure that the permission bits for userlog/dstorelog are set so that each client can create $LOGNAME.
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_LOG_DIRECTORY="
This directory is appended to the path specified in the user.log directive. Together they create the path leading to the user-specific logs. The default is a null-string. Change to enforce the usage of the specified directory. If this directive is commented out, .eclipse/RSE/ will be used.
Notes:
  1. The complete path to the user logs is userlog/dstorelog/$LOGNAME/, where userlog is the value of the user.log directive, dstorelog is the value of the DSTORE_LOG_DIRECTORY directive, and $LOGNAME is the client's user ID in uppercase.
  2. The directory specified here is relative to the directory specified in user.log, and thus may not start with a forward slash (/).
  3. Ensure that the permission bits for userlog/dstorelog are set so that each client can create $LOGNAME.

The following directives are commented out by default.

#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.clients=60"
Maximum amount of clients serviced by one thread pool. The default is 60. Uncomment and customize to limit the number of clients per thread pool. Note that other limits may prevent RSE from reaching this limit.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.threads=1000"
Maximum amount of threads serviced by one thread pool. The default is 1000. Uncomment and customize to limit the number of threads per thread pool. Note that each client connection uses multiple threads (16 or more) and that other limits may prevent RSE from reaching this limit.
Note:
This value must be lower than the setting for MAXTHREADS and MAXTHREADTASKS in SYS1.PARMLIB(BPXPRMxx).
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dminimum.threadpool.process=1"
The minimum number of active thread pools. The default is 1. Uncomment and customize to start at least the listed number of thread pool processes. Thread pool processes are used for load balancing the RSE server threads. More new processes are started when they are needed. Starting the new processes up front helps prevent connection delays but uses more resources during idle times.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.threadpool.process=100"
The maximum number of active thread pools. The default is 100. Uncomment and customize to limit the number of thread pool processes. Thread pool processes are used for load balancing the RSE server threads, so limiting them will limit the amount of active client connections.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dipv6=true"
TCP/IP version. The default is false, which means that an IPv4 interface will be used. Uncomment and specify true to use an IPv6 interface.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dkeep.last.log=true"
Keep a copy of the host log files belonging to the previous session. The default is false. Uncomment and specify true to rename the previous log files to *.last during server startup and client connect.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.standard.log=true"
Write the stdout and stderr streams of the thread pools to a log file. The default is false. Uncomment and specify true to save the stdout and stderr streams. The resulting log files are located in the directory referenced by the daemon.log directive.
Notes:
  1. The MODIFY RSESTANDARDLOG operator command can be used to dynamically stop or start the update of the stream log files.
  2. There are no user-specific stdout.log and stderr.log log files when the enable.standard.log directive is active. The user-specific data is now written to the matching RSE thread pool stream.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.port.of.entry=true"
Port Of Entry (POE) check option. The default is false. Uncomment and specify true to enforce POE checking for client connections. During POE checking, the IP address of the client is mapped into a network access security zone by your security software. The client user ID must have permission to use the profile that defines the security zone.
Notes:
  1. POE checking must also be enabled in your security product.
  2. Enabling POE checking will enable it for other z/OS UNIX services also, such as INETD.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.certificate.mapping=false"
Use your security software to authenticate a logon with a X.509 certificate. The default is true. Uncomment and specify false to have RSE daemon do the authentication without relying on the X.509 support of your security software.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Denable.audit.log=true"
Audit option. The default is false. Uncomment and specify true to enforce audit logging of actions done by clients. Audit logs are written to the RSE daemon log location. See the daemon.log option of the _RSE_JAVAOPTS variable to know where this is.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Daudit.cycle=30"
Number of days stored in 1 audit log file. The default is 30. Uncomment and customize to control how much audit data is written to 1 audit log file. The maximum value is 365.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Daudit.retention.period=0"
Number of days audit logs are kept. The default is 0 (no limit). Uncomment and customize to delete audit logs after a given number of days. The maximum value is 365.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DAPPLID=OMVSAPPL"
RSE server application ID. The default is FEKAPPL. Uncomment and customize this option to enforce the use of the desired application ID. OMVSAPPL is used by z/OS UNIX itself and z/OS UNIX based processes that do not create a unique application ID.
Note:
The application ID must be defined to your security software. Failure to do so will prevent the client from logging on.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDENY_PASSWORD_SAVE=true"
Password save option. The default is false. Uncomment and specify true to prevent users from saving their host password on the client. Previously saved passwords will be removed. This option only works with clients version 7.1 and higher.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DHIDE_ZOS_UNIX=true"
Hide z/OS UNIX option. The default is false. Uncomment and specify true to prevent users from seeing z/OS UNIX elements (directory structure and command line) on the client. This option only works with clients version 7.6 and higher.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_IDLE_SHUTDOWN_TIMEOUT=3600000"
Disconnect idle clients. By default, idle clients are not disconnected. Uncomment and customize to disconnect clients who are idle for the listed amount of milliseconds (3600000 equals 1 hour).
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_TRACING_ON=true"
Start dstore tracing. Use only when directed by the IBM support center. Note that the resulting .dstoreTrace log file is created in Unicode (ASCII), not EBCDIC.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DDSTORE_MEMLOGGING_ON=true"
Start dstore memory tracing. Use only when directed by the IBM support center. Note that the resulting .dstoreMemLogging log file is created in Unicode (ASCII), not EBCDIC.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DTSO_SERVER=APPC"
Use an APPC transaction for the TSO Commands service. By default, ISPF's TSO/ISPF Client Gateway is used. Uncomment to use an APPC transaction instead. Do not change the assigned value.

Defining extra Java startup parameters with _RSE_CMDSERV_OPTS

With the different _RSE_*OPTS directives, rsed.envvars provides the possibility to give extra parameters to Java when it starts the RSE processes. The sample options included in rsed.envvars can be activated by uncommenting them.

The _RSE_CMDSERV_OPTS directives are RSE-specific Java options and are only in effect when ISPF's TSO/ISPF Client Gateway is used by the Developer for System z. (This is the default.)

_RSE_CMDSERV_OPTS=""
Variable initialization. Do not modify.
_RSE_CMDSERV_OPTS="$_RSE_CMDSERV_OPTS &ISPROF=&SYSUID..ISPROF="
Use an existing ISPF profile for the ISPF initialization. Uncomment and change the data set name to use the specified ISPF profile.

The following variables can be used in the data set name:

ISPF.conf, ISPF's TSO/ISPF Client Gateway configuration file

ISPF's TSO/ISPF Client Gateway uses the definitions in ISPF.conf to create a valid environment to execute batch TSO and ISPF commands. Developer for System z uses this environment to run some MVS based services. These services include the TSO Commands service, SCLM Developer Toolkit service and an alternate CARMA startup method.

ISPF.conf is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

Comment lines start with an asterisk (*) when using a US code page. Data lines can only have a directive and its assigned value. Comments are not allowed on the same line. Line continuations are not supported. When concatenating data set names, add them on the same line and separate the names with a comma (,).

In addition to providing the correct names for the ISPF data sets, you must also add the TSO Commands service data set name, FEK.SFEKPROC, to the SYSPROC or SYSEXEC statement, as shown in the following example.

Figure 9. ISPF.conf - ISPF configuration file
* REQUIRED:
sysproc=ISP.SISPCLIB,FEK.SFEKPROC
ispmlib=ISP.SISPMENU
isptlib=ISP.SISPTENU
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB

* OPTIONAL:
*allocjob = FEK.#CUST.CNTL(CRAISPRX)
*ISPF_timeout = 900
Notes:
  1. You can add your own DD-like statements and data set concatenations to customize the TSO environment, thus mimicking a TSO logon procedure. See Customizing the TSO environment for more details.
  2. The TSO/ISPF Client Gateway may not function properly if you use a (third party) product that intercepts ISPF commands, such as ISPSTART. Check the documentation for that product on how it can be disabled for Developer for System z. If the product requires the allocation of a specific DD statement to DUMMY, you can simulate this in ISPF.conf by allocating that DD statement to nullfile.

    For example:

    ISPTRACE=nullfile
  3. When using the allocjob directive, be careful not to undo the DD definitions done earlier in ISPF.conf.
  4. System abend 522 for module ISPZTSO is to be expected if the JWT parameter in the SMFPRMxx parmlib member is set lower than the ISPF_timeout value in ISPF.conf. This does not impact Developer for System z operations, as the TSO/ISPF Client Gateway is restarted automatically when needed.
  5. Changes are active for all new invocations. No server restart is needed.

Optional components

The customization steps above are for a basic Developer for System z setup. Refer to the chapters about the optional components for their customization requirements:

(Optional) Common Access Repository Manager (CARMA)

Common Access Repository Manager (CARMA) is a productivity aid for developers who are creating Repository Access Managers (RAMs). A RAM is an Application Programming Interface (API) for z/OS based Software Configuration Managers (SCMs).

In turn, user-written applications can start a CARMA server which loads the RAMs and provides a standard interface to access the SCM.

Developer for System z supports multiple methods to start a CARMA server, each with their own benefits and drawbacks.

Requirements and checklist

You will need the assistance of a security administrator and a TCP/IP administrator to complete this customization task, which requires the following resources or special customization tasks:

In order to start using CARMA at your site, you must perform the following tasks. Unless otherwise indicated, all tasks are mandatory.

  1. Create required CARMA components. For details, see CARMA components.
  2. Initial customization of RSE configuration files to interface with CARMA. The complete customization is dependent on the method chosen to start CARMA. For details, see RSE interface to CARMA.
  3. Choose a method to start CARMA and do the required customization of the related configuration files. For details see:
  4. Optionally activate sample Repository Access Managers (RAMs). For details see (Optional) Activating the sample Repository Access Managers (RAMs).
  5. Optionally activate CA Endevor® RAM. For details see (Optional) Activating the CA Endevor® RAM.
  6. Optionally create CRAXJCL as replacement for IRXJCL. For details, see (Optional) IRXJCL versus CRAXJCL.
Note:
The sample members referenced in this chapter are located in FEK.#CUST.* and /etc/rdz, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

CARMA components

The following CARMA components must be customized, regardless of the chosen startup method. The sample members referenced below are located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

  1. Customize and submit the FEK.#CUST.JCL(CRA$VDEF) JCL. Refer to the documentation within CRA$VDEF for customization instructions. CRA$VDEF creates and primes the CARMA configuration VSAM data set, CRADEF.
  2. Customize and submit the FEK.#CUST.JCL(CRA$VMSG) JCL. Refer to the documentation within CRA$VMSG for customization instructions. CRA$VMSG creates and primes the CARMA message VSAM data set, CRAMSG.
  3. Customize and submit the FEK.#CUST.JCL(CRA$VSTR) JCL. Refer to the documentation within CRA$VSTR for customization instructions. CRA$VSTR creates and primes the CARMA custom information VSAM data set, CRASTRS.
Note:

RSE interface to CARMA

The CARMA server provides a standard API for other host-based products to access one or more Software Configuration Managers (SCMs). However, it does not provide methods for direct communication with a client PC. For this, it relies on other products, such as the RSE server. The RSE server uses the settings in CRASRV.properties to start and connect to a CARMA server.

CRASRV.properties is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

Note:
The RSED started task must be restarted to pick up any changes you make.
Figure 10. CRASRV.properties - CARMA configuration file
# CRASRV.properties - CARMA configuration options
#
port.start=5227
port.range=100
startup.script.name=/usr/lpp/rdz/bin/carma.startup.rex
clist.dsname='FEK.#CUST.CNTL(CRASUBMT)'
crastart.stub=/usr/lpp/rdz/bin/CRASTART
crastart.configuration.file=/etc/rdz/crastart.conf
crastart.syslog=Partial
crastart.timeout=420
#crastart.steplib=FEK.SFEKLPA
#crastart.tasklib=TASKLIB
port.start
First port used for communication between CARMA and the RSE server. The default port is 5227. Communication on this port is confined to your host machine.
Note:
Before selecting a port, verify that the port is available on your system with the NETSTAT and NETSTAT PORTL commands. See Reserved TCP/IP ports for more information.
port.range
Range of ports, starting at port.start, which will be used for CARMA communication. The default is 100. For example, when using the defaults, port 5227 until 5326 (inclusive) can be used by CARMA.
startup.script.name
Defines the absolute path of the CARMA startup script. The default is /usr/lpp/rdz/bin/carma.startup.rex. This REXX exec will trigger the startup of a CARMA server.
clist.dsname
Defines the startup method for the CARMA server.

The default is 'FEK.#CUST.CNTL(CRASUBMT)'. This CLIST will start a CARMA server when opening a connection using the batch submit method.

crastart.stub
z/OS UNIX stub for calling CRASTART. The default is /usr/lpp/rdz/bin/CRASTART. This stub makes the MVS based CRASTART load module available to z/OS UNIX processes. This directive is only used if the clist.dsname directive has *CRASTART as value.
crastart.configuration.file
Specifies the name of the CRASTART configuration file. The default is /etc/rdz/crastart.conf. This file specifies the data set allocations and program invocations needed to start a CARMA server. This directive is only used if the clist.dsname directive has *CRASTART as value.
crastart.syslog
Specifies how much information is written to the system log while CRASTART starts a CARMA server. The default is Partial. Valid values are:
A (All) All tracing information is printed to SYSLOG
P (Partial) Only connect, disconnect, and error information is printed to SYSLOG
anything else Only error conditions are printed to SYSLOG

This directive is only used if the clist.dsname directive has *CRASTART as value.

crastart.timeout
The length of time, in seconds, before a CARMA server ends due to lack of activity. The default is 420 (7 minutes). This directive is only used if the clist.dsname directive has *CRASTART as value.
crastart.steplib
The location of the CRASTART module when accessed through the STEPLIB directive in rsed.envvars. The default is FEK.SFEKLPA. Uncomment and customize this directive if the CRASTART module cannot be part of LPA or LINKLIST. Note that program control and APF issues may arise if the CRASTART module is not in LPA. This directive is only used if the clist.dsname directive has *CRASTART as value.
crastart.tasklib
Alternate name for the TASKLIB DD name in crastart.conf. The default is TASKLIB. Uncomment and customize this directive if DD name TASKLIB has a special meaning for your SCM or RAM and cannot be used as STEPLIB replacement. This directive is only used if the clist.dsname directive has *CRASTART as value.

CARMA server startup using batch submit

The information in this section describes how to configure the default method for Developer for System z to start a CARMA server. This customization step can be bypassed if you use another startup method.

Developer for System z uses by default the batch submit CARMA server startup method that does not require the CRASTART module to be in LPA and does not depend on the TSO/ISPF Client Gateway. The method submits the CARMA server as a long-running batch job in your JES.

Adjust CRASRV.properties

RSE server uses the settings in /etc/rdz/CRASRV.properties to start and connect to a CARMA server, as documented in RSE interface to CARMA. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect.

Change the value of the clist.dsname directive to the data set and member name of the CRASUBMT CARMA server startup CLIST, as shown in the following example:

Figure 11. CRASRV.properties - CARMA startup using batch submit
port.start=5227
port.range=100
startup.script.name=/usr/lpp/rdz/bin/carma.startup.rex
clist.dsname='FEK.#CUST.CNTL(CRASUBMT)'

Adjust CRASUBMT

Customize the CRASUBMT CLIST, as shown in the following code sample. Refer to the documentation within CRASUBMT for customization instructions. The CRASUBMT CLIST submits a CARMA server.

CRASUBMT is located in FEK.#CUST.CNTL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Figure 12. CRASUBMT - CARMA startup using batch submit
PROC 1 PORT TIMEOUT(420)
SUBMIT * END($$)
//CRA&PORT JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1)
//RUN      EXEC PGM=IKJEFT01,DYNAMNBR=25,REGION=1024K,TIME=NOLIMIT
//STEPLIB  DD DISP=SHR,DSN=FEK.SFEKLOAD
//*        DD DISP=SHR,DSN=FEK.#CUST.LOAD
//CRADEF   DD DISP=SHR,DSN=FEK.#CUST.CRADEF
//CRAMSG   DD DISP=SHR,DSN=FEK.#CUST.CRAMSG
//CRASTRS  DD DISP=SHR,DSN=FEK.#CUST.CRASTRS
//*CRARAM1  DD DISP=SHR,DSN=FEK.#CUST.CRARAM1
//*
//ISPPROF  DD DISP=(NEW,DELETE,DELETE),DSN=&&PROF,
//            SPACE=(TRK,(1,1,5)),LRECL=80,RECFM=FB,UNIT=SYSALLDA
//ISPMLIB  DD DISP=SHR,DSN=ISP.SISPMENU
//ISPPLIB  DD DISP=SHR,DSN=ISP.SISPPENU
//ISPSLIB  DD DISP=SHR,DSN=ISP.SISPSENU
//ISPTLIB  DD DISP=SHR,DSN=ISP.SISPTENU
//ISPEXEC  DD DISP=SHR,DSN=ISP.SISPEXEC
//SYSPROC  DD DISP=SHR,DSN=ISP.SISPCLIB
//*
//CARMALOG DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
ISPSTART PGM(CRASERV) PARM(&PORT &TIMEOUT)
//*
$$
EXIT CODE(0)
Notes:
  1. You can add your own DD statements and data set concatenations to customize the CARMA TSO environment, thus mimicking a TSO logon procedure.
  2. You can optionally change CARMA's timeout value by modifying the PROC 1 PORT TIMEOUT(420) line in FEK.#CUST.CNTL(CRASUBMT) CLIST. The timeout value is the number of seconds CARMA will wait for the next command from the client. Setting a value of 0 results in the default timeout value, currently 420 seconds (7 minutes).
  3. Details of the CARMA startup process are shown in rsecomm.log. Refer to (Optional) RSE tracing for more information on setting the detail level of rsecomm.log.
  4. Changes are in effect for all CARMA servers started after the update.

(Optional) Alternative CARMA server startup using CRASTART

The information in this section describes how to configure an alternative method for Developer for System z to start a CARMA server. This customization step can be bypassed if you use another startup method.

Developer for System z supports an alternative CARMA server startup method that does not depend on the TSO/ISPF Client Gateway and that does not submit a server job using a JES initiator. The method uses CRASTART to start the CARMA server as a subtask within RSE and is similar to the TSO/ISPF Client Gateway service.

Note:
Details of the CARMA startup process are shown in rsecomm.log. Refer to (Optional) RSE tracing for more information on setting the detail level of rsecomm.log.

Adjust CRASRV.properties

RSE server uses the settings in /etc/rdz/CRASRV.properties to start and connect to a CARMA server, as documented in RSE interface to CARMA. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect.

Change the value of the clist.dsname directive to *CRASTART and provide the correct values for the crastart.* directives, as shown in the following example:

Figure 13. CRASRV.properties - *CRASTART alternative CARMA startup
port.start=5227
port.range=100
startup.script.name=/usr/lpp/rdz/bin/carma.startup.rex
clist.dsname=*CRASTART
crastart.stub=/usr/lpp/rdz/bin/CRASTART
crastart.configuration.file=/etc/rdz/crastart.conf
crastart.syslog=Partial
crastart.timeout=420
#crastart.steplib=FEK.SFEKLPA
#crastart.tasklib=TASKLIB
Note:
System abend 522 for module CRASERV is to be expected if the JWT parameter in the SMFPRMxx parmlib member is set lower than the time out value in CRASRV.properties. This does not impact CARMA operations, as the server is restarted automatically if needed.

Adjust crastart.conf

Keep a printout of the customized CRASUBMT (see CARMA server startup using batch submit) handy for easy reference during this customization step. The printout will be valuable even if you have not customized the member.

CRASTART uses the definitions in crastart.conf to create a valid environment to execute batch TSO and ISPF commands. Developer for System z uses this environment to run the CARMA server called CRASERV.

crastart.conf is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

Note:
Changes are in effect for all CARMA servers started after the update.

The following customization steps are needed to adjust the configuration file shown in the code sample below.

Note:
crastart.conf definitions cannot be split across multiple lines.
Figure 14. crastart.conf - *CRASTART alternative CARMA startup
* crastart.conf - CARMA allocation options

TASKLIB  = FEK.SFEKLOAD
CRADEF   = FEK.#CUST.CRADEF
CRAMSG   = FEK.#CUST.CRAMSG
CRASTRS  = FEK.#CUST.CRASTRS
*CRARAM1  = FEK.#CUST.CRARAM1
*
CARMALOG = SYSOUT(H)
SYSTSPRT = SYSOUT(H)
SYSTSIN  = DUMMY
-COMMAND=ALLOC FI(SCRATCH) NEW DELETE DSORG(PS) RECFM(F,B) LRECL(80) UNIT(VIO)
*
PROGRAM=IKJEFT01 CRASERV &CRAPRM1. &CRAPRM2.

The following variables can be used in the configuration file:

Table 10. crastart.conf variables
&CRAUSER. Logon user ID of the client.
&CRADATE. Current® date in Dyyyyddd format (7 character Julian).
&CRATIME. Current time in Thhmmss format (hour minute second).
&CRAPRM3. through &CRAPRM9. Additional variables with user-assigned values. The usage of these variables requires customizing the CARMA startup REXX referenced by startup.script.name in CRASRV.properties.
system symbol Any system symbol defined in SYS1.PARMLIB(IEASYMxx)
-<DD> A dash (-) followed by a previously defined DD name acts like a *.ddname backward reference in JCL. The original DD must be allocated using the -COMMAND statement.
Note:
There is no variable for the TSO prefix, because TSO is not active when the configuration file is interpreted.

(Optional) Alternative CARMA server startup using TSO/ISPF Client Gateway

The information in this section describes how to configure an alternative method for Developer for System z to start a CARMA server. This customization step can be bypassed if you use another startup method.

Developer for System z supports an alternative CARMA server startup method that does not require the CRASTART module to be in LPA and that does not submit a server job using a JES initiator. The method uses ISPF's TSO/ISPF Client Gateway and is similar to the default way of accessing the TSO Commands service.

Note:
Details of the CARMA startup process are shown in rsecomm.log. Refer to (Optional) RSE tracing for more information on setting the detail level of rsecomm.log.

Adjust CRASRV.properties

RSE server uses the settings in /etc/rdz/CRASRV.properties to start and connect to a CARMA server, as documented in RSE interface to CARMA. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect.

Change the value of the clist.dsname directive to *ISPF, as shown in the following example:

Figure 15. CRASRV.properties - *ISPF alternative CARMA startup
port.start=5227
port.range=100
startup.script.name=/usr/lpp/rdz/bin/carma.startup.rex
clist.dsname=*ISPF

Adjust ISPF.conf

Keep a printout of the customized CRASUBMT (see CARMA server startup using batch submit ) handy for easy reference during this customization step. The printout will be valuable even if you have not customized the member.

ISPF's TSO/ISPF Client Gateway uses the definitions in ISPF.conf to create a valid environment to execute batch TSO and ISPF commands. Developer for System z uses this environment to run the CARMA server.

ISPF.conf is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

Note:
Changes are in effect for all CARMA servers started after the update.

The following customization steps are needed to adjust the configuration file shown in the code sample below.

Note:
Do not include the SYSTSIN, SYSTSOUT, or CARMALOG DDs, nor any other DD statement that uses JES constructs such as instream data and SYSOUT=. These entries must be converted to use data sets.
Figure 16. ISPF.conf - *ISPF alternative CARMA startup
sysproc=ISP.SISPCLIB,FEK.SFEKPROC
ispllib=FEK.SFEKLOAD
ispmlib=ISP.SISPMENU
isptlib=ISP.SISPTENU
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB
CRADEF =FEK.#CUST.CRADEF
CRAMSG =FEK.#CUST.CRAMSG
CRASTRS=FEK.#CUST.CRASTRS
*CRARAM1=FEK.#CUST.CRARAM1
allocjob=FEK.#CUST.CNTL(CRAISPRX)

DD CARMALOG refers to SYSOUT=* by default, which cannot be mapped in ISPF.conf. You cannot map the DD directly to a data set either, since all Developer for System z users will be using the same ISPF.conf file and thus the same data sets.

However, as described in Customizing the TSO environment, section Advanced - Using an allocation exec, you can use an allocation exec to create and allocate a data set based upon the active user ID. See sample member CRAISPRX in data set FEK.#CUST.CNTL as an example that allocates DD CARMALOG to data set name TSOPREFIX'.'USERID'.CRA.'TIMESTAMP'.CARMALOG'.

Note:

(Optional) Activating the sample Repository Access Managers (RAMs)

Repository Access Managers (RAMs) are user-written APIs to interface with z/OS Software Configuration Managers (SCMs). Follow the instructions in the sections below for the sample RAMs you want to activate.

Note:
The sample RAMs are provided for the purpose of testing the configuration of your CARMA environment and as examples for developing your own RAMs. Do NOT use the provided sample RAMs in a production environment.

Refer to Rational Developer for System z Common Access Repository Manager Developer's Guide (SC23-7660) for more information on the sample RAMs and sample source code provided.

The sample members referenced below are located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Activating the PDS RAM

The PDS RAM gives a data set list similar to MVS Files -> My Data Sets in the Remote Systems view. The PDS RAM uses RAM ID 0 by default.

Note:
The PDS RAM expects that CARMA is started within ISPF (using ISPSTART).

  1. Customize and submit the FEK.#CUST.JCL(CRA#VPDS) JCL. Refer to the documentation within CRA#VPDS for customization instructions. CRA#VPDS creates and primes the PDS RAM message VSAM data set.
  2. Add the CRARAM1 DD statement to the selected CARMA startup method and provide the data set name of the PDS RAM message VSAM.

Activating the SCLM RAM

The SCLM RAM gives a basic entry into SCLM, ISPF's Software Configuration Manager. The SCLM RAM uses RAM ID 1 by default.

Note:
The SCLM RAM expects that CARMA is started within ISPF (using ISPSTART).

  1. Customize and submit the FEK.#CUST.JCL(CRA#VSLM) JCL. Refer to the documentation within CRA#VSLM for customization instructions. CRA#VSLM creates and primes the SCLM RAM message VSAM data set.
  2. Add the CRARAM2 DD statement to the selected CARMA startup method and provide the data set name of the SCLM RAM message VSAM.
  3. Customize the FEK.#CUST.JCL(CRA#ASLM) JCL. Refer to the documentation within CRA#ASLM for customization instructions. CRA#ASLM allocates data sets needed by SCLM RAM clients.
    Note:
    Each user must submit FEK.#CUST.JCL(CRA#ASLM) once before using CARMA with the SCLM RAM. Failing to do so will result in an allocation error.

Activating the skeleton RAM

The skeleton RAM gives a skeleton framework that can be used to develop your own RAMs. The skeleton RAM uses RAM ID 3 by default.

  1. Customize and submit the FEK.#CUST.JCL(CRA#CRAM) JCL. Refer to the documentation within CRA#CRAM for customization instructions. CRA#CRAM compiles the skeleton RAM.
  2. Add the load library holding the compiled skeleton RAM module, CRARAMSA, to the STEPLIB DD of the selected CARMA startup method (TASKLIB DD for the CRASTART method).

(Optional) Activating the CA Endevor® RAM

The IBM® Rational® Developer for System z Interface for CA Endevor® SCM gives Developer for System z clients direct access to CA Endevor®. From here on, IBM® Rational® Developer for System z Interface for CA Endevor® SCM is abbreviated to CA Endevor® RAM (Repository Access Manager).

In contradiction with the sample RAMs documented in this publication, CA Endevor® RAM is a production type RAM. You should not activate both types of RAM in the same setup.

Attention: The provided setup jobs for CA Endevor® RAM replace the active CARMA setup with one that holds only the CA Endevor® RAM.

Note:
The TSO/ISPF Client Gateway startup method can not be used together with the CA Endevor® RAM.

Define the CA Endevor® RAM

The following CARMA components must be customized, regardless of the chosen startup method. The sample members referenced below are located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

  1. Customize and submit the FEK.#CUST.JCL(CRA#VCAD) JCL. Refer to the documentation within CRA$VDEF for customization instructions. CRA#VCAD creates and primes the CARMA configuration VSAM data set, CRADEF.
  2. Customize and submit the FEK.#CUST.JCL(CRA$VMSG) JCL. Refer to the documentation within CRA$VMSG for customization instructions. CRA$VMSG creates and primes the CARMA message VSAM data set, CRAMSG.
    Note:
    This is the same job as for the sample RAMs.
  3. Customize and submit the FEK.#CUST.JCL(CRA#VCAS) JCL. Refer to the documentation within CRA$VSTR for customization instructions. CRA#VCAS creates and primes the CARMA custom information VSAM data set, CRASTRS.
Note:

Update the CARMA server startup - batch submit

Do not execute this step if you use the CRASTART method to start the CARMA server with the CA Endevor® RAM.

The following customizations to FEK.#CUST.CNTL(CRASUBMT) are specific to the CA Endevor® RAM and must be done on top of the customizations described in CARMA server startup using batch submit.

Update the CARMA server startup - CRASTART

Do not execute this step if you use the batch submit method to start the CARMA server with the CA Endevor® RAM.

The following customizations to /etc/rdz/crastart.conf are specific to the CA Endevor® RAM and must be done on top of the customizations described in (Optional) Alternative CARMA server startup using CRASTART.

(Optional) IRXJCL versus CRAXJCL

If the CARMA server is started using TSO (IKJEFTxx), you may experience problems if your RAMs call services which in turn call the IRXJCL REXX batch interface. The problem can occur when the processors called by the RAM previously ran either without TSO, or only in online TSO and dynamically allocates DD SYSTSIN or SYSTSPRT. A sample program, CRAXJCL, is provided to work around this problem.

Your processor might fail if it attempts to allocate SYSTSIN or SYSTSPRT (required for IRXJCL) because batch TSO (required for CARMA) already has those DD names allocated and open. The CRAXJCL replacement module attempts to allocate SYSTSIN and SYSTSPRT to DUMMY but ignores the errors which occur if the allocations fail.

This means that when your processors run in a CARMA environment started by TSO, the allocations to SYSTSIN and SYSTSPRT are the same as those used by CARMA. When the processors are run outside of TSO/CARMA, the SYSTSIN and SYSTSPRINT allocations will be created by CRAXJCL. Therefore, your processors must not rely on the contents of the data set allocated to SYSTSIN.

It is assumed that calls to IRXJCL use the PARM field to pass the REXX name and startup parameters, as documented in TSO/E REXX Reference (SA22-7790). This means that SYSTSIN can safely be used by CARMA. Any output sent to SYSTSPRT by IRXJCL will end up in CARMA's log.

Processors that call the CRAXJCL replacement module should not attempt to allocate DD SYSTSIN or SYSTSPRT before calling CRAXJCL.

Create CRAXJCL

The CRAXJCL replacement module is shipped in source format because you will need to customize it to specify the specific allocations you want to use for SYSTSPRT. SYSTSIN should usually be allocated to a dummy data set.

Sample assembler source code and a sample compile/bind job are shipped as FEK.#CUST.ASM(CRAXJCL) and FEK.#CUST.JCL(CRA#CIRX) respectively, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Customize the CRAXJCL assembler source code per your needs, using the documentation within the member. Afterwards, customize and submit the CRA#CIRX JCL to create the CRAXJCL load module. Refer to the documentation within CRA#CIRX for customization instructions.

(Optional) Application Deployment Manager

Developer for System z uses certain functions of Application Deployment Manager as a common deployment approach for various components. The customization steps listed in this chapter are required if your developers use any of the following functions:

Note:
Enterprise Service Tools (EST) encompasses multiple tools, such as the Service Flow Modeler (SFM) and XML Services for the Enterprise (XSE).

Customizing Application Deployment Manager adds the CICS Resource Definition (CRD) server, which runs as a CICS application on z/OS to support the following functions:

CICS administrators can find more information on the CRD server in CICSTS considerations.

Requirements and checklist

You will need assistance of a CICS administrator, a TCP/IP administrator and a security administrator to complete this customization task, which requires the following resources or special customization tasks:

In order to start using Application Deployment Manager at your site, you must perform the following tasks. Unless otherwise indicated, all tasks are mandatory.

  1. Create the CRD repository. For details, see CRD repository.
  2. Choose the CICS interface (RESTful or Web Service) to be used. (The interfaces can co-exist). For details see RESTful versus Web Service.
  3. If desired, do the RESTful specific customizations. For details see CRD server using the RESTful interface.
  4. If desired, do the Web Service specific customizations. For details see CRD server using the Web Service interface.
  5. Optionally create the manifest repository. For details, see (Optional) Manifest repository.

CRD repository

Customize and submit job ADNVCRD to allocate and initialize the CRD repository VSAM data set. Refer to the documentation within the member for customization instructions.

ADNVCRD is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

You should create a separate repository for each CICS primary connection region. Sharing the repository implies that all related CICS regions will use the same values stored in the repository.

Note:
Unless notified otherwise, your current CRD server repository (holding your customized values) can be reused across Developer for System z releases.

Users require READ access to the CRD repository, CICS administrators require UPDATE access.

CICS administrative utility

Developer for System z provides the administrative utility to let CICS administrators provide the default values for CICS resource definitions. These defaults can be read-only, or can be editable by the application developer.

The administrative utility is invoked by sample job ADNJSPAU. The usage of this utility requires UPDATE access to the CRD repository.

ADNJSPAU is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

More information is available in CICSTS considerations.

RESTful versus Web Service

CICS Transaction Server provides in version 4.1 and higher support for an HTTP interface designed using Representational State Transfer (RESTful) principles. This RESTful interface is now the strategic CICSTS interface for use by client applications. The older Web Service interface has been stabilized, and enhancements will be for the RESTful interface only.

Application Deployment Manager follows this statement of direction and requires the RESTful CRD server for all services that are new to Developer for System version 7.6 or higher.

The RESTful and Web Service interfaces can be active concurrently in a single CICS region, if desired. In this case, there will be two CRD servers active in the region. Both servers will share the same CRD repository. Note that CICS will issue some warnings about duplicate definitions when the second interface is defined to the region.

CRD server using the RESTful interface

The information in this section describes how to define the CRD server that uses the RESTful interface to communicate with the Developer for System z client.

The RESTful and Web Service interfaces can be active concurrently in a single CICS region, if desired. In this case, there will be two CRD servers active in the region. Both servers will share the same CRD repository. Note that CICS will issue some warnings about duplicate definitions when the second interface is defined to the region.

CICS primary connection region

The CRD server must be defined to the primary connection region. This is the Web Owning Region (WOR) that will process Web Service requests from Developer for System z.

CICS non-primary connection regions

The CRD server can also be used with one or more additional non-primary connection regions, which are usually Application Owning Regions (AOR).

Note:
It is not necessary to perform these steps if CICSPlex® SM Business Application Services (BAS) is used to manage your CICS resource definitions.

(Optional) Customize CRD server transaction IDs

Developer for System z supplies multiple transactions that are used by the CRD server when defining and inquiring CICS resources.

Table 11. Default CRD server transaction IDs
Transaction Description
ADMS For requests from the Manifest Processing tool to change CICS resources. Typically, this is intended for CICS administrators.
ADMI For requests that define, install, or uninstall CICS resources.
ADMR For all other requests that retrieve CICS environmental or resource information.

You can change the transaction IDs to match your site standards by following these steps:

  1. Customize and submit ADNTXNC to create load module ADNRCUST. Refer to the documentation within the member for customization instructions.
  2. Place the resulting ADNRCUST load module in the CICS RPL concatenation (DD statement DFHRPL) of the CICS regions where the CRD server is defined.
  3. Customize and submit ADNCSDTX to define ADNRCUST as program to the CICS regions where the CRD server is defined. Refer to the documentation within the member for customization instructions.

Note:
The RESTful CRD server will always try to load the ADNRCUST load module. So you can get a small performance benefit by creating and defining the ADNRCUST load module, even if you do not change the transaction IDs.

CRD server using the Web Service interface

The information in this section describes how to define the CRD server that uses the Web Service interface to communicate with the Developer for System z client.

The RESTful and Web Service interfaces can be active concurrently in a single CICS region, if desired. In this case, there will be two CRD servers active in the region. Both servers will share the same CRD repository. Note that CICS will issue some warnings about duplicate definitions when the second interface is defined to the region.

Pipeline message handler

The pipeline message handler (ADNTMSGH) is used for security by processing the user ID and password in the SOAP header. ADNTMSGH is referenced by the sample pipeline configuration file and must therefore be placed into the CICS RPL concatenation. Refer to CICSTS considerations to learn more about the pipeline message handler and the required security setup.

Developer for System z supplies multiple transactions that are used by the CRD server when defining and inquiring CICS resources. These transaction IDs are set by ADNTMSGH, depending on the requested operation. Sample COBOL source code is provided to allow site-specific customizations to ADNTMSGH:

Table 12. Default CRD server transaction IDs
Transaction Description
ADMS For requests from the Manifest Processing tool to change CICS resources. Typically, this is intended for CICS administrators.
ADMI For requests that define, install or uninstall CICS resources.
ADMR For all other requests that retrieve CICS environmental or resource information.

Using the default:

Customizing ADNTMSGH:

Sample members ADNMSGH* are located in FEK.#CUST.JCL and FEK.#CUST.COBOL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Note:
Ensure that the customized ADNTMSGH load module is located before any reference to FEK.SFEKLOAD, otherwise the default one will be used.

CICS primary connection region

The CRD server must be defined to the primary connection region. This is the region that will process service requests from Developer for System z.

CICS non-primary connection regions

The CRD server can also be used with one or more additional non-primary connection regions, which are usually Application Owning Regions (AOR).

Note:
It is not necessary to perform these steps if CICSPlex SM Business Application Services (BAS) is used to manage your CICS resource definitions.

(Optional) Manifest repository

Developer for System z allows clients to browse and optionally change manifests describing selected CICS resources. Depending on permissions set by the CICS administrator, changes can be done directly or exported to the manifest repository for further processing by a CICS administrator.

Note:

Customize and submit job ADNVMFST to allocate and initialize the manifest repository VSAM data set, and to define it to the CICS primary connection region. Refer to the documentation within the member for customization instructions. A separate manifest repository must be created for each CICS primary connection region. All users need UPDATE access to the manifest repository.

ADNVMFST is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

(Optional) SCLM Developer Toolkit

SCLM Developer Toolkit provides the tools needed to extend the capabilities of SCLM to the client. SCLM itself is a host-based source code manager that is shipped as part of ISPF.

The SCLM Developer Toolkit has an Eclipse-based plugin that interfaces to SCLM and provides for access to all SCLM processes for legacy code development as well as support for full Java and J2EE development on the workstation with synchronization to SCLM on the mainframe including building, assembling, and deployment of the J2EE code from the mainframe.

Requirements and checklist

You will need assistance of an SCLM administrator and optionally a security administrator to complete this customization task, which requires the following resources and/or special customization tasks:

In order to start using SCLM Developer Toolkit at your site, you must perform the following tasks. Unless otherwise indicated, all tasks are mandatory.

  1. Verify and adjust prerequisites and PARMLIB updates. For details, see Prerequisites.
  2. Customize Developer for System z configuration files. For details see:
  3. Optionally define long/short name translation support. For details, see (Optional) Long/short name translation.
  4. Optionally install and customize Ant to use the JAVA/J2EE build support. For details, see (Optional) Install and customize Ant.
  5. Update SCLM to define SCLMDT-specific parts. For details, see SCLM updates for SCLMDT.
  6. Optionally set up automation to periodically clean up the SCLMDT work area. For details, see Remove old files from WORKAREA.

Prerequisites

Refer to Appendix E. Requisites for a list of required SCLM maintenance.

This appendix also documents the Ant specifications needed for JAVA/J2EE builds in SCLM Developer Toolkit.

Attention: SCLM Developer Toolkit requires the usage of ISPF's TSO/ISPF Client Gateway, which implies that z/OS 1.8 or higher is required.

As described in PARMLIB changes, SCLM Developer Toolkit requires additional customization of system settings. These changes include:

Also, SCLM Developer Toolkit uses SDSF or the TSO OUTPUT command to retrieve job completion status and job output. Both methods require some additional attention:

Users require READ, WRITE, and EXECUTE permission to the z/OS UNIX directories /tmp/ and /var/rdz/WORKAREA/. Directory WORKAREA/ is located in /var/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

ISPF.conf updates for SCLMDT

SCLM Developer Toolkit uses the standard ISPF/SCLM skeletons, so ensure that skeleton library ISP.SISPSLIB is allocated to the ISPSLIB concatenation in ISPF.conf. The usage of the ISP.SISPSENU data set is optional.

ISPF.conf is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

Note:
Changes are in effect for all clients connecting to the host after the update.

The following sample code shows the ISPF.conf file, which must be customized to match your system environment. Comment lines start with an asterisk (*). Add data sets to the concatenation on the same line and separate the names with a comma (,). See ISPF.conf, ISPF's TSO/ISPF Client Gateway configuration file for more details on customizing ISPF.conf.

Figure 17. ISPF.conf updates for SCLMDT
* REQUIRED:
sysproc=ISP.SISPCLIB,FEK.SFEKPROC
ispmlib=ISP.SISPMENU
isptlib=ISP.SISPTENU
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB

* OPTIONAL:
*allocjob = FEK.#CUST.CNTL(CRAISPRX)
*ISPF_timeout = 900
Notes:
  1. You can add your own DD-like statements and data set concatenations to customize the TSO environment, thus mimicking a TSO logon procedure. See Customizing the TSO environment for more details.
  2. When you are doing batch builds, ensure that the customized version of the FLMLIBS skeleton is concatenated before the ISPF/SCLM skeleton library.
    ispslib=hlq.USERSKEL,ISP.SISPSLIB

rsed.envvars updates for SCLMDT

SCLM Developer Toolkit uses some directives set in rsed.envvars to locate data sets and directories.

rsed.envvars is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

Note:
The RSED started task must be restarted to pick up any changes you make.

The following code sample shows the SCLMDT directives in rsed.envvars, which must be customized to match your system environment. See rsed.envvars, RSE configuration file for more details on customizing rsed.envvars.

Figure 18. rsed.envvars updates for SCLMDT
_SCLMDT_CONF_HOME=/var/rdz/sclmdt
#STEPLIB=$STEPLIB:FEK.SFEKAUTH:FEK.SFEKLOAD
#_SCLMDT_TRANTABLE=FEK.#CUST.LSTRANS.FILE
#ANT_HOME=/usr/lpp/Apache/Ant/apache-ant-1.7.1
_SCLMDT_BASE_HOME=$RSE_HOME
_SCLMDT_WORK_HOME=$_CMDSERV_WORK_HOME 
CGI_DTWORK=$_SCLMDT_WORK_HOME

(Optional) Long/short name translation

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.

Notes:
  1. For versions previous to z/OS 1.8, this facility is provided through a base ISPF/SCLM PTF that addresses APAR OA11426.
  2. The long/short name translation is also used by other SCLM-related products, such as IBM SCLM Administrator Toolkit.

Create LSTRANS.FILE, the long/short name translation VSAM

Customize and submit sample member FLM02LST in the ISPF sample library ISP.SISPSAMP, to create the long/short name translation VSAM. The configuration steps in this publication expect the VSAM to be named FEK.#CUST.LSTRANS.FILE, as shown in the following sample setup JCL.

Figure 19. FLM02LST - long/short name translation setup JCL
//FLM02LST JOB <job parameters>
//*
//* CAUTION: This is neither a JCL procedure nor a complete job.
//* Before using this sample, you will have to make the following
//* modifications:
//* 1. Change the job parameters to meet your system requirements.
//* 2. Change ****** to the volume that will hold the VSAM.
//* 3. Change all references of FEK.#CUST.LSTRANS.FILE to 
//*    match your naming convention for the SCLM translate VSAM.
//*
//CREATE   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE FEK.#CUST.LSTRANS.FILE
  SET MAXCC=0
  DEFINE CLUSTER(NAME(FEK.#CUST.LSTRANS.FILE) -
                 VOLUMES(******) -
                 RECORDSIZE(58 2048) -
                 SHAREOPTIONS(3 3) -
                 CYLINDERS(1 1) -
                 KEYS(8 0) -
                 INDEXED) -
         DATA   (NAME(FEK.#CUST.LSTRANS.FILE.DATA)) -
         INDEX  (NAME(FEK.#CUST.LSTRANS.FILE.INDEX))

  /* DEFINE ALTERNATE INDEX WITH NONUNIQUE KEYS -> ESDS */

  DEFINE ALTERNATEINDEX(-
                 NAME(FEK.#CUST.LSTRANS.FILE.AIX) -
                 RELATE(FEK.#CUST.LSTRANS.FILE) -
                 RECORDSIZE(58 2048) -
                 VOLUMES(******) -
                 CYLINDERS(1 1) -
                 KEYS(50 8) -
                 UPGRADE -
                 NONUNIQUEKEY) -
         DATA   (NAME(FEK.#CUST.LSTRANS.FILE.AIX.DATA)) -
         INDEX  (NAME(FEK.#CUST.LSTRANS.FILE.AIX.INDEX))
/*
//*
//PRIME    EXEC PGM=IDCAMS,COND=(0,LT)
//SYSPRINT DD SYSOUT=*
//INITREC  DD *
INITREC1
/*
//SYSIN    DD *
  REPRO INFILE(INITREC) -
        OUTDATASET(FEK.#CUST.LSTRANS.FILE)
  IF LASTCC = 4 THEN SET MAXCC=0

  BLDINDEX IDS(FEK.#CUST.LSTRANS.FILE) -
           ODS(FEK.#CUST.LSTRANS.FILE.AIX)

  IF LASTCC = 0 THEN -
    DEFINE PATH (NAME(FEK.#CUST.LSTRANS.FILE.PATH) -
           PATHENTRY (FEK.#CUST.LSTRANS.FILE.AIX))
/*
Note:
Users need UPDATE authority to this VSAM data set, as described in Security considerations.

rsed.envvars updates for long/short name translation

Before using the long/short name translation, uncomment and set the rsed.envvars environment variable _SCLMDT_TRANTABLE to match the name of the long/short name translation VSAM.

rsed.envvars is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

Note:
The RSED started task must be restarted to pick up any changes you make.

(Optional) Install and customize Ant

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

Apache Ant is an open source Java build tool and can be downloaded from http://ant.apache.org/. Ant consists of text files and scripts which are distributed in ASCII format and thus require an ASCII/EBCDIC translation to run in z/OS UNIX.

Perform the following steps to implement Ant on z/OS, and to define it to Developer for System z:

For example:

To test that the Ant initialization has been successful:

Note:
Setting the PATH statement in this way is necessary for testing only, not for operational use.

SCLM updates for SCLMDT

SCLM itself also requires customization to work with SCLM Developer Toolkit. Refer to IBM Rational Developer for System z SCLM Developer Toolkit Administrator's Guide (SC23-9801) for more information on the required customization tasks:

To complete the customization and project definition tasks, the SCLM administrator needs to know several Developer for System z customizable values, as described in Table 13.

Table 13. SCLM administrator checklist
Description

Default value

Where to find the answer Value
Developer for System z sample library

FEK.SFEKSAMV

SMP/E installation
Developer for System z sample directory

/usr/lpp/rdz/samples

SMP/E installation
Java bin directory

/usr/lpp/java/J5.0/bin

rsed.envvars - $JAVA_HOME/bin
Ant bin directory

/usr/lpp/Apache/Ant/apache-ant-1.7.1/bin

rsed.envvars - $ANT_HOME/bin
WORKAREA home directory

/var/rdz

rsed.envvars - $_CMDSERV_CONF_HOME
SCLMDT project configuration home directory

/var/rdz/sclmdt

rsed.envvars - $_SCLMDT_CONF_HOME
Long/short name translation VSAM

FEK.#CUST.LSTRANS.FILE

rsed.envvars - $_SCLMDT_TRANTABLE

Remove old files from WORKAREA

SCLM Developer Toolkit and ISPF's TSO/ISPF Client Gateway share the same WORKAREA, which might need a periodical cleanup. Refer to (Optional) WORKAREA cleanup for more information on this.

(Optional) Other customization tasks

This section combines a variety of optional customization tasks. Follow the instructions in the appropriate section to configure the desired service.

(Optional) DB2 stored procedure

You will need the assistance of a WLM administrator and a DB2 administrator to complete this customization task, which requires the following resources or special customization tasks:

  • WLM update
  • New PROCLIB member
  • DB2 update

Developer for System z provides a sample DB2 stored procedure (PL/I and COBOL Stored Procedure Builder) for building COBOL and PL/I Stored Procedures from within the Developer for System z client.

Note:
Sample members ELAXM* are located in FEK.#CUST.JCL and FEK.#CUST.PROCLIB, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Workload Manager (WLM) changes

Use the workload management (WLM) panels to associate an application environment with the JCL procedure of the WLM address space for the PL/I and COBOL Stored Procedure Builder. Refer to MVS Planning Workload Management (SA22-7602) for information on how to do this.

Note:
You can create a new application environment in WLM for the PL/I and COBOL Stored Procedure Builder, or you can add the necessary definitions to an existing one.

PROCLIB changes

Customize the sample Stored Procedure task FEK.#CUST.PROCLIB(ELAXMSAM), as described within the member, and copy it to SYS1.PROCLIB. As shown in the following code sample, you have to provide the following:

Figure 20. ELAXMSAM - DB2 stored procedure task
//ELAXMSAM PROC RGN=0M,
//            NUMTCB=1,
//            APPLENV=#wlmwd4z,
//            DB2SSN=#ssn,
//            DB2PRFX='DSN810',
//            COBPRFX='IGY.V3R4M0',
//            PLIPRFX='IBMZ.V3R6M0',
//            LIBPRFX='CEE',
//            LODPRFX='FEK'
//*
//DSNX9WLM EXEC PGM=DSNX9WLM,REGION=&RGN,TIME=NOLIMIT,DYNAMNBR=10,
//            PARM='&DB2SSN,&NUMTCB,&APPLENV'
//STEPLIB  DD DISP=SHR,DSN=&DB2PRFX..SDSNEXIT
//         DD DISP=SHR,DSN=&DB2PRFX..SDSNLOAD
//         DD DISP=SHR,DSN=&LIBPRFX..SCEERUN
//         DD DISP=SHR,DSN=&COBPRFX..SIGYCOMP
//         DD DISP=SHR,DSN=&PLIPRFX..SIBMZCMP
//SYSEXEC  DD DISP=SHR,DSN=&LODPRFX..SFEKPROC
//SYSTSPRT DD SYSOUT=*
//CEEDUMP  DD SYSOUT=*
//SYSABEND DD DUMMY
//SYSUT1   DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2   DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3   DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4   DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5   DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6   DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7   DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//*
Notes:
  1. The DB2 stored procedure uses REXX exec ELAXMREX, located in FEK.SFEKPROC. Do not change this location if you want possible SMP/E maintenance to be activated automatically.
  2. See Running multiple instances if you want to rename members ELAXMSAM or ELAXMREX.

DB2 changes

Customize and submit sample member ELAXMJCL in data set FEK.#CUST.JCL to define the Stored Procedure to DB2. Refer to the documentation within the member for customization instructions.

Figure 21. ELAXMJCL - DB2 stored procedure definition
//ELAXMJCL JOB <job parameters>
//JOBPROC  JCLLIB ORDER=(#hlq.SDSNPROC)
//JOBLIB   DD DISP=SHR,DSN=#hlq.SDSNEXIT
//         DD DISP=SHR,DSN=#hlq.SDSNLOAD
//*
//RUNTIAD  EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 DSN S(#ssn) R(1) T(1)
 RUN PROGRAM(DSNTIAD) PLAN(DSNTIAD) -
 LIB('#hlq.RUNLIB.LOAD')
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
 CREATE PROCEDURE SYSPROC.ELAXMREX
  ( IN  FUNCTION_REQUEST   VARCHAR(20)      CCSID EBCDIC
  , IN  SQL_ROUTINE_NAME   VARCHAR(27)      CCSID EBCDIC
  , IN  SQL_ROUTINE_SOURCE VARCHAR(32672)   CCSID EBCDIC
  , IN  BIND_OPTIONS       VARCHAR(1024)    CCSID EBCDIC
  , IN  COMPILE_OPTIONS    VARCHAR(255)     CCSID EBCDIC
  , IN  PRECOMPILE_OPTIONS VARCHAR(255)     CCSID EBCDIC
  , IN  PRELINK_OPTIONS    VARCHAR(32672)   CCSID EBCDIC
  , IN  LINK_OPTIONS       VARCHAR(255)     CCSID EBCDIC
  , IN  ALTER_STATEMENT    VARCHAR(32672)   CCSID EBCDIC
  , IN  SOURCE_DATASETNAME VARCHAR(80)      CCSID EBCDIC
  , IN  BUILDOWNER         VARCHAR(8)       CCSID EBCDIC
  , IN  BUILDUTILITY       VARCHAR(18)      CCSID EBCDIC
  , OUT RETURN_VALUE       VARCHAR(255)     CCSID EBCDIC )
 PARAMETER STYLE GENERAL  RESULT SETS 1
 LANGUAGE REXX            EXTERNAL NAME   ELAXMREX
 COLLID   DSNREXCS        WLM ENVIRONMENT ELAXMSAM
 PROGRAM TYPE MAIN        MODIFIES SQL DATA
 STAY RESIDENT NO         COMMIT ON RETURN NO
 ASUTIME NO LIMIT         SECURITY USER;

 COMMENT ON PROCEDURE SYSPROC.ELAXMREX IS
 'PLI & COBOL PROCEDURE PROCESSOR (ELAXMREX), INTERFACE LEVEL 0.01';

 GRANT EXECUTE ON PROCEDURE SYSPROC.ELAXMREX TO PUBLIC;
//*
Note:
Make sure the WLM ENVIRONMENT clause in the CREATE PROCEDURE statement specifies the name of the WLM environment procedure which has been defined for the PL/I and COBOL Stored Procedure Builder (default ELAXMSAM).

(Optional) Enterprise Service Tools (EST) support

This customization task does not require assistance, special resources, or special customization tasks.

The Developer for System z client has a code generation component called Enterprise Service Tools (EST). Depending on the type of code being generated, this code relies on functions provided by the Developer for System z host install. Making these host functions available is described in the following sections:

Note:
Enterprise Service Tools (EST) encompasses multiple tools, such as the Service Flow Modeler (SFM) and XML Services for the Enterprise (XSE).

(Optional) CICS bidirectional language support

You will need the assistance of a CICS administrator to complete this customization task, which requires the following resources or special customization tasks:

  • Update CICS region JCL
  • Define a program to CICS

The Developer for System z Enterprise Service Tools (EST) component supports different formats of Arabic and Hebrew interface messages, as well as bidirectional data presentation and editing in all editors and views. In terminal applications, both left-to-right and right-to-left screens are supported, as well as numeric fields and fields with opposite-to-screen orientation.

Additional bidirectional features and functionality include the following:

Additionally, EST-generated code can support bidi transformation in environments other than CICS SFR (Service Flow Runtime). One example is batch applications. You can make the EST generators to include calls to the bidirectional conversion routines by specifying the appropriate bidi transformation options in the EST generation wizards and linking the generated programs with the appropriate bidirectional conversion library, FEK.SFEKLOAD.

Perform the following tasks to activate CICS Bidirectional language support:

  1. Place the FEK.SFEKLOAD load modules FEJBDCMP and FEJBDTRX in the CICS RPL concatenation (DD statement DFHRPL). You should do this by adding the installation data set to the concatenation so that applied maintenance is automatically available to CICS.
    Note:
    If you do not concatenate the installation data set but copy the modules into a new or existing data set, keep in mind that those modules are DLLs and MUST reside in a PDSE library.
  2. Define FEJBDCMP and FEJBDTRX as programs to CICS using the appropriate CEDA command, for example:

    CEDA DEF PROG(FEJBDCMP) LANG(LE) G(xxx)
    CEDA DEF PROG(FEJBDTRX) LANG(LE) G(xxx)

(Optional) Diagnostic IRZ error messages

This customization task does not require assistance, but does require the following resources or special customization tasks:

  • LINKLIST update
  • Update CICS region JCL

The Developer for System z client has a code generation component called Enterprise Service Tools (EST). In order for code generated by EST to issue diagnostic error messages, all IRZ* and IIRZ* modules in the FEK.SFEKLOAD load library must be made available to the generated code. EST can generate code for the following environments:

When the generated code is executed in a CICS transaction, then add all IRZ* and IIRZ* modules in FEK.SFEKLOAD to the DFHRPL DD of the CICS region. You should do this by adding the installation data set to the concatenation so that applied maintenance is automatically available to CICS.

In all other situations, make all IRZ* and IIRZ* modules in FEK.SFEKLOAD available either through STEPLIB or LINKLIST. You should do this by adding the installation data set to the concatenation so that applied maintenance is automatically available to CICS.

If you decide to use STEPLIB, you must define the modules not available through LINKLIST in the STEPLIB directive of the task that executes the code.

If the load modules are not available and an error is encountered by the generated code, then following message will be issued:

IRZ9999S Failed to retrieve the text of a Language Environment runtime
message. Check that the Language Environment runtime message module for
facility IRZ is installed in DFHRPL or STEPLIB.

(Optional) RSE SSL encryption

You will need assistance of a security administrator to complete this customization task, which requires the following resources or special customization tasks:

  • LINKLIST update
  • Security rule to add program controlled data sets
  • (Optional) Security rule to add certificate for SSL

External (client-host) communication can be encrypted using SSL (Secure Socket Layer). This feature is disabled by default and is controlled by the settings in ssl.properties.

ssl.properties is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect.

The client communicates with RSE daemon during connection setup and with RSE server during the actual session. Both data streams are encrypted when SSL is enabled.

RSE daemon and RSE server support different mechanisms to store certificates due to architectural differences between the two. This implies that SSL definitions are required for both RSE daemon and RSE server. A shared certificate can be used if RSE daemon and RSE server use the same certificate management method.

Table 14. SSL certificate storage mechanisms
Certificate storage Created and managed by RSE daemon RSE server
key ring SAF-compliant security product supported supported
key database z/OS UNIX's gskkyman supported /
key store Java's keytool / supported
Note:

RSE daemon uses System SSL functions to manage SSL. This implies that SYS1.SIEALNKE must be program controlled by your security software and available to RSE via LINKLIST or the STEPLIB directive in rsed.envvars.

The following code sample shows the sample ssl.properties file, which must be customized to match your system environment. Comment lines start with a pound sign (#), when using a US code page. Data lines can only have a directive and its assigned value, comments are not allowed on the same line. Line continuations are not supported.

Figure 22. ssl.properties - SSL configuration file
# ssl.properties - SSL configuration file
enable_ssl=false

# Daemon Properties

#daemon_keydb_file=
#daemon_keydb_password=
#daemon_key_label=

# Server Properties

#server_keystore_file=
#server_keystore_password=
#server_keystore_label=
#server_keystore_type=JCERACFKS

The daemon and server properties only need to be set if you enable SSL. Refer to Appendix A. Setting up SSL and X.509 authentication for more information on SSL setup.

enable_ssl
Enable or disable SSL communication. The default is false. The only valid options are true and false.
daemon_keydb_file
RACF (or similar security product) key ring name. Provide the key database name if you used gskkyman to create a key database instead of using a key ring. Uncomment and customize this directive if SSL is enabled.
daemon_keydb_password
Leave commented out or blank if you use a key ring, otherwise provide the key database password. Uncomment and customize this directive if SSL is enabled and you are using a gskkyman key database.
daemon_key_label
The certificate label used in the key ring or key database, if it is not defined as the default one. Must be commented out if the default is used. Uncomment and customize this directive if SSL is enabled and you are not using the default security certificate.
server_keystore_file
Name of the key store created by Java's keytool command, or the RACF (or similar security product) key ring name if server_keystore_type=JCERACFKS. Uncomment and customize this directive if SSL is enabled.
server_keystore_password
Leave commented out or blank if you use a key ring, otherwise provide the key store password. Uncomment and customize this directive if SSL is enabled and you are using a keytool key store.
server_keystore_label
The certificate label used in the key ring or key store. The default is the first valid certificate encountered. Uncomment and customize this directive if SSL is enabled and you are not using the default security certificate.
server_keystore_type
Key store type. The default is JKS. Valid values are:
Table 15. Valid keystore types
Keyword Key store type
JKS Java key store
JCERACFKS SAF-compliant key ring, where the certificate's private key is stored in the security database.
JCECCARACFKS SAF-compliant key ring, where the certificate's private key is stored using ICSF, the interface to System z cryptographic hardware.
Note:
At the time of publication, IBM z/OS Java requires an update of the /usr/lpp/java/J5.0/lib/security/java.security file to support JCECCARACFKS. The following line must be added:
security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA

The resulting file will look like this:

security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
security.provider.2=com.ibm.jsse2.IBMJSSEProvider2
security.provider.3=com.ibm.crypto.provider.IBMJCE
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath
security.provider.6=com.ibm.security.sasl.IBMSASL 

(Optional) RSE tracing

This customization task does not require assistance, special resources, or special customization tasks.

Developer for System z supports different levels of tracing the internal program flow for problem solving purposes. RSE, and some of the services called by RSE, use the settings in rsecomm.properties to know the desired detail level in the output logs.

Attention: Changing these settings can cause performance degradations and should only be done under the direction of the IBM support center.

rsecomm.properties is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command.

The following code sample shows the rsecomm.properties file, which can be customized to match your tracing needs. Comment lines start with a pound sign (#), when using a US code page. Data lines can only have a directive and its assigned value, comments are not allowed on the same line. Line continuations are not supported.

Figure 23. rsecomm.properties - Logging configuration file
# server.version - DO NOT MODIFY!
server.version=5.0.0

# Logging level
# 0 - Log error messages
# 1 - Log error and warning messages
# 2 - Log error, warning and info messages
debug_level=1

# Log location
# Log_To_StdOut
# Log_To_File
log_location=Log_To_File
server.version
Logging server version. The default is 5.0.0. Do not modify.
debug_level
Detail level for output logs. The default is 1 (log error and warning messages). Note that debug_level controls the detail level of multiple services (and thus multiple output files). Increasing the detail level will cause performance degradations and should only be done under the direction of the IBM support center. Refer to RSE tracing for more information on which logs are controlled by this directive.

The valid values are the following:

0 Log error messages only.
1 Log error and warning messages.
2 Log error, warning, and informational messages.
Note:
debug_level can be changed dynamically with the modify rsecommlog operator command, as described in Operator commands.
log_location
Output medium for RSE related logging. The default is Log_To_File. Do not change when using the RSE daemon connection method (default), unless directed by the IBM support center.

The valid values are the following:

Log_To_File Send log messages to a separate file in the log output directory.
  • RSE daemon: rsedaemon.log in daemonlog
  • RSE thread pools: rseserver.log in daemonlog
  • User: rsecomm.log in userlog/.eclipse/RSE/$LOGNAME
Log_To_StdOut Send log messages to stdout.
  • RSE daemon: rerouted to DD STDOUT in the RSED started task
  • RSE thread pools: undefined
  • User: rerouted to stdout.log in userlog/.eclipse/RSE/$LOGNAME

daemonlog is the value of the daemon.log directive in rsed.envvars. If the daemon.log directive is commented out or not present, the home path of the user ID assigned to the RSED started task is used. The home path is defined in the OMVS security segment of the user ID.

User-specific logs go to userlog/.eclipse/RSE/$LOGNAME, where userlog is the value of the user.log directive in rsed.envvars, and $LOGNAME is the logon user ID (uppercase). If the user.log directive is commented out or not present, the home path of the user is used. The home path is defined in the OMVS security segment of the user ID.

(Optional) Host based property groups

This customization task does not require assistance, special resources, or special customization tasks.

Developer for System z clients can define property groups which hold default values for various properties (for example, the COBOL compiler options to use when compiling COBOL source code). Developer for System z has some default values built in, but also allows defining custom, system-specific defaults.

The location of the custom property group and default value configuration files is defined in propertiescfg.properties, which is located in/etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect.

The following code sample shows the propertiescfg.properties file, which must be customized to match your system environment. Comment lines start with a pound sign (#), when using a US code page. Data lines can only have a directive and its assigned value. Comments are not allowed on the same line. Line continuations are not supported.

Figure 24. propertiescfg.properties - Host-based property groups configuration file
#
# host based property groups - root configuration file
#
ENABLED=FALSE
RDZ-VERSION=7.5.0.0
PROPERTY-GROUP=/var/rdz/properties
DEFAULT-VALUES=/var/rdz/properties
ENABLED
Indicates whether Developer for System z will use the property group and default value configuration files. The default is FALSE. The only valid options are TRUE and FALSE.
RDZ-VERSION
Minimum Developer for System z client level to use host-based property groups. The default is 7.5.0.0. Do not modify.
PROPERTY-GROUP
The location of the property group configuration file. The default is /var/rdz/properties.
DEFAULT-VALUES
The location of the default value configuration file. The default is /var/rdz/properties.

Refer to the Developer for System z Information Center (http://publib.boulder.ibm.com/infocenter/ratdevz/v7r6/index.jsp) for more information on creating the property group configuration file (propertygroups.xml) and the default value configuration file (defaultvalues.xml).

(Optional) Host based projects

This customization task does not require assistance, special resources, or special customization tasks.

z/OS Projects can be defined individually through the z/OS Projects perspective on the client or can be defined centrally on the host and propagated to the client on a per user basis. These "host-based projects" look and function exactly like projects defined on the client except that their structure, members, and properties cannot be modified by the client and they are only accessible when connected to the host.

The location of the project definitions is defined in projectcfg.properties, which is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect.

The following code sample shows the projectcfg.properties file, which must be customized to match your system environment. Comment lines start with a pound sign (#), when using a US code page. Data lines can only have a directive and its assigned value. Comments are not allowed on the same line. Line continuations are not supported.

Figure 25. projectcfg.properties - Host-based projects configuration file
#
# host based projects - root configuration file
#
# WSED-VERSION - do not modify !
WSED-VERSION=7.0.0.0
# specify the location of the host based project definition files
PROJECT-HOME=/var/rdz/projects
WSED-VERSION
Minimum Developer for System z client level to use host-based projects. The default is 7.0.0.0. Do not modify.
PROJECT-HOME
The base directory for the project definitions. The default is /var/rdz/projects.

Note:
In order to activate host-based projects, a project.instance file must exist in /var/rdz/projects/USERID, where /var/rdz/projects is the location of the project definition files and USERID is the user ID (uppercase) with which the developer logs on.

Refer to Developer for System z Information Center (http://publib.boulder.ibm.com/infocenter/ratdevz/v7r6/index.jsp) for more information on host-based projects.

(Optional) File Manager integration

You will need the assistance of a security administrator to complete this customization task, which requires the following resources or special customization tasks:

  • Security rule to add program controlled data sets

Developer for System z supports direct access from the client to a limited set of IBM File Manager for z/OS functions. IBM File Manager for z/OS provides comprehensive tools for working with MVS data sets, z/OS UNIX files, DB2, IMS and CICS data. These tools include the familiar browse, edit, copy, and print utilities found in ISPF, enhanced to meet the needs of application developers. In the current version of Developer for System z, only browse and edit of MVS data sets (including all types of VSAM), creating and editing MVS data set templates (including dynamic templates), and advanced copy utilities are supported.

Note that the IBM File Manager for z/OS product must be ordered, installed and configured separately. Refer to Rational Developer for System z Prerequisites (SC23-7659) to know which level of File Manger is required for your version of Developer for System z. The installation and customization of this product is not described in this manual.

Note that both Developer for System z and File Manger no longer support the batch interface to access File Manager services. Usage of the File Manager listener is now required.

Note:
In addition to the normal listener setup tasks described in your File Manager documentation, Developer for System z requires that the server's STEPLIB data sets are program controlled.

The File Manager Integration definitions needed by Developer for System z are stored in FMIEXT.properties, which is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup more details. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect.

The following code sample shows the FMIEXT.properties file, which must be customized to match your system environment. Comment lines start with a pound sign (#), when using a US code page. Data lines can only have a directive and its assigned value. Comments are not allowed on the same line. Line continuations are not supported.

Figure 26. FMIEXT.properties - File Manager configuration file
# File Manager Integration (FMI) Extension properties
#
enabled=false    
fmlistenport=1960

enabled
Indicates whether the File Manager listener is available on the same host system or not. The default value is false. The only values allowed are true and false.
fmlistenport
Port used by the File Manager listener. The default is 1960. Communication on this port is confined to your host machine.

(Optional) Uneditable characters

This customization task does not require assistance, special resources, or special customization tasks.

Some characters do not translate well between host code pages (EBCDIC based) and client code pages (ASCII based). The Developer for System z client editor uses the definitions in uchars.settings file to identify these uneditable characters.

uchars.settings is located in /etc/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details. You can edit the file with the TSO OEDIT command. Note that RSE must be restarted for the changes to take effect. Also note that it is advised not to change this file, unless directed by IBM support center.

Figure 27. uchars.settings - Uneditable characters configuration file
# uchars.settings - uneditable code points
#
# By default everything below x'40' is uneditable
*          *          00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
                      10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
                      20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
                      30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F;
# SBCS
IBM-037    Cp1252     0D 15 25;
IBM-037    UTF-8      0D 15 25;
IBM-424    Cp1255     0D 15 25;
IBM-424    UTF-8      0D 15 25;
# DBCS
IBM-939    MS932      0D 15 1E 1F 25;

The file consists of multiple entries in the following format:

HOST-CODEPAGE  LOCAL-CODEPAGE  HEX-CODEPOINTS ;

Where HEX-CODEPOINTS is a blank-delimited list of 2-digit hexadecimal code points which identify the uneditable characters. The list must end with a semicolon (;).

The following syntax rules apply:

(Optional) Using REXEC (or SSH)

This customization task does not require assistance, special resources, or special customization tasks.

REXEC (Remote Execution) is a TCP/IP service to let clients execute a command on the host. SSH (Secure Shell) is a similar service, but here all communication is encrypted using SSL (Secure Socket Layer). Developer for System z uses either service for doing remote (host-based) actions in z/OS UNIX subprojects.

Developer for System z can also be configured to use REXEC (or SSH) to start an RSE server on the host. Note, however, that each connection started this way will result in a separate RSE server, each using a fair amount of system resources. Therefore, this alternate connection method is only viable for a small number of connections.

Also, since the REXEC (or SSH) alternative connection method bypasses the RSE daemon, it does not have access to all host services described in this publication, such as single server processing and audit. Contact IBM support to learn if a specific host service is supported by the REXEC alternate connection method.

Note:
Developer for System z uses the z/OS UNIX version of REXEC, not the TSO version.

Remote (host-based) actions for z/OS UNIX subprojects

Remote (host-based) actions for z/OS UNIX subprojects require that REXEC or SSH is active on the host. If REXEC/SSH is not configured to use the default port, the Developer for System z client must define the correct port for use by z/OS UNIX subprojects. This can be done by selecting the Window > Preferences... > z/OS Solutions > USS Subprojects > Remote Action Options preference page. Refer to REXEC (or SSH) set up to know which port is used.

Alternate RSE connection method

Developer for System z clients need to know two values to start an RSE connection through REXEC (or SSH), as follows:

REXEC (or SSH) set up

Communications Server IP Configuration Guide (SC31-8775) describes the steps required to set up REXEC (or SSH). Refer to Appendix C. Setting up INETD for Developer for System z specific setup considerations (there are no Developer for System z specific setup steps).

A common port used by REXEC is 512. To verify this, you can check /etc/inetd.conf and /etc/services to find the port number used.

The same principle applies to SSH. Its common port is 22, and the server name is sshd.

Note:
/etc/inetd.conf and /etc/services can have different names. Refer to Appendix C. Setting up INETD for more information.

(Optional) APPC transaction for the TSO Commands service

You will need assistance of an APPC administrator and a WLM administrator to complete this customization task, which requires the following resources or special customization tasks:

  • LINKLIST update
  • APPC transaction
  • WLM update

The TSO Commands service can be implemented as an APPC transaction program, FEKFRSRV. This transaction acts as a host server to execute TSO and ISPF commands that are issued from the workstation. APPC is not required on the workstation because the client communicates with FEKFRSRV through RSE. Each client can have an active connection to multiple hosts at the same time.

Notes:
  1. By default, Developer for System z uses ISPF's TSO/ISPF Client Gateway to access the TSO Commands service.
  2. If you are unfamiliar with APPC, refer toAppendix D. Setting up APPC before continuing with this section.
  3. RSE uses the TCP/IP REXX socket API to communicate with FEKFRSRV. This implies that the TCP/IP load library, default TCPIP.SEZALOAD, must be available either via LINKLIST or the STEPLIB directive in rsed.envvars.
  4. RSE must be restarted for the described changes to take effect.

Preparation

Refer to MVS Planning Workload Management (SA22-7602) for more information on WLM/SRM management. Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on OMVS segments and data set protection profiles.

Implementation

Note:
Sample members FEKAPPC* are located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

  1. Define the scheduling information (class) for the APPC transaction scheduler if you are not using an existing transaction class. Include a definition in SYS1.PARMLIB(ASCHPMxx) for the class to be used by the transaction program FEKFRSRV. This class is used in sample JCL FEK.#CUST.JCL(FEKAPPCC). Therefore the class in FEKAPPCC must match the class defined in SYS1.PARMLIB(ASCHPMxx). For example:
    CLASSADD
      CLASSNAME(A)
      MAX(20)
      MIN(1)
      MSGLIMIT(200)
     
    Notes:
    1. The TSO Commands service needs the default specifications to be specified in the OPTIONS and TPDEFAULT sections of SYS1.PARMLIB(ASCHPMxx). Refer to Appendix D. Setting up APPC for more information.
    2. The APPC transaction class used must have enough APPC initiators to allow one initiator for each concurrent user of Developer for System z.
  2. Define the APPC transaction that will act as a command server. You can use the sample JCL FEK.#CUST.JCL(FEKAPPCC) to define this transaction. Instructions on how to customize this JCL are located within the JCL.
    Notes:
    1. If you changed the transaction program name (default FEKFRSRV) in this step, the new name must be assigned to _FEKFSCMD_TP_NAME_ in rsed.envvars, as described in rsed.envvars, RSE configuration file.
    2. The APPC transaction uses the REXX exec FEKFRSRV, located in FEK.SFEKPROC. Do not change this location if you want possible SMP/E maintenance to be activated automatically.
    3. Sample JCL is also provided to display, FEK.#CUST.JCL(FEKAPPCL), or delete, FEK.#CUST.JCL(FEKAPPCX), the transaction.
  3. Enable RSE to use APPC by uncommenting the RSE_JAVAOPTS="$_RSE_JAVAOPTS -DTSO_SERVER=APPC" directive in rsed.envvars, as described in rsed.envvars, RSE configuration file.
  4. Control the dispatching priority of the transaction program by associating FEKFRSRV with a domain and performance group in Workload Manager (WLM). Because FEKFRSRV issues TSO commands, it should be assigned to a TSO performance group.
  5. Define a default OMVS segment for the system or an individual one for each user of Developer for System z.
  6. Give Developer for System z users READ access to FEK.SFEKPROC, the Developer for System z TSO executable library.

APPC usage considerations

(Optional) WORKAREA cleanup

This customization task does not require assistance, special resources, or special customization tasks.

ISPF's TSO/ISPF Client Gateway and the SCLM Developer Toolkit function use the WORKAREA directory to store temporary work files, which are removed before the session is closed. However, temporary output is sometimes left behind, for example, if there is a communication error while processing. For this reason, it is recommended that you clear out the WORKAREA directory from time to time.

z/OS UNIX provides a shell script, skulker, that deletes files based upon the directory they are in and their age. Combined with the z/OS UNIX cron daemon, which runs commands at specified dates and times, you can set up an automated tool that periodically cleans out the WORKAREA directory. Refer to UNIX System Services Command Reference (SA22-7802) for more information on the skulker script and the cron daemon.

Note:
WORKAREA is located in /var/rdz/, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Installation verification

Verify started tasks

JMON, JES Job Monitor

Start the JMON started task (or user job). The startup information in DD STDOUT should end with the following message:

JM200I Server initialization complete.

If the job ends with return code 66, then FEK.SFEKAUTH is not APF authorized.

Note:
Start JES Job Monitor before continuing with the other IVP tests.

LOCKD, Lock daemon

Start the LOCKD started task (or user job). The lock daemon issues the following console message upon successful startup:

FEK501I Lock daemon started, port=4036, cleanup interval=1440,
 log level=1

RSED, RSE daemon

Start the RSED started task (or user job) with the IVP=IVP parameter. With this parameter, the server will end after doing some installation verification tests. The output of these tests is available in DD STDOUT. In case of certain errors, data will also be available in DD STDERR. The STDOUT data should look like the following sample:

Note:
Start the RSE daemon, without the IVP parameter, before continuing with the other IVP tests. RSE daemon issues the following console message upon successful startup:
FEK002I RseDaemon started. (port=4035)
RSE daemon IVP test

Wed Jul 2 17:11:52 2008 UTC
uid=8(STCRSE) gid=1(STCGROUP)

RSE daemon port is 4035
RSE configuration files located in /etc/rdz

-------------------------------------------------------------
current environment variables
-------------------------------------------------------------
@="/usr/lpp/rdz/bin/rsed.sh" @[1]="4035" @[2]="/etc/rdz"
CGI_DTCONF="/var/rdz/sclmdt"
CGI_DTWORK="/var/rdz"
CGI_TRANTABLE="FEK.#CUST.LSTRANS.FILE"
CLASSPATH=".:/usr/lpp/rdz/lib:/usr/lpp/rdz/lib/dstore_core.jar:/usr/lpp/
ERRNO="0"
HOME="/tmp"
IFS="
"
JAVA_HOME="/usr/lpp/java/J5.0"
JAVA_PROPAGATE="NO"
LANG="C"
LIBPATH=".:/usr/lib:/usr/lpp/java/J5.0/bin:/usr/lpp/java/J5.0/bin/classi
LINENO="66"
LOGNAME="STCRSE"
MAILCHECK="600"
OLDPWD="/tmp"
OPTIND="1"
PATH=".:/usr/lpp/java/J5.0/bin:/usr/lpp/rdz/bin:/usr/lpp/ispf/bin:/bin:/
PPID="33554711"
PS1="\$ "
PS2="> "
PS3="#? "
PS4="+ "
PWD="/etc/rdz"
RANDOM="27298"
RSE_CFG="/etc/rdz"
RSE_HOME="/usr/lpp/rdz"
RSE_LIB="/usr/lpp/rdz/lib"
SECONDS="0"
SHELL="/bin/sh"
STEPLIB="NONE"
TZ="EST5EDT"
_BPX_SHAREAS="YES"
_BPX_SPAWN_SCRIPT="YES"
_CEE_DMPTARG="/tmp"
_CEE_RUNOPTS="ALL31(ON) HEAP(32M,32K,ANYWHERE,KEEP,,) TRAP(ON)"
_CMDSERV_BASE_HOME="/usr/lpp/ispf"
_CMDSERV_CONF_HOME="/etc/rdz"
_CMDSERV_WORK_HOME="/var/rdz"
_RSE_CMDSERV_OPTS="&SESSION=SPAWN"
_RSE_DAEMON_CLASS="com.ibm.etools.zos.server.RseDaemon"
_RSE_DAEMON_IVP_TEST="1"
_RSE_DAEMON_PORT="4035"
_RSE_JAVAOPTS=" -DISPF_OPTS='&SESSION=SPAWN' -DA_PLUGIN_PATH=/usr/lpp/rd
_RSE_POOL_SERVER_CLASS="com.ibm.etools.zos.server.ThreadPoolProcess"
_RSE_PWD="/tmp"
_RSE_SERVER_CLASS="org.eclipse.dstore.core.server.Server"
_RSE_SERVER_TIMEOUT="120000"
_SCLMDT_BASE_HOME="/usr/lpp/rdz"
_SCLMDT_CONF_HOME="/var/rdz/sclmdt"
_SCLMDT_TRANTABLE="FEK.#CUST.LSTRANS.FILE"
_SCLMDT_WORK_HOME="/var/rdz"
_SCLM_BASE="/var/rdz/WORKAREA"
_SCLM_BWBCALL="/usr/lpp/rdz/bin/BWBCALL"
_SCLM_DWGET="/var/rdz/WORKAREA"
_SCLM_DWTRANSFER="/var/rdz/WORKAREA"
_SCLM_J2EEPUT="/var/rdz/WORKAREA"

-------------------------------------------------------------
java startup test...
-------------------------------------------------------------
java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build pmz31dev-2008031
IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 z/OS s390-31 j9vmmz3123-2008
J9VM - 20080314_17962_bHdSMr
JIT  - 20080130_0718ifx2_r8
GC   - 200802_08)
JCL  - 20080314

-------------------------------------------------------------
TCP/IP IVP test...
-------------------------------------------------------------

Wed Jul  2 13:11:54 EDT 2008
uid=8(STCRSE) gid=1(STCGROUP)
using /etc/rdz/rsed.envvars

-------------------------------------------------------------
TCP/IP resolver configuration (z/OS UNIX search order):
-------------------------------------------------------------
Resolver Trace Initialization Complete -> 2008/07/02 13:11:54.745964

res_init Resolver values:
 Global Tcp/Ip Dataset  = None
 Default Tcp/Ip Dataset = None
 Local Tcp/Ip Dataset   = /etc/resolv.conf
 Translation Table      = Default
 UserId/JobName         = STCRSE
 Caller API             = LE C Sockets
 Caller Mode            = EBCDIC
 (L) DataSetPrefix = TCPIP
 (L) HostName      = CDFMVS08
 (L) TcpIpJobName  = TCPIP
 (L) DomainOrigin  = RALEIGH.IBM.COM
 (L) NameServer    = 9.42.206.2
                     9.42.206.3
 (L) NsPortAddr    = 53            (L) ResolverTimeout    = 10
 (L) ResolveVia    = UDP           (L) ResolverUdpRetries = 1
 (*) Options NDots = 1
 (*) SockNoTestStor
 (*) AlwaysWto     = NO            (L) MessageCase        = MIXED
 (*) LookUp        = DNS LOCAL
res_init Succeeded
res_init Started: 2008/07/02 13:11:54.755363
res_init Ended: 2008/07/02 13:11:54.755371
************************************************************************
MVS TCP/IP NETSTAT CS V1R9       TCPIP Name: TCPIP           13:11:54
Tcpip started at 01:28:36 on 06/23/2008 with IPv6 enabled

-------------------------------------------------------------
host IP address:
-------------------------------------------------------------
hostName=CDFMVS08
hostAddr=9.42.112.75
bindAddr=9.42.112.75
localAddr=9.42.112.75

Success, addresses match

-------------------------------------------------------------
PassTicket IVP test...
-------------------------------------------------------------

Success, PassTicket IVP finished normally

-------------------------------------------------------------RSE daemon IVP ended

Verify services

The Developer for System z installation provides several Installation Verification Programs (IVP) for the basic and optional services. The IVP scripts are located in the installation directory, default /usr/lpp/rdz/bin/.

Table 17. IVPs for services
fekfivpa (Optional) TSO Commands service connection using APPC
fekfivpd RSE daemon connection
fekfivpi ISPF's TSO/ISPF Client Gateway connection
fekfivpj JES Job Monitor connection
fekfivpl Lock daemon connection
fekfivpr (Optional) REXEC connection
fekfivps (Optional) SCLMDT connection
fekfivpt TCP/IP setup
fekfivpz (Optional) REXEC/SSH shell script

The tasks described below expect you to be active in z/OS UNIX. This can be done by issuing the TSO command OMVS. Use the exit command to return to TSO.

A large region size is required for the user ID that executes the IVPs, because functions such as Java, which require a lot of memory, will be executed. You should set the region size to 131072 kilobytes (128 megabytes) or higher.

The following sample error is a clear indication of an insufficient region size. (But other errors can occur, too. For example, Java may fail to start.)

CEE5213S The signal SIGPIPE was received.
%z/OS UNIX command%: command was killed by signal number 13
    %line-number% *-*   %REXX command%
       +++ RC(137) +++ 

Note:
The Developer for System z started tasks must be active before starting the IVP test.

IVP initialization

All sample commands in this section expect that certain environment variables are set. This way, the IVP scripts are available through the PATH statement and the location of the customized configuration files is known. Use the pwd and cd commands to verify and change your current directory to the directory with the customized configuration files. The ivpinit shell script can then be used to set the RSE environment variables, such as in the following sample ($ is the z/OS UNIX prompt):

$ pwd
/u/userid
$ cd /etc/rdz
$ . ./ivpinit
RSE configuration files located in /etc/rdz --default
added /usr/lpp/rdz/bin to PATH

The first "." (dot) in . ./ivpinit is a z/OS UNIX command to run the shell in the current environment, so that the environment variables set in the shell are effective even after exiting the shell. The second one is referring to the current directory.

Note:

For information on diagnosing RSE connection problems, see Troubleshooting configuration problems or the Technotes on the Developer for System z Support Page http://www-306.ibm.com/software/awdtools/rdz/support/.

Port availability

The JES Job Monitor, RSE daemon, and optionally REXEC or SSH port availability can be verified by issuing the netstat command. The result should show the ports used by these services, as in the following samples ($ is the z/OS UNIX prompt):

IPv4

$ netstat
MVS TCP/IP NETSTAT CS VxRy    TCPIP Name: TCPIP       13:57:36
User Id  Conn     Local Socket      Foreign Socket    State
-------  ----     ------------      --------------    -----
INETD4   00000014 0.0.0.0..22       0.0.0.0..0        Listen
INETD4   00000030 0.0.0.0..512      0.0.0.0..0        Listen
RSED     0000004B 0.0.0.0..4035     0.0.0.0..0        Listen
LOCKD    0000004C 0.0.0.0..4036     0.0.0.0..0        Listen
JMON     00000037 0.0.0.0..6715     0.0.0.0..0        Listen

IPv6

$ netstat
MVS TCP/IP NETSTAT CS VxRy    TCPIP Name: TCPIP       14:03:35
User Id  Conn     State
-------  ----     -----
INETD4   00000018 Listen
  Local Socket:   0.0.0.0..22
  Foreign Socket: 0.0.0.0..0
INETD4   00000046 Listen
  Local Socket:   0.0.0.0..512
  Foreign Socket: 0.0.0.0..0
RSED     0000004B Listen
  Local Socket:   0.0.0.0..4035
  Foreign Socket: 0.0.0.0..0
LOCKD    0000004C Listen
  Local Socket:   0.0.0.0..4036
  Foreign Socket: 0.0.0.0..0
JMON     00000037 Listen
  Local Socket:   0.0.0.0..6715
  Foreign Socket: 0.0.0.0..0

TCP/IP setup

When using APPC for the TSO Commands service, Developer for System z is dependent upon TCP/IP having the correct hostname when it is initialized. This implies that the different TCP/IP and Resolver configuration files must be set up correctly. Refer to Appendix B. Setting up TCP/IP for more information on TCP/IP and Resolver setup. Verify the current settings by executing the following command:

fekfivpt
Note:
This IVP issues the TCPIP netstat command, which might be protected against execution by your security software.

The command should return an output like that in this sample ($ is the z/OS UNIX prompt):

$ fekfivpt

Wed Jul  2 13:11:54 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars

current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

-------------------------------------------------------------
TCP/IP resolver configuration (z/OS UNIX search order):
-------------------------------------------------------------
Resolver Trace Initialization Complete -> 2008/07/02 13:11:54.745964

res_init Resolver values:
 Global Tcp/Ip Dataset  = None
 Default Tcp/Ip Dataset = None
 Local Tcp/Ip Dataset   = /etc/resolv.conf
 Translation Table      = Default
 UserId/JobName         = USERID
 Caller API             = LE C Sockets
 Caller Mode            = EBCDIC
 (L) DataSetPrefix = TCPIP
 (L) HostName      = CDFMVS08
 (L) TcpIpJobName  = TCPIP
 (L) DomainOrigin  = RALEIGH.IBM.COM
 (L) NameServer    = 9.42.206.2
                     9.42.206.3
 (L) NsPortAddr    = 53            (L) ResolverTimeout    = 10
 (L) ResolveVia    = UDP           (L) ResolverUdpRetries = 1
 (*) Options NDots = 1
 (*) SockNoTestStor
 (*) AlwaysWto     = NO            (L) MessageCase        = MIXED
 (*) LookUp        = DNS LOCAL
res_init Succeeded
res_init Started: 2008/07/02 13:11:54.755363
res_init Ended: 2008/07/02 13:11:54.755371
************************************************************************
MVS TCP/IP NETSTAT CS V1R9       TCPIP Name: TCPIP           13:11:54
Tcpip started at 01:28:36 on 06/23/2008 with IPv6 enabled

-------------------------------------------------------------
host IP address:
-------------------------------------------------------------
hostName=CDFMVS08
hostAddr=9.42.112.75
bindAddr=9.42.112.75
localAddr=9.42.112.75

Success, addresses match

RSE daemon connection

Verify the RSE daemon connection by executing the following command. Replace 4035 with the port used by the RSE daemon and USERID by a valid user ID.

fekfivpd 4035 USERID

After prompting you for a password, the command should return an output like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivpd 4035 USERID

Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars

current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

Password:
SSL is disabled
connected
8108
570655399
Success
Note:
When testing an SSL enabled connection, verify that you specified the correct port if you get this error message: gsk_secure_socket_init() failed: Socket closed by remote partner.

JES Job Monitor connection

Verify the JES Job Monitor connection by executing the following command. Replace 6715 with the JES Job Monitor port number.

fekfivpj 6715

The command should return the JES Job Monitor acknowledge message, like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivpj 6715

Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars

current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

hostName=CDFMVS08
hostAddr=9.42.112.75
Waiting for JES Job Monitor response...
ACKNOWLEDGE01v03

Success

Lock daemon connection

Verify the lock daemon connection by executing the following command.

fekfivpl

The command should return an output like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivpl

Mon Jun 29 08:00:38 EDT 2009
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars

current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

hostName=CDFMVS08
hostAddr=9.42.112.75

Registering user to Lock Daemon...
Waiting for Lock Daemon response...

Querying to Lock Daemon...
Waiting for Lock Daemon response...
USERID


Unregistering user from Lock Daemon...
Waiting for Lock Daemon response...

Querying to Lock Daemon...
Waiting for Lock Daemon response...


Success

ISPF's TSO/ISPF Client Gateway connection

Verify the connection to ISPF's TSO/ISPF client Gateway by executing the following command:

fekfivpi

The command should return the result of ISPF's TSO/ISPF client Gateway-related checks (variables, HFS modules, starting and stopping TSO/ISPF session), like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivpi
 
Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars
 
current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

-------------------------------------------------------------
/etc/rdz/ISPF.conf content:
-------------------------------------------------------------
 
ispmlib=ISP.SISPMENU 
isptlib=ISP.SISPTENU 
ispplib=ISP.SISPPENU 
ispslib=ISP.SISPSLIB 
sysproc=ISP.SISPCLIB,FEK.SFEKPROC 
 
-------------------------------------------------------------
Host install verification for RSE
Review IVP log messages from HOST below :
-------------------------------------------------------------

RSE connection and base TSO/ISPF session initialization check only

*** CHECK : ENVIRONMENT VARIABLES - key variables displayed below :

Server PATH         = 
/usr/lpp/java/J5.0/bin:/usr/lpp/rdz/lib:/usr/lpp/ispf/bin:
/bin:/usr/sbin:.

STEPLIB             = FEK.SFEKAUTH:FEK.SFEKLOAD

_CMDSERV_BASE_HOME  = /usr/lpp/ispf
_CMDSERV_CONF_HOME  = /etc/rdz
_CMDSERV_WORK_HOME  = /var/rdz
-------------------------------------------------------------
*** CHECK : USS MODULES
Checking ISPF Directory : /usr/lpp/ispf
Checking modules in /usr/lpp/ispf/bin directory
Checking for ISPF configuration file ISPF.conf
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
*** CHECK : TSO/ISPF INITIALIZATION
( TSO/ISPF session will be initialized )
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
*** CHECK: Shutting down TSO/ISPF IVP session
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
Host installation verification completed successfully
-------------------------------------------------------------
Note:
If any of the ISPF checks fail, more detailed information will be shown.

fekfivpi has the following optional, non-positional, parameters:

-file
fekfivpi can produce large amounts of output (hundreds of lines). The -file parameter sends this output to a file, userlog/.eclipse/RSE/$LOGNAME/fekfivpi.log, where userlog is the value of the user.log directive in rsed.envvars, and $LOGNAME is your user ID (uppercase). If the user.log directive is commented out or not present, your home path is used. The home path is defined in your OMVS security segment.
-debug
The -debug parameter creates detailed test output. Do not use this option unless directed by the IBM support center.

(Optional) TSO Commands service connection using APPC

Verify the connection to the TSO Command server (using APPC) by executing the following command. Replace USERID with a valid user ID:

fekfivpa USERID

After prompting you for a password, the command should return the APPC conversation, like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivpa USERID
Enter password:
 
Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars
 
current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

20070607 13:57:18.584060 /usr/lpp/rdz/bin/fekfscmd: version=Oct 2003
20070607 13:57:18.584326 Input parms: 1.2.3.4 * NOTRACE USERID ********
20070607 13:57:18.586800 APPC: Allocate succeeded
20070607 13:57:18.587022  Conversation id is 0DDBD3F80000000D
20070607 13:57:18.587380 APPC: Set Send Type succeeded
20070607 13:57:26.736674 APPC: Confirm succeeded
20070607 13:57:26.737027  Req to send recd value is  0
20070607 13:57:26.737546 APPC: SEND_DATA return_code = 0
20070607 13:57:26.737726  request_to_send_received =  0
20070607 13:57:26.737893  Send Data succeeded
20070607 13:57:26.738169 APPC: Set Prepare to Receive type succeeded
20070607 13:57:26.738580 APPC: Prepare to Receive succeeded
20070607 13:57:26.808899 APPC: Receive data
20070607 13:57:26.809122  RCV return_code = 0
20070607 13:57:26.809270  RCV data_received= 2
20070607 13:57:26.809415  RCV received_length= 29
20070607 13:57:26.809556  RCV status_received= 4
20070607 13:57:26.809712  RCV req_to_send= 0
20070607 13:57:26.809868  Receive succeeded
:IP: 0 9.42.112.75 1674 50246
20070607 13:57:26.810533 APPC: CONFIRMED succeeded

(Optional) SCLMDT connection

Verify the connection to SCLM Developer Toolkit by executing the following command:

fekfivps

The command should return the result of SCLM Developer Toolkit related checks (variables, HFS modules, REXX runtime, starting and stopping TSO/ISPF session), like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivps

Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars
 
current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

-------------------------------------------------------------
/etc/rdz/ISPF.conf content:
-------------------------------------------------------------
 
ispmlib=ISP.SISPMENU 
isptlib=ISP.SISPTENU 
ispplib=ISP.SISPPENU 
ispslib=ISP.SISPSLIB 
sysproc=ISP.SISPCLIB,FEK.SFEKPROC 
-------------------------------------------------------------
Host install verification for RSE
Review IVP log messages from HOST below :
-------------------------------------------------------------


*** CHECK : ENVIRONMENT VARIABLES - key variables displayed below :

Server PATH         = /usr/lpp/java/J5.0/bin:/usr/lpp/rdz/lib:/usr/lpp/ispf/bin:
/bin:/usr/sbin:.

STEPLIB             = FEK.SFEKAUTH:FEK.SFEKLOAD

_CMDSERV_BASE_HOME  = /usr/lpp/ispf
_CMDSERV_CONF_HOME  = /etc/rdz
_CMDSERV_WORK_HOME  = /var/rdz
_SCLMDT_CONF_HOME  = /var/rdz/sclmdt
_SCLMDT_WORK_HOME  = /var/rdz
_SCLMDT_TRANTABLE  = FEK.#CUST.LSTRANS.FILE 

-------------------------------------------------------------
*** CHECK : JAVA PATH SETUP VERIFICATION
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
*** CHECK : USS MODULES
Checking ISPF Directory : /usr/lpp/ispf
Checking modules in /usr/lpp/ispf/bin directory
Checking for ISPF configuration file ISPF.conf
Checking install bin Directory : /usr/lpp/rdz/bin
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
*** CHECK : REXX RUNTIME ENVIRONMENT
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
*** CHECK : TSO/ISPF INITIALIZATION
( TSO/ISPF session will be initialized )
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
*** CHECK: Shutting down TSO/ISPF IVP session
RC=0
MSG: SUCCESSFUL

-------------------------------------------------------------
Host installation verification completed successfully
-------------------------------------------------------------
Note:
If any of the SCLMDT checks fail, more detailed information will be shown.

fekfivps has the following optional, non-positional, parameters:

-file
fekfivps can produce large amounts of output (hundreds of lines). The -file parameter sends this output to a file, userlog/.eclipse/RSE/$LOGNAME/fekfivps.log, where userlog is the value of the user.log directive in rsed.envvars, and $LOGNAME is your user ID (uppercase). If the user.log directive is commented out or not present, your home path is used. The home path is defined in your OMVS security segment.
-debug
The -debug parameter creates detailed test output. Do not use this option unless directed by the IBM support center.

(Optional) REXEC connection

Verify the REXEC connection by executing the following command. Replace 512 with the port used by REXEC and USERID by a valid user ID.

fekfivpr 512 USERID

After prompting you for a password, the command should return the REXEC trace, a timeout warning, the Java version, and the RSE server message, like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivpr 512 USERID
Enter password:
 
Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars
 
current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

$ EZYRC01I  Calling function rexec_af with the following:
EZYRC02I  Host: CDFMVS08, user USERID, cmd cd /etc/rdz;export RSE_USER_ID=USERI
D;./server.zseries -ivp, port 512
EZYRC19I  Data socket = 4, Control socket = 6.

RSE server IVP test

CDFMVS08 -- Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)

RSE configuration files located in /etc/rdz --default
 
RSE userid is USERID --default

-------------------------------------------------------------
Address Space size limits
-------------------------------------------------------------
current address space size limit is 2147483647 (2048.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

-------------------------------------------------------------
service history
-------------------------------------------------------------
Fri Jun 19 00:01:00 2009 -- COPY -- HHOP760 v7600 created 18 Jun 2009

-------------------------------------------------------------
expect to see time out messages after a successful IVP test

-------------------------------------------------------------
starting RSE server in background -- Fri Jun 19 15:59:05 EDT 2009
-------------------------------------------------------------
java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build pmz31dev-20070201 (SR4))
IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 z/OS s390-31 j9vmmz3123-20070201 (JI
T enabled)
J9VM - 20070131_11312_bHdSMr
JIT  - 20070109_1805ifx1_r8
GC   - 200701_09)
JCL  - 20070126

DStore Server Starting... 
Server Started Successfully
8108
Server running on: CDFMVS08

Notes:
  1. If you do not get any Java and RSE server output, the INETD region size is probably too small (must be 2096128 or larger if started from a TSO/OMVS shell session, or region size 0 for BPXBATCH).
  2. You can test the shell script used by REXEC separately, as described in the next IVP test, (Optional) REXEC/SSH shell script.
  3. The server is started without a client trying to connect, so it will time out (after 5 seconds). This results in a Connection error message that looks like the following sample:
    Connection error
    Server: error initializing socket: java.net.SocketTimeoutException: 
    			Accept timed out

(Optional) REXEC/SSH shell script

This IVP test can be skipped if the previous test outlined in, (Optional) REXEC connection, completed successfully.

Verify the shell script used by the REXEC and SSH connection by executing the following command:

fekfivpz

The command should return a timeout warning, the Java version and the RSE server message, like that in the following sample ($ is the z/OS UNIX prompt):

$ fekfivpz

Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)

using /etc/rdz/rsed.envvars

current address space size limit is 1914675200 (1826.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

-------------------------------------------------------------

RSE server IVP test

CDFMVS08 -- Wed Jul  2 15:00:27 EDT 2008
uid=1(USERID) gid=0(GROUP)

RSE configuration files located in /etc/rdz --default
RSE userid is USERID --default

-------------------------------------------------------------
Address Space size limits
-------------------------------------------------------------
current address space size limit is 2147483647 (2048.0 MB)
maximum address space size limit is 2147483647 (2048.0 MB)

-------------------------------------------------------------
service history
-------------------------------------------------------------
Fri Jun 19 00:01:00 2009 -- COPY -- HHOP760 v7600 created 18 Jun 2009

-------------------------------------------------------------
expect to see time out messages after a successful IVP test

-------------------------------------------------------------
starting RSE server in background -- Fri Jun 19 15:59:05 EDT 2009
-------------------------------------------------------------
java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build pmz31dev-20070201 (SR4))
IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 z/OS s390-31 j9vmmz3123-20070201 (JI
T enabled)
J9VM - 20070131_11312_bHdSMr
JIT  - 20070109_1805ifx1_r8
GC   - 200701_09)
JCL  - 20070126

DStore Server Starting... 
Server Started Successfully
8108
Server running on: CDFMVS08
Notes:
  1. If you do not get any output, your (TSO) region size is probably too small (must be 2096128).
  2. The server is started without a client trying to connect, so it will time out (after 5 seconds). This results in a Connection error message that looks like the following sample:
    Connection error
    Server: error initializing socket: java.net.SocketTimeoutException: 
            Accept timed out

Developer for System z information

Operator commands

This appendix provides an overview of the available operator (or console) commands for Developer for System z. Refer to How to read a syntax diagram if you are unfamiliar with the syntax diagrams used to explain the command format.

Start (S)

Use the START command to dynamically start a started task (STC). The abbreviated version of the command is the letter S.

JES Job Monitor

Figure 29. START JMON operator command
JES Job Monitor
procname
The name of the member in a procedure library that is used to start the server. The default name used during the host configuration is JMON.
HLQ=install_hlq
High-level qualifier used to install Developer for System z. The default is FEK.
CFG=config_member
Absolute data set and member name of the JES Job Monitor configuration file. The default is FEK.#CUST.PARMLIB(FEJJCNFG).
PRM=-TV
Enable verbose (trace) mode. Tracing will cause performance degradations and should only be done under the direction of the IBM support center.

RSE daemon

Figure 30. START RSED operator command
RSE daemon
procname
The name of the member in a procedure library that is used to start the server. The default name used during the host configuration is RSED.
PORT=port
The port used by the RSE daemon for the clients to connect. The default is 4035.
HOME='install_path'
Path prefix and the mandatory /usr/lpp/rdz used to install Developer for System z. The default is '/usr/lpp/rdz'. Note that the z/OS UNIX path is case sensitive and that it must be enclosed in single quotes (') to preserve lower case characters.
CNFG='config_path'
Absolute location of the configuration files stored in z/OS UNIX. The default is '/etc/rdz'. Note that the z/OS UNIX path is case sensitive and that it must be enclosed in single quotes (') to preserve lower case characters.
IVP=IVP
Do not start the server but run the RSE daemon installation verification program (IVP).

Lock daemon

Figure 31. START LOCKD operator command
Lock daemon
procname
The name of the member in a procedure library that is used to start the server. The default name used during the host configuration is LOCKD.
HOME='install_path'
Path prefix and the mandatory /usr/lpp/rdz used to install Developer for System z. The default is '/usr/lpp/rdz'. Note that the z/OS UNIX path is case sensitive and that it must be enclosed in single quotes (') to preserve lower case characters.
CNFG='config_path'
Absolute location of the configuration files stored in z/OS UNIX. The default is '/etc/rdz'. Note that the z/OS UNIX path is case sensitive and that it must be enclosed in single quotes (') to preserve lower case characters.
LOG=log_level
The detail level of output in DD STDOUT.

Modify (F)

The MODIFY command allows you to dynamically query and change the characteristics of an active task. The abbreviated version of the command is the letter F.

JES Job Monitor

Figure 32. MODIFY JMON operator command
JES Job Monitor
procname
The name of the member in a procedure library that was used to start the server. The default name used during the host configuration is JMON.
-TV
Enable verbose (trace) mode. Tracing will cause performance degradations and should only be done under the direction of the IBM support center.
-TN
Disable verbose (trace) mode.

RSE daemon

Figure 33. MODIFY RSED operator command
RSE daemon
procname
The name of the member in a procedure library that was used to start the server. The default name used during the host configuration is RSED.
DISPLAY CLIENT
Display the active clients.
<clientid> : <userid> : <connected since>
DISPLAY PROCESS[,CLEANUP]
Display the RSE thread pool processes. There can be multiple processes, which are used for load balancing the connected users.
ProcessId(<processid>) Memory Usage(<java heap usage>%)
                        Clients(<number of clients>) <error status>
Note:
  • <processid> can be used in process specific z/OS UNIX operator commands.
  • Each process has its own Java heap, whose size can be set in rsed.envvars.

In normal situations, <error status> is blank. Table 18___ documents the possible non-blank values for <error status>.

Table 18. Thread pool error status
Status Description
*severe error* The thread pool process encountered an unrecoverable error and halted operations. The other status fields show the last known values. Use the CLEANUP option of the DISPLAY PROCESS modify command to remove this entry from the table.
*killed process* The thread pool process was killed by Java, z/OS UNIX or an operator command. The other status fields show the last known values. Use the CLEANUP option of the DISPLAY PROCESS modify command to remove this entry from the table.
*timeout* The thread pool process did not respond in a timely manner to RSE daemon during a client connect request. The other status fields show the current values. The thread pool is excluded for future client connect requests. The *timeout* status is reset when a client served by this thread pool logs off.
CANCEL ID=clientid
Cancel a client connection based upon the client ID, which is shown in the DISPLAY CLIENT modify command.
CANCEL USER=userid
Cancel a client connection based upon the client's user ID, which is shown in the DISPLAY CLIENT modify command.
RSECOMMLOG {ON,OFF,I,W,E,2,1,0}
Control the trace detail level for RSE server (rsecomm.log) and the MVS data set services (lock.log and ffs*.log). The startup default is defined in rsecomm.properties. There are three detail levels available:
E or 0 or OFF Error messages only.
W or 1 Error and Warning messages. This is the default setting in rsecomm.properties.
I or 2 or ON Error, Warning and Informational messages.

Detailed tracing will cause performance degradations and should only be done under the direction of the IBM support center.

RSEDAEMONLOG {ON,OFF,I,E,2,0}
Control the trace detail level for RSE daemon (rsedaemon.log). The startup default is defined in rsecomm.properties. There are two detail levels available:
E or 0 or OFF Error messages only.
I or 2 or ON Error, Warning, and Informational messages.

Detailed tracing will cause performance degradations and should only be done under the direction of the IBM support center.

RSESERVERLOG {ON,OFF,I,E,2,0}
Control the trace detail level for RSE thread pools (rseserver.log). The startup default is defined in rsecomm.properties. There are two detail levels available:
E or 0 or OFF Error messages only.
I or 2 or ON Error, Warning, and Informational messages.

Detailed tracing will cause performance degradations and should only be done under the direction of the IBM support center.

RSESTANDARDLOG {ON,OFF}
Disable (OFF) or enable (ON) updating the log files holding the stdout and stderr streams of the thread pools (stdout.*.log and stderr.*.log). The startup default is defined by the enable.standard.log directive in rsed.envvars.

Detailed tracing will cause performance degradations and should only be done under the direction of the IBM support center.

SWITCH
Switch to a new audit log file.
Notes:
  1. Refer to Log files in Troubleshooting configuration problems for more information on the log files mentioned above.
  2. Refer to Audit logging in Security considerations for more information on audit.

Lock daemon

Figure 34. MODIFY LOCKD operator command
Lock daemon
procname
The name of the member in a procedure library that was used to start the server. The default name used during the host configuration is LOCKD.
QUERY dataset[(member)]
Query the lock status of the listed data set or member. The server will reply with one of the following messages:
BPXM023I (stclock) dataset[(member)] NOT LOCKED 
BPXM023I (stclock) dataset[(member)] LOCKED BY userid 
Notes:
  1. The server will also report locks held by other products, such as ISPF.
  2. Locks held by Developer for System z clients who were unable to register with the lock daemon will result in the thread pool server address space (RSEDx) being reported as lock owner.

    Console message FEK513W is generated when RSE server is unable to register the client with the lock daemon. The ASID and TCB values mentioned in this message can be compared against the output of the D GRS,RES=(*,dataset[(member)]) operator command in order to find the actual user holding the lock.

Stop (P)

Use the STOP command to stop an active task. The abbreviated version of the command is the letter P.

Figure 35. STOP operator command
procname
The name of the member in a procedure library that was used to start the server. The default names used during the host configuration are JMON, RSED, and LOCKD for JES Job Monitor, RSE daemon, and the lock daemon, respectively.

Console messages

JES Job Monitor

JES Job Monitor does not have product-specific console messages. The server relies on z/OS and JES to generate console messages for actions done by Developer for System z clients.

RSE daemon, RSE thread pool server, and lock daemon

Table 19 lists the product-specific console messages generated by RSE daemon, RSE thread pool server, and the lock daemon.

Table 19. RSE console messages
Message ID Message text
FEK001I RseDaemon being initialized
FEK002I RseDaemon started. (port={0})
FEK003I Stop command being processed
FEK004I RseDaemon: Max Heap Size={0}MB and private AS Size={1}MB
FEK005I Server process started. (processId={0})
FEK009I RseDaemon is waiting for the server process to start.
FEK010I (rsed.envvars location = {0})
FEK011I (log directory = {0})
FEK100E Daemon port/timeout value must be digits
FEK101E JRE {0} or higher required
FEK102E Invalid arguments received: {0}
FEK103E Almost Disk-Full in {0}
FEK104E Maximum number of processes has been reached
FEK105E Error in sending audit data (rc={0})
FEK110E socket() failed. reason=({0})
FEK111E setsockopt() failed. reason=({0})
FEK112E bind() failed. reason=({0})
FEK113E listen() failed. reason=({0})
FEK114E accept() failed. reason=({0})
FEK115E write() failed. reason=({0})
FEK116E pipe() failed. reason=({0})
FEK117E socketpair() failed. reason=({0})
FEK118E select() failed. reason=({0})
FEK119E _console() failed. reason=({0})
FEK130E gsk_environment_open() failed. reason=({0})
FEK131E gsk_attribute_set_enum(GSK_PROTOCOL_SSLV2) failed. reason=({0})
FEK132E gsk_attribute_set_enum(GSK_PROTOCOL_SSLV3) failed. reason=({0})
FEK133E gsk_attribute_set_enum(GSK_PROTOCOL_TLSV1) failed. reason=({0})
FEK134E gsk_attribute_set_buffer(GSK_KEYRING_FILE) failed. reason=({0})
FEK135E gsk_attribute_set_buffer(GSK_KEYRING_PW) failed. reason=({0})
FEK136E gsk_environment_init() failed. reason=({0})
FEK137E gsk_secure_socket_open() failed. reason=({0})
FEK138E gsk_attribute_set_numeric_value(GSK_FD) failed. reason=({0})
FEK139E gsk_attribute_set_buffer(GSK_KEYRING_LABEL) failed. reason=({0})
FEK140E gsk_attribute_set_enum(GSK_SESSION_TYPE) failed. reason=({0})
FEK141E gsk_attribute_set_callback(GSK_IO_CALLBACK) failed. reason=({0})
FEK142E gsk_secure_socket_init() failed. reason=({0})
FEK143E gsk_attribute_set_enum(GSK_CLIENT_AUTH_TYPE) failed. reason=({0})
FEK144E gsk_get_cert_info failed. reason=({0})
FEK145E gsk_secure_socket_read() failed. reason=({0})
FEK146E gsk_secure_socket_write() failed. reason=({0})
FEK150E RseDaemon abnormally terminated; {0}
FEK201I {0} Command has been processed
FEK202E Invalid Command Entered
FEK203E Invalid Display Command: Display Process|Client
FEK204E Invalid Cancel Command: Cancel ID=|User=
FEK205E Command was not processed owing to consecutive SWITCHs
FEK206E Audit Log facility is not active
FEK207I No Client to be displayed
FEK208I {0} canceled
FEK209I No Process to be displayed
FEK501I Lock daemon started, port={0}, cleanup interval={1}, log level={2}
FEK502I Lock daemon terminating
FEK510E Lock daemon, missing port
FEK511E Lock daemon, wrong port, port={0}
FEK512E Lock daemon, socket error, port={0}
FEK513W Lock daemon, registration failed, ASID={0}, TCB={1}, USER={2}
FEK514W Lock daemon, wrong log level, log level={0}
BPXM023I (stclock) dataset[(member)] NOT LOCKED
BPXM023I (stclock) dataset[(member)] LOCKED BY userid
BPXM023I (stclock) command, WRONG COMMAND
BPXM023I (stclock) command, MISSING ARGUMENT
BPXM023I (stclock) argument, WRONG ARGUMENT

How to read a syntax diagram

The syntax diagram shows you how to specify a command so that the operating system can correctly interpret what you type. Read the syntax diagram from left to right and from top to bottom, following the horizontal line (the main path).

Symbols

The following symbols are used in syntax diagrams:

Symbol Description
>> Marks the beginning of the syntax diagram.
> Indicates that the syntax diagram is continued.
| Marks the beginning and end of a fragment or part of the syntax diagram.
>< Marks the end of the syntax diagram.

Operands

The following types of operands are used in syntax diagrams:

Operands are classified as keywords or variables:

Syntax example

In the following example, the USER command is a keyword. The required variable parameter is user_id, and the optional variable parameter is password. Replace the variable parameters with your own values:

>>--USER--user_id-*----------*----------------------------------><
                  *-password-*

Nonalphanumeric characters and blank spaces

If a diagram shows a character that is not alphanumeric (such as parentheses, periods, commas, equal signs, and blank spaces), you must code the character as part of the syntax. In this example, you must code OPERAND=(001 0.001):

>>--OPERAND--=--(--001-- --0.001--)------------------------><

Selecting more than one operand

An arrow returning to the left in a group of operands means that more than one can be selected, or that a single one can be repeated:

>>--*----------------------*----------------------------><
    *-REPEATABLE_OPERAND_1-*
    *-REPEATABLE_OPERAND_2-*
    *-<--------------------*

Longer than one line

If a diagram is longer than one line, the first line ends with a single arrowhead and the second line begins with a single arrowhead:

>>--| The first line of a syntax diagram that is longer than one line |-->
>--| The continuation of the subcommands, parameters, or both |---------><

Syntax fragments

Some diagrams might contain syntax fragments, which serve to break up diagrams that are too long, too complex, or too repetitious. Syntax fragment names are in mixed case and are shown in the diagram and in the heading of the fragment. The fragment is placed below the main diagram:

 >>--| Syntax fragment |---------------------------------------><

Syntax fragment:
|--1ST_OPERAND--,--2ND_OPERAND--,--3RD_OPERAND--|

Troubleshooting configuration problems

This chapter is provided to assist you with some common problems that you may encounter during your configuration of Developer for System z, and has the following sections:

More information is available through the Support section of the Developer for System z Web site (http://www-306.ibm.com/software/awdtools/rdz/support/) where you can find Technotes that bring you the latest information from our support team.

In the Library section of the Web site (http://www-306.ibm.com/software/awdtools/rdz/library/) you can also find the latest version of the Developer for System z documentation, including whitepapers.

The Developer for System z Information Center (http://publib.boulder.ibm.com/infocenter/ratdevz/v7r6/index.jsp) documents the Developer for System z client, and how it interacts with the host (from a client's perspective).

Valuable information can also be found in the z/OS internet library, available at http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/.

Please notify us if you think that Developer for System z misses a certain function. You can open a Request For Enhancement (RFE) at

https://www.ibm.com/developerworks/support/rational/rfe/

Log and setup analysis using FEKLOGS

Developer for System z provides a sample job, FEKLOGS, which gathers all z/OS UNIX log files as well as Developer for System z installation and configuration information.

Sample job FEKLOGS is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

The customization of FEKLOGS is described within the JCL. The customization encompasses the provision of a few key variables.

Note:
SDSF customers can use the XDC line command in SDSF to save the job output in a data set, which in turn can be given to the IBM support center.

Log files

Developer for System z creates log files that can assist you and IBM support center in identifying and solving problems. The following list is an overview of log files that can be created on your z/OS host system. Next to these product-specific logs, be sure to check the SYSLOG for any related messages.

MVS based logs can be located through the appropriate DD statement. z/OS UNIX based log files are located in the following directories:

Note:
There are operator commands available to control the amount of data written to some of the mentioned log files. Refer to Operator commands for more information.

JES Job Monitor logging

Lock daemon logging

RSE daemon and thread pool logging

Notes:
  1. serverlogs.count, stderr.*.log, and stdout.*.log are only created if the enable.standard.log directive in rsed.envvars is active, or if the function is dynamically activated with the modify rsestandardlog on operator command.
  2. The * in stderr.*.log and stdout.*.log is 1 by default. However, there can be multiple RSE thread pools, in which case the number is incremented for each new RSE thread pool to ensure unique file names.
  3. There are no user-specific stdout.log and stderr.log log files when the enable.standard.log directive is active. The user-specific data is now written to the matching RSE thread pool stream.
  4. There are operator commands available to control the amount of data written to some of the mentioned log files. Refer to Operator commands for more information.

RSE user logging

Notes:
  1. The .eclipse directory and the .dstore* log files start with a dot (.), which makes them hidden. Use z/OS UNIX command ls -lA to list hidden files and directories. When using the Developer for System z client, select the Window > Preferences... > Remote Systems > Files preference page and enable "Show hidden files".
  2. The creation of the .dstore* log files is controlled by the -DDSTORE_* Java startup options, as described in Defining extra Java startup parameters with _RSE_JAVAOPTS.
  3. The .dstore* log files are created in ASCII. Use z/OS UNIX command iconv -f ISO8859-1 -t IBM-1047 .dstore* to display them in EBCDIC (when using code page IBM-1047).
  4. There are no user-specific stdout.log and stderr.log log files when the enable.standard.log directive is active. The user-specific data is now written to the matching RSE thread pool stream.
  5. There are operator commands available to control the amount of data written to some of the mentioned log files. Refer to Operator commands for more information.

Fault Analyzer Integration logging

File Manager Integration logging

SCLM Developer Toolkit logging

CARMA logging

APPC transaction (TSO Commands service) logging

fekfivpi IVP test logging

fekfivps IVP test logging

Dump files

When a product abnormally terminates, a storage dump is created to assist in problem determination. The availability and location of these dumps depends heavily on site-specific settings. So it could be that they are not created, or created in different locations than mentioned below.

MVS dumps

When the program is running in MVS, check the system dump files and check your JCL for the following DD statements (depending on the product):

Refer to MVS JCL Reference (SA22-7597) and Language Environment Debugging Guide (GA22-7560) for more information on these DD statements.

Java dumps

In z/OS UNIX, most Developer for System z dumps are controlled by the Java Virtual Machine (JVM).

The JVM creates a set of dump agents by default during its initialization (SYSTDUMP and JAVADUMP). You can override this set of dump agents using the JAVA_DUMP_OPTS environment variable and further override the set by the use of -Xdump on the command line. JVM command-line options are defined in the _RSE_JAVAOPTS directive of rsed.envvars. Do not change any of the dump settings unless directed by the IBM support center.

Note:
The -Xdump:what option on the command line can be used for determining which dump agents exist at the completion of startup.

The types of dump that can be produced are the following:

SYSTDUMP
Java Transaction dump. An unformatted storage dump generated by z/OS.

The dump is written to a sequential MVS data set, using a default name of the form %uid.JVM.TDUMP.%job.D%y%m%d.T%H%M%S, or as determined by the setting of the JAVA_DUMP_TDUMP_PATTERN environment variable. If you do not want transaction dumps to be created, add environment variable IBM_JAVA_ZOS_TDUMP=NO to rsed.envvars.

Note:
JAVA_DUMP_TDUMP_PATTERN allows the usage of variables, which are translated to an actual value at the time the transaction dump is taken.
Table 20. JAVA_DUMP_TDUMP_PATTERN variables
Variable Usage
%uid User ID
%job Job name
%y Year (2 digits)
%m Month (2 digits)
%d Day (2 digits)
%H Hour (2 digits)
%M Minute (2 digits)
%S Second (2 digits)
CEEDUMP
Language Environment (LE) dump. A formatted summary system dump that shows stack traces for each thread that is in the JVM process, together with register information and a short dump of storage for each register.

The dump is written to a z/OS UNIX file named CEEDUMP.yyyymmdd.hhmmss.pid, where yyyymmdd equals the current date, hhmmss the current time and pid the current process ID. The possible locations of this file are described in z/OS UNIX dump locations.

HEAPDUMP
A formatted dump (a list) of the objects that are on the Java heap.

The dump is written to a z/OS UNIX file named HEAPDUMP.yyyymmdd.hhmmss.pid.TXT, where yyyymmdd equals the current date, hhmmss the current time and pid the current process ID. The possible locations of this file are described in z/OS UNIX dump locations.

JAVADUMP
A formatted analysis of the JVM. It contains diagnostic information related to the JVM and the Java application, such as the application environment, threads, native stack, locks, and memory.

The dump is written to a z/OS UNIX file named JAVADUMP.yyyymmdd.hhmmss.pid.TXT, where yyyymmdd equals the current date, hhmmss the current time and pid the current process ID. The possible locations of this file are described in z/OS UNIX dump locations.

Refer to Java Diagnostic Guide (SC34-6358) for more information on JVM dumps, and Language Environment Debugging Guide (GA22-7560) for LE-specific information.

z/OS UNIX dump locations

The JVM checks each of the following locations for existence and write-permission, and stores the CEEDUMP, HEAPDUMP, and JAVADUMP files in the first one available. Note that you must have enough free disk space for the dump file to be written correctly.

  1. The directory in environment variable _CEE_DMPTARG, if found. This variable is set in rsed.envvars as /tmp. It can be changed to /dev/null to avoid creating the dump files.
  2. The current working directory, if the directory is not the root directory (/), and the directory is writable.
  3. The directory in environment variable TMPDIR (an environment variable that indicates the location of a temporary directory if it is not /tmp), if found.
  4. The /tmp directory.
  5. If the dump cannot be stored in any of the above, it is put to stderr.

Tracing

JES Job Monitor tracing

JES Job Monitor tracing is controlled by the system operator, as described in Operator commands.

RSE tracing

There are several log files created by the components related to RSE. Most are located in userlog/$LOGNAME/, where userlog is the combined value of the user.log and DSTORE_LOG_DIRECTORY directives in rsed.envvars, and $LOGNAME is the logon user ID (uppercase). If the user.log directive is commented out or not present, the home path of the user is used. The home path is defined in the OMVS security segment of the user ID. If the DSTORE_LOG_DIRECTORY directive is commented out or not present, then .eclipse/RSE/ is appended to the user.log value.

The amount of data written to ffs*.log, lock.log and rsecomm.log is controlled by the modify rsecommlog operator command, or by setting debug_level in rsecomm.properties. See Operator commands and (Optional) RSE tracing for more details.

The creation of the .dstore* log files is controlled by the -DDSTORE_* Java startup options, as described in Defining extra Java startup parameters with _RSE_JAVAOPTS.

Notes:
  1. The .eclipse directory and the .dstore* log files start with a dot (.), which makes them hidden. Use z/OS UNIX command ls -lA to list hidden files and directories. When using the Developer for System z client, select the Window > Preferences... > Remote Systems > Files preference page and enable "Show hidden files".
  2. The .dstore* log files are created in ASCII. Use z/OS UNIX command iconv -f ISO8859-1 -t IBM-1047 .dstore* to display them in EBCDIC (when using code page IBM-1047).

The RSE daemon and RSE thread pool specific log files are located in daemon-home, where daemon-home is the value of the daemon.log directive in rsed.envvars. If the daemon.log directive is commented out or not present, the home directory of the user ID assigned to the RSED started task is used. The home directory is defined in the OMVS security segment of the user ID.

The amount of data written to rsedaemon.log and rseserver.log is controlled by the modify rsedaemonlog and modify rseserverlog operator commands or by setting debug_level in rsecomm.properties . See Operator commands and (Optional) RSE tracing for more details.

serverlogs.count, stderr.*.log, and stdout.*.log are only created if the enable.standard.log directive in rsed.envvars is active, or if the function is dynamically activated with the modify rsestandardlog on operator command..

Lock daemon tracing

The lock daemon-specific log is located in the STDOUT DD of the LOCKD started task. The amount of data written to the log is controlled by the LOG startup parameter. See Operator commands and (Optional) RSE tracing for more details.

CARMA tracing

The user can control the amount of trace info CARMA generates by setting Trace Level in the properties tab of the CARMA connection on the client. The choices for Trace Level are:

The default value is the following:

Error Logging

Refer to Log files for more information on log file locations.

Error feedback tracing

The following procedure allows gathering of information needed to diagnosis error feedback problems with remote build procedures. This tracing will cause performance degradation and should only be done under the direction of the IBM support center. All references to hlq in this section refer to the high-level qualifier used during installation of Developer for System z. The installation default is FEK, but this might not apply to your site.

  1. Make a backup copy of your active ELAXFCOC compile procedure. This procedure is default shipped in data set hlq.SFEKSAMP, but could have been copied to a different location, such as SYS1.PROCLIB, as described in ELAXF* remote build procedures.
  2. Change the active ELAXFCOC procedure to include the 'MAXTRACE' string on the EXIT(ADEXIT(ELAXMGUX)) compile option.
    //COBOL  EXEC PGM=IGYCRCTL,REGION=2048K,
    //*            PARM=('EXIT(ADEXIT(ELAXMGUX))',
    //             PARM=('EXIT(ADEXIT(''MAXTRACE'',ELAXMGUX))',
    //             'ADATA',
    //             'LIB',
    //             'TEST(NONE,SYM,SEP)',
    //             'LIST',
    //             'FLAG(I,I)'&CICS &DB2 &COMP)
    Note:
    You have to double the apostrophes around MAXTRACE. The option is now: EXIT(ADEXIT(''MAXTRACE'',ELAXMGUX)).
  3. Perform a Remote Syntax Check on the COBOL program for which you want detailed tracing.
  4. The SYSOUT part of the JES output will start by listing the names of the data sets for SIDEFILE1, SIDEFILE2, SIDEFILE3 and SIDEFILE4.
    ABOUT TOO OPEN SIDEFILE1 - NAME = 'uid.DT021207.TT110823.M0000045.C0000000'
    SUCCESSFUL OPEN SIDEFILE1 - NAME = 'uid.DT021207.TT110823.M0000045.C0000000'
    ABOUT TOO OPEN SIDEFILE2 - NAME = 'uid.DT021207.TT110823.M0000111.C0000001'
    SUCCESSFUL OPEN SIDEFILE2 - NAME = 'uid.DT021207.TT110823.M0000111.C0000001'
    ABOUT TOO OPEN SIDEFILE3 - NAME = 'uid.DT021207.TT110823.M0000174.C0000002'
    SUCCESSFUL OPEN SIDEFILE3 - NAME = 'uid.DT021207.TT110823.M0000174.C0000002'
    ABOUT TOO OPEN SIDEFILE4 - NAME = 'uid.DT021207.TT110823.M0000236.C0000003'
    SUCCESSFUL OPEN SIDEFILE4 - NAME = 'uid.DT021207.TT110823.M0000236.C0000003'
    Note:
    Depending on your settings, SIDEFILE1 and SIDEFILE2 may be pointing to a DD statement (SUCCESSFUL OPEN SIDEFILE1 - NAME = DD:WSEDSF1). Refer to the JESJCL part of the output (which is located before the SYSOUT part) to get the actual data set name.
           22 //COBOL.WSEDSF1 DD DISP=MOD,
              // DSN=uid.ERRCOB.member.SF1.Z682746.XML
           23 //COBOL.WSEDSF2 DD DISP=MOD,
              // DSN=uid.ERRCOB.member.SF1.Z682747.XML
  5. Copy these four data sets to your PC, for example, by creating a local COBOL project in Developer for System z and adding the SIDEFILE1->4 data sets.
  6. Copy the complete JES job log to your PC, for example, by opening the job output in Developer for System z and saving it to the local project by selecting File > Save As ... .
  7. Restore procedure ELAXFCOC to the original state, either by undoing the change (remove the ''MAXTRACE'', string in the compile options) or restoring the backup.
  8. Send the collected files (SIDEFILE1->4 and job log) to the IBM support center.

z/OS UNIX permission bits

Developer for System z requires that the z/OS UNIX file system and some z/OS UNIX files have certain permission bits set.

SETUID file system attribute

Remote Systems Explorer (RSE) is the Developer for System z component that provides core services such as connecting the client to the host. It must be allowed to perform tasks such as creating the user's security environment.

The file system (HFS or zFS) in which Developer for System z is installed must be mounted with the SETUID permission bit on (this is the system default). Mounting the file system with the NOSETUID parameter will prevent Developer for System z from creating the user's security environment, and will fail the connection request.

Use the TSO ISHELL command to list the current status of the SETUID bit. In the ISHELL panel, select File_systems > 1. Mount table... to list the mounted file systems. The a line command will show the attributes for the selected file system, where the "Ignore SETUID" field should be 0.

Program Control authorization

Remote Systems Explorer (RSE) is the Developer for System z component that provides core services such as connecting the client to the host. It must run program controlled in order to perform tasks such as switching to the user ID of the client.

The z/OS UNIX program control bit is set during SMP/E install where needed, except for the Java interface to your security product, as documented in Security considerations. These permission bits might get lost if you did not preserve them during a manual copy of the Developer for System z directories.

The following Developer for System z files must be program controlled:

Use z/OS UNIX command ls -E to list the extended attributes, in which the program control bit is marked with the letter p, as shown in the following sample ($ is the z/OS UNIX prompt):

$ cd /usr/lpp/rdz
$ ls -E lib/fekf*
-rwxr-xr-x  -ps-  2 user     group      94208 Jul  8 12:31 lib/fekfdir.dll

Use z/OS UNIX command extattr +p to set the program control bit manually, as shown in the following sample ($ and # are the z/OS UNIX prompt):

$ cd /usr/lpp/rdz
$ su
# extattr +p lib/fekf*
# exit
$ ls -E lib/fekf*
-rwxr-xr-x  -ps-  2 user     group      94208 Jul  8 12:31 lib/fekfdir.dll
Note:
To be able to use the extattr command, you must have at least READ access to the BPX.FILEATTR.PROGCTL profile in the FACILITY class of your security software, or be a superuser (UID 0) if this profile is not defined. For more information, refer to UNIX System Services Planning (GA22-7800).

Sticky bit

Some of the optional Developer for System z services require that MVS load modules are available to z/OS UNIX. This is done by creating a stub (a dummy file) in z/OS UNIX with the "sticky" bit on. When the stub is executed, z/OS will look for an MVS load module with the same name and execute the load module instead.

The z/OS UNIX sticky bit is set during SMP/E install where needed. These permission bits might get lost if you did not preserve them during a manual copy of the Developer for System z directories.

The following Developer for System z files must have the sticky bit on:

Use z/OS UNIX command ls -l to list the permissions, in which the sticky bit is marked with the letter t, as shown in the following sample ($ is the z/OS UNIX prompt):

$ cd /usr/lpp/rdz
$ ls -l bin/CRA*
-rwxr-xr-t   2 user     group         71 Jul  8 12:31 bin/CRASTART

Use z/OS UNIX command chmod +t to set the sticky bit manually, as shown in the following sample ($ and # are the z/OS UNIX prompt):

$ cd /usr/lpp/rdz
$ su
# chmod +t bin/CRA*
# exit
$ ls -l bin/CRA*
-rwxr-xr-t   2 user     group         71 Jul  8 12:31 bin/CRASTART
Note:
To be able to use the chmod command, you must have at least READ access to the SUPERUSER.FILESYS.CHANGEPERMS profile in the UNIXPRIV class of your security software, or be a superuser (UID 0) if this profile is not defined. For more information, refer to UNIX System Services Planning (GA22-7800).

Reserved TCP/IP ports

With the netstat command (TSO or z/OS UNIX) you can get an overview of the ports currently in use. The output of this command will look similar to the example below. The ports used are the last number (behind the "..") in the "Local Socket" column. Since these ports are already in use, they cannot be used for the Developer for System z configuration.

IPv4

MVS TCP/IP NETSTAT CS VxRy       TCPIP Name: TCPIP           16:36:42
User Id  Conn     Local Socket           Foreign Socket         State
-------  ----     ------------           --------------         -----
BPXOINIT 00000014 0.0.0.0..10007         0.0.0.0..0             Listen
INETD4   0000004D 0.0.0.0..512           0.0.0.0..0             Listen
RSED     0000004B 0.0.0.0..4035          0.0.0.0..0             Listen
JMON     00000038 0.0.0.0..6715          0.0.0.0..0             Listen
 

IPv6

MVS TCP/IP NETSTAT CS VxRy       TCPIP Name: TCPIP           12:46:25
User Id  Conn     State
-------  ----     -----
BPXOINIT 00000018 Listen
  Local Socket:   0.0.0.0..10007
  Foreign Socket: 0.0.0.0..0
INETD4   00000046 Listen
  Local Socket:   0.0.0.0..512
  Foreign Socket: 0.0.0.0..0
RSED     0000004B Listen
  Local Socket:   0.0.0.0..4035
  Foreign Socket: 0.0.0.0..0
JMON     00000037 Listen
  Local Socket:   0.0.0.0..6715
  Foreign Socket: 0.0.0.0..0

Another limitation that can exist is reserved TCP/IP ports. There are the following two common places to reserve TCP/IP ports:

These reserved ports can be listed with the netstat portl command (TSO or z/OS UNIX), which creates an output like that in the example as follows:

MVS TCP/IP NETSTAT CS VxRy       TCPIP Name: TCPIP           17:08:32
Port# Prot User     Flags    Range       IP Address
----- ---- ----     -----    -----       ----------
00007 TCP  MISCSERV DA
00009 TCP  MISCSERV DA
00019 TCP  MISCSERV DA
00020 TCP  OMVS     D
00021 TCP  FTPD1    DA
00025 TCP  SMTP     DA
00053 TCP  NAMESRV  DA
00080 TCP  OMVS     DA
03500 TCP  OMVS     DAR      03500-03519
03501 TCP  OMVS     DAR      03500-03519

Refer to Communications Server: IP System Administrator's Commands (SC31-8781) for more information on the NETSTAT command.

Note:
The NETSTAT command only shows the information defined in PROFILE.TCPIP, which should overlap the BPXPRMxx definitions. In case of doubt or problems, check the BPXPRMxx parmlib member to verify the ports being reserved here.

Address Space size

The RSE daemon, which is a z/OS UNIX Java process, requires a large region size to perform its functions. Therefore it is important to set large storage limits for OMVS address spaces.

startup JCL requirements

The RSE daemon is started by JCL using BPXBATSL, whose region size must be 0.

Limitations set in SYS1.PARMLIB(BPXPRMxx)

Set MAXASSIZE in SYS1.PARMLIB(BPXPRMxx), which defines the default OMVS address space (process) region size, to 2G. This is the maximum size allowed. This is a system-wide limit, and thus active for all z/OS UNIX address spaces. If this is not desired, then you can set the limit also just for Developer for System z in your security software.

This value can be checked and set dynamically (until the next IPL) with the following console commands, as described in MVS System Commands (GC28-1781):

  1. DISPLAY OMVS,O
  2. SETOMVS MAXASSIZE=2G

Limitations stored in the security profile

Check ASSIZEMAX in the daemon's user ID OMVS segment, and set it to 2147483647 or, preferably, to NONE to use the SYS1.PARMLIB(BPXPRMxx) value.

Using RACF, this value can be checked and set with the following TSO commands, as described in Security Server RACF Command Language Reference (SA22-7687):

  1. LISTUSER userid NORACF OMVS
  2. ALTUSER userid OMVS(NOASSIZEMAX)

Limitations enforced by system exits

Make sure you are not allowing system exits IEFUSI or IEALIMIT to control OMVS address space region sizes. A possible way to accomplish this is by coding SUBSYS(OMVS,NOEXITS) in SYS1.PARMLIB(SMFPRMxx).

SYS1.PARMLIB(SMFPRMxx) values can be checked and activated with the following console commands, as described in MVS System Commands (GC28-1781):

  1. DISPLAY SMF,O
  2. SET SMF=xx

APPC transaction and TSO Commands service

If you cannot use the APPC version of the TSO Commands service, there are two areas where problems may arise: starting the APPC server transaction and connecting to RSE.

The REXX provided in (Optional) APPC transaction for the TSO Commands service can help with solving APPC problems since it gives you the possibility to manage APPC interactively through ISPF panels. Be aware however that you can deactivate the transaction with this tool; the transaction is still there but will not accept any connections.

The following list is a selection of Technotes currently available on the support Web site (http://www-306.ibm.com/software/awdtools/rdz/support/). Refer to the support Web site for additional information:

Note:
This list is not definitive. Check the support Web site for additional Technotes.

Miscellaneous information

System limits

SYS1.PARMLIB(BPXPRMxx) defines many z/OS UNIX related limitations, which might be reached when several Developer for System z clients are active. Most BPXPRMxx values can be changed dynamically with the SETOMVS and SET OMVS console commands.

Use the SETOMVS LIMMSG=ALL console command to have z/OS UNIX display console messages (BPXI040I) when any of the BPXPRMxx limits is about to be reached.

Connection refused

Each RSE connection starts several processes which are permanently active. New connections can be refused due to the limit set in SYS1.PARMLIB(BPXPRMxx) on the amount of processes, especially when users share the same UID (such as when using the default OMVS segment).

Another source of refused connections is the limit on the amount of active z/OS address spaces and z/OS UNIX users.

Known requisite issues

Opening MVS data sets fails

When using APPC for the TSO Commands service, reading, and writing an MVS data set requires the use of a socket physical file system domain. If the file system is not properly defined or it has not enough sockets, the lock manager (FFS) might fail read/write requests. The ffs*.log files will show messages like the following:

Verify that the SYS1.PARMLIB(BPXPRMxx) member contains the following statements:

FILESYSTYPE TYPE(UDS) ENTRYPOINT(BPXTUINT)
NETWORK DOMAINNAME(AF_UNIX)
        DOMAINNUMBER(1)
        MAXSOCKETS(2000)
        TYPE(UDS)

Another probable cause for this problem, when using APPC for the TSO Commands service, is that TCP/IP Resolver cannot resolve the host address properly due to a missing or incomplete resolver configuration file. A clear indication for this problem is the following message in lock.log:

clientip(0.0.0.0) <> callerip(<host IP address>)

Execute the fekfivpt TCP/IP IVP, as described in Installation verification. The resolver configuration section of the output will look like the following sample:

Resolver Trace Initialization Complete -> 2008/07/02 13:11:54.745964

res_init Resolver values:
 Global Tcp/Ip Dataset  = None
 Default Tcp/Ip Dataset = None
 Local Tcp/Ip Dataset   = /etc/resolv.conf
 Translation Table      = Default
 UserId/JobName         = USERID
 Caller API             = LE C Sockets
 Caller Mode            = EBCDIC

Ensure that the definitions in the file (or data set) referenced by "Local Tcp/Ip Dataset" are correct.

This field will be blank if you do not use a default name for the IP resolver file (using the z/OS UNIX search order). If so, add the following statement to rsed.envvars, where <resolver file> or <resolver data> represents the name of your IP resolver file:

RESOLVER_CONFIG=<resolver file>

or

RESOLVER_CONFIG='<resolver data set>'

Host Connect Emulator

Security considerations

Developer for System z provides mainframe access to users on a non-mainframe workstation. Validating connection requests, providing secure communication between the host and the workstation, and authorizing and auditing activity are therefore important aspects of the product configuration.

The security mechanisms used by Developer for System z servers and services rely on the file system it resides in being secure. This implies that only trusted system administrators should be able to update the program libraries and configuration files.

The following topics are covered in this chapter:

Note:
Remote Systems Explorer (RSE), which provides core services such as connecting the client to the host, consists of 2 logical entities:

Refer to Understanding Developer for System z to learn about basic Developer for System z design concepts.

Authentication methods

Developer for System z supports multiple ways to authenticate a user ID provided by a client upon connection.

Note that the authentication data provided by the client is only used once, during initial connection setup. Once a user ID is authenticated, the user ID and self-generated PassTickets are used for all actions that require authentication.

User ID and password

The client provides a user ID and matching password upon connection. The user ID and password are used to authenticate the user with your security product.

User ID and one-time password

Based upon a unique token, a one-time password can be generated by a third-party product. One-time passwords improve your security setup as the unique token cannot be copied and used without the user's knowledge, and an intercepted password is useless because it is valid only once.

The client provides a user ID and the one-time password upon connection, which is used to authenticate the user ID with the security exit provided by the third party. This security exit is expected to ignore the PassTickets used to satisfy authentication requests during normal processing. The PassTickets must be processed by your security software.

X.509 certificate

A third party can provide one or more X.509 certificates that can be used for authenticating a user. When stored on secure devices, X.509 certificates combine a secure setup with ease of use for the user (no user ID or password needed).

Upon connection, the client provides a selected certificate, and optionally a selected extension, which is used to authenticate the user ID with your security product.

Note that this authentication method is only supported by the RSE daemon connection method, and that SSL must be enabled.

JES Job Monitor authentication

Client authentication is done by RSE daemon (or REXEC/SSH) as part of the client's connection request. Once the user is authenticated, self-generated PassTickets are used for all future authentication requests, including the automatic logon to JES Job Monitor.

In order for JES Job Monitor to validate the user ID and PassTicket presented by RSE, JES Job Monitor must be allowed to evaluate the PassTicket. This implies the following:

Note:
Previous clients (version 7.0 and older) communicate directly with JES Job Monitor. For these connections, only the user ID and password authentication method is supported.

Connection security

Different levels of communication security are supported by RSE, which controls all communication between the client and Developer for System z services:

Limit external communication to specified ports

The system programmer can specify the ports on which the RSE server can communicate with the client. By default, any available port is used. This range of ports has no connection with the RSE daemon port.

To help understand the port usage, a brief description of RSE's connection process follows:

  1. The client connects to host port 4035, RSE daemon.
  2. The RSE daemon creates an RSE server thread.
  3. The RSE server opens a host port for the client to connect. The selection of this port can be configured by the user, either on the client in the subsystem properties tab (this is not recommended) or through the _RSE_PORTRANGE definition in rsed.envvars.
  4. The RSE daemon returns the port number to the client.
  5. The client connects to the host port.
Note:
The process is similar for the (optional) alternative connection method using REXEC/SSH, which is described in (Optional) Using REXEC (or SSH).

Communication encryption using SSL

All external Developer for System z data streams that pass through RSE can be encrypted using Secure Socket Layer (SSL). The usage of SSL is controlled by the settings in the ssl.properties configuration file, as described in SSL encrypted communication.

The Host Connect Emulator on the client connects to a TN3270 server on the host. The usage of SSL is controlled by TN3270, as documented in the Communications Server IP Configuration Guide (SC31-8775).

The Application Deployment Manager client uses the CICS TS Web Service or the RESTful interface to invoke the Application Deployment Manger host services. The usage of SSL is controlled by CICS TS, as documented in RACF Security Guide for CICS TS.

Port Of Entry checking

Developer for System z supports Port Of Entry (POE) checking, which allows host access only to trusted TCP/IP addresses. The usage of POE is controlled by the definition of specific profiles in your security software and the enable.port.of.entry directive in rsed.envvars, as described in Port Of Entry (POE) checking.

Note that activating POE will impact other TCPIP applications that support POE checking, such as INETD.

TCP/IP ports

Figure 36. TCP/IP ports
TCP/IP ports

Figure 36 shows the TCP/IP ports that can be used by Developer for System z. The arrows show which party does the bind (arrowhead side) and which one connects.

External communication

Define the following ports to your firewall protecting the z/OS host, as they are used for client-host communication (using the tcp protocol):

Notes:
  1. Previous clients (version 7.0 and older) communicate directly with JES Job Monitor, default port 6715.
  2. During a remote debug session for Cobol, PL/I or Assembler, IBM Debug Tool for z/OS is invoked. This product communicates directly with the client. This communication is initiated on the host, and connects to port 8001 on the client.

Internal communication

Several Developer for System z host services run in separate threads or address spaces and are using TCP/IP sockets as communication mechanism. All these services use RSE for communicating with the client, making their data stream confined to the host only. For some services any available port will be used, for others the system programmer can choose the port or port range that will be used:

Note:
Previous clients (version 7.0 and older) communicate directly with the JES Job Monitor server, default port 6715.

CARMA and TCP/IP ports

In most cases, like for RSE daemon, a server binds to a port and listens for connection requests. CARMA however uses a different approach, as the CARMA server is not active yet when the client initiates the connection request.

When the client sends a connection request, the CARMA miner, which is active as a user thread in a RSE thread pool, will find a free port in the range specified in the CRASRV.properties configuration file and binds to it. The miner then starts the CARMA server and passes the port number, so that the server knows to which port to connect. Once the server is connected, the client can send requests to the server and receive the results.

So from a TCP/IP perspective, RSE (via the CARMA miner) is the server that binds to the port, and the CARMA server is the client connecting to it.

Using PassTickets

After logon, PassTickets are used to establish thread security within the RSE server. This feature cannot be disabled. PassTickets are system generated passwords with a lifespan of about 10 minutes. The generated PassTickets are based upon the DES encryption algorithm, the user ID, the application ID, a time and date stamp, and a secret key. This secret key is a 64 bit number (16 hex characters) that must be defined to your security software.

To help understand the PassTicket usage, a brief description of RSE's security process follows:

  1. The client connects to host port 4035, RSE daemon.
  2. The RSE daemon authenticates the client, using the credentials presented by the client.
  3. The RSE daemon creates a unique client ID and an RSE server thread.
  4. The RSE server generates a PassTicket and creates a security environment for the client, using the PassTicket as password.
  5. The client connects to the host port returned by the RSE daemon.
  6. The RSE server validates the client using the client ID.
  7. The RSE server uses a newly generated PassTicket as password for all future actions requiring a password.

The actual password of the client is no longer needed after initial authentication because SAF-compliant security products can evaluate both PassTickets and regular passwords. RSE server generates and uses a PassTicket each time a password is required, resulting in a (temporary) valid password for the client.

Using PassTickets allows RSE to set up a user-specific security environment at will, without the need of storing all user IDs and passwords in a table, which could be compromised. It also allows for client authentication methods that do not use reusable passwords, such as X.509 certificates.

Security profiles in the APPL and PTKTDATA classes are required to be able to use PassTickets. These profiles are application specific and thus do not impact your current system setup.

PassTickets being application specific implies that both RSE and JES Job Monitor must use the same application ID (APPLID). By default both servers use FEKAPPL as APPLID, but this can be changed by the APPLID directive in rsed.envvars for RSE and in FEJJCNFG for JES Job Monitor.

Attention: The client connection request will fail if PassTickets are not set up correctly.

Audit logging

Developer for System z supports audit logging of actions that are managed by the RSE daemon. The audit logs are stored as text files in the daemon log directory, using the CSV (Comma Separated Value) format.

Audit control

Multiple options in rsed.envvars influence the audit function, as documented in Defining extra Java startup parameters with _RSE_JAVAOPTS.

The modify switch operator command can be used to manually switch to a new audit log file, as documented in Operator commands.

A warning message is sent to the console when the file system holding the audit log files is running low on free space. This console message (FEK103E) is repeated regularly until the low space issue is resolved. Refer to Console messages for a list of console messages generated by RSE.

Audit data

A new audit log file is started after a predetermined time or when the modify switch operator command is issued. The old log file is saved as audit.log.yyyymmdd.hhmmss, where yyyymmdd.hhmmss is the date/timestamp when this log was closed. The system date/timestamp assigned to the file indicates the creation of the log file. The combination of the two dates shows the time period covered by this audit log file.

The following actions are logged:

Each logged action is stored (with a date/timestamp) using the CSV (Comma Separated Value) format, which can be read by an automation or data analysis tool.

Audit log files have permission bit mask 640 (-rw-r-----), which means that the owner (RSE daemon z/OS UNIX uid) has read and write access, and the owner's (default) group has read access. All other access attempts are denied, unless it is done by a super user (UID 0) or somebody with sufficient permission to the SUPERUSER.FILESYS profile in the UNIXPRIV class.

JES security

Developer for System z allows clients access to the JES spool through the JES Job Monitor. The server provides basic access limitations, which can be extended with the standard spool file protection features of your security product. Operator actions (Hold, Release, Cancel, and Purge) against spool files are done through an EMCS console, for which conditional permits must be set up.

Actions against jobs - target limitations

JES Job Monitor does not provide Developer for System z users full operator access to the JES spool. Only the Hold, Release, Cancel, and Purge commands are available, and by default, only for spool files owned by the user. The commands are issued by selecting the appropriate option in the client menu structure (there is no command prompt). The scope of the commands can be widened, using security profiles to define for which jobs the commands are available.

Similar to the SDSF SJ action character, JES Job Monitor also supports the Show JCL command to retrieve the JCL that created the selected job output, and show it in an editor window. JES Job Monitor retrieves the JCL from JES, making it a useful function for situations in which the original JCL member is not easily located.

Table 21. JES Job Monitor console commands
Action JES2 JES3
Hold $Hx(jobid)

with x = {J, S or T}

*F,J=jobid,H
Release $Ax(jobid)

with x = {J, S or T}

*F,J=jobid,R
Cancel $Cx(jobid)

with x = {J, S or T}

*F,J=jobid,C
Purge $Cx(jobid),P

with x = {J, S or T}

*F,J=jobid,C
Show JCL not applicable not applicable

The available JES commands listed in Table 21 are by default limited to jobs owned by the user. This can be changed with the LIMIT_COMMANDS directive, as documented in FEJJCNFG, JES Job Monitor configuration file.

Table 22. LIMIT_COMMANDS command permission matrix
Job owner
LIMIT_COMMANDS User Other
USERID (default) Allowed Not allowed
LIMITED Allowed Allowed only if explicitly permitted by security profiles
NOLIMIT Allowed Allowed if permitted by security profiles or when the JESSPOOL class is not active

JES uses the JESSPOOL class to protect SYSIN/SYSOUT data sets. Similar to SDSF, JES Job Monitor extends the use of the JESSPOOL class to protect job resources as well.

If LIMIT_COMMANDS is not USERID, then JES Job Monitor will query for permission to the related profile in the JESSPOOL class, as shown in the following table.

Table 23. Extended JESSPOOL profiles
Command JESSPOOL profile Required access
Hold nodeid.userid.jobname.jobid ALTER
Release nodeid.userid.jobname.jobid ALTER
Cancel nodeid.userid.jobname.jobid ALTER
Purge nodeid.userid.jobname.jobid ALTER
Show JCL nodeid.userid.jobname.jobid.JCL READ

Use the following substitutions in the preceding table:

nodeid NJE node ID of the target JES subsystem
userid Local user ID of the job owner
jobname Name of the job
jobid JES job ID

If the JESSPOOL class is not active, then there is different behavior for the LIMITED and NOLIMIT value of LIMIT_COMMANDS, as described in Table 9. The behavior is identical when JESSPOOL is active, since the class, by default, denies permission if a profile is not defined.

Actions against jobs - execution limitations

The second phase of JES spool command security, after specifying the permitted targets, includes the permits needed to actually execute the operator command. This execution authorization is enforced by the z/OS and JES security checks.

Note that Show JCL is not an operator command such as the other JES Job Monitor commands (Hold, Release, Cancel, and Purge), so the limitations below do not apply because there is no further security check.

JES Job Monitor issues all JES operator commands requested by a user through an extended MCS (EMCS) console, whose name is controlled with the CONSOLE_NAME directive, as documented in FEJJCNFG, JES Job Monitor configuration file.

This setup allows the security administrator to define granular command execution permits using the OPERCMDS and CONSOLE classes.

Assuming the identity of the JES Job Monitor server by creating a JMON console from a TSO session is prevented by your security software. Even though the console can be created, the point of entry is different (JES Job Monitor versus TSO). JES commands issued from this console will fail the security check, if your security is set up as documented in this publication and the user does not have authority to JES commands through other means.

Note that JES Job Monitor cannot create the console when a command must be executed if the console name is already in use. To prevent this, the system programmer can set the GEN_CONSOLE_NAME=ON directive in the JES Job Monitor configuration file or the security administrator can define security profiles to stop TSO users from creating a console. The following sample RACF commands prevent everyone (except those permitted) from creating a TSO or SDSF console:

Note:
Without being authorized for these operator commands, users will still be able to submit jobs and read job output through the JES Job Monitor, if they have sufficient authority to possible profiles that protect these resources (such as those in the JESINPUT, JESJOBS and JESSPOOL classes).

Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on operator command protection.

Access to spool files

JES Job Monitor allows browse access to all spool files by default. This can be changed with the LIMIT_VIEW directive, as documented in FEJJCNFG, JES Job Monitor configuration file.

Table 24. LIMIT_VIEW browse permission matrix
Job owner
LIMIT_VIEW User Other
USERID Allowed Not allowed
NOLIMIT (default) Allowed Allowed if permitted by security profiles or when the JESSPOOL class is not active

To limit users to their own jobs on the JES spool, define the "LIMIT_VIEW=USERID" statement in the JES Job Monitor configuration file, FEJJCNFG. If the users need access to a wider range of jobs, but not all, use the standard spool file protection features of your security product, such as the JESSPOOL class.

When defining further protection, keep in mind that JES Job Monitor uses SAPI (SYSOUT application program interface) to access the spool. This implies that the user needs at least UPDATE access to the spool files, even for browse functionality. This requisite does not apply if you run z/OS 1.7 (z/OS 1.8 for JES3) or higher. Here READ permission is sufficient for browse functionality.

Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on JES spool file protection.

SSL encrypted communication

External (client-host) communication can be encrypted using SSL (Secure Socket Layer). This feature is disabled by default and is controlled by the settings in ssl.properties, as documented in (Optional) RSE SSL encryption.

RSE daemon and RSE server support different mechanisms to store certificates due to architectural differences between the two. This implies that SSL definitions and certificates are required for both RSE daemon and RSE server. A shared certificate can be used if RSE daemon and RSE server use the same certificate management method.

Table 25. SSL certificate storage mechanisms
Certificate storage Created and managed by RSE daemon RSE server
key ring SAF compliant security product supported supported
key database z/OS UNIX's gskkyman supported /
key store Java's keytool / supported
Note:
SAF-compliant key rings are the preferred method for managing certificates.

SAF-compliant key rings can store the certificate's private key either in the security database or by using ICSF (Integrated Cryptographic Service Facility), the interface to System z cryptographic hardware.

ICSF is recommended for the storage of the private keys associated with digital certificates, because it is a more secure solution than non-ICSF private key management. ICSF ensures that private keys are encrypted under the ICSF master key and that access to them is controlled by general resources in the CSFKEYS and CSFSERV security classes. In addition, operational performance is improved because ICSF utilizes the hardware Cryptographic Coprocessor.

RSE daemon uses System SSL functions to manage SSL encrypted communications. This implies that SYS1.SIEALNKE must be program controlled by your security software and available to RSE via LINKLIST or the STEPLIB directive in rsed.envvars.

The RSE user ID (STCRSE in the sample commands below) needs authorization to access his key ring and the related certificates when SAF-compliant key rings are used for either RSE daemon or RSE server.

Refer to Appendix A. Setting up SSL and X.509 authentication for more details on activating SSL for Developer for System z.

Client authentication using X.509 certificates

RSE daemon supports users authenticating themselves with an X.509 certificate. Using SSL encrypted communication is a prerequisite for this function, as it is an extension to the host authentication with a certificate used in SSL.

RSE daemon starts the client authentication process by validating the client certificate. Some key aspects that are checked are the dates the certificate is valid and the trust-worthiness of the Certificate Authority (CA) used to sign the certificate. Optionally, a (third party) Certificate Revocation List (CRL) can also be consulted.

After RSE daemon validates the certificate, it is processed for authentication. The certificate is passed on to your security product for authentication, unless rsed.envvars directive enable.certificate.mapping is set to false, at which point RSE daemon will do the authentication.

If successful, the authentication process will determine the user ID to be used for this session, which is then tested by RSE daemon to ensure it is usable on the host system where RSE daemon is running

The last check (which is done for every authentication mechanism, not just X.509 certificates) verifies that the user ID is allowed to use Developer for System z.

If you are familiar with the SSL security classifications used by TCP/IP, the combination of these validation steps match the "Level 3 Client authentication" specifications (the highest available).

Certificate Authority (CA) validation

Part of the certificate validation process includes checking that the certificate was signed by a Certificate Authority (CA) you trust. In order to do so, RSE daemon must have access to a certificate that identifies the CA.

When using the gskkyman key database for your SSL connection, the CA certificate must be added to the key database.

When using an SAF key ring (which is the advised method), you must add the CA certificate to your security database as a CERTAUTH certificate with the TRUST or HIGHTRUST attribute, as shown in this sample RACF command:

Note that most security products already have the certificates for well known CA's available in their database with a NOTRUST status. Use the following sample RACF commands to list the existing CA certificates and mark one as trusted based on the label assigned to it.

Note:
The HIGHTRUST status is required if you rely on RACF authenticating the user based upon the HostIdMappings extension in the certificate. Refer to Authentication by your security software for more information.

Once the CA certificate is added to your security database, it must be connected to the RSE key ring, as shown in this sample RACF command:

Refer to Security Server RACF Command Language Reference (SA22-7687) for more information on the RACDCERT command.

Attention: If you rely on RSE daemon instead of your security software to authenticate a user you must be cautious not to mix CAs with a TRUST and HIGHTRUST status in your SAF key ring or gskkyman key database. RSE daemon is not able to differentiate between the two, so certificates signed by a CA with TRUST status will be valid for user ID authentication purposes.

(Optional) Query a Certificate Revocation List (CRL)

If desired, you can instruct RSE daemon to check one or more Certificate Revocation List(s) (CRL) to add extra security to the validation process. This is done by adding CRL-related environment variables to rsed.envvars. Refer to rsed.envvars, RSE configuration file for information on these sample variables:

Refer to the Cryptographic Services System Secure Sockets Layer Programming (SC24-5901) for more information on these and other environment variables used by z/OS System SSL.

Note:
Be careful when specifying other z/OS System SSL environment variables (GSK_*) in rsed.envvars, as they might change the way RSE daemon handles SSL connections and certificate authentication.

Authentication by your security software

RACF performs several checks to authenticate a certificate and return the associated user ID. Note that other security products might do this differently. Refer to your security product documentation for more information on the initACEE function used to do the authentication (query mode).

  1. RACF checks if the certificate is defined in the DIGTCERT class. If so, RACF returns the user ID that was associated with this certificate when it was added to the RACF database.

    Certificates are defined to RACF using the RACDCERT command, as in the following example:

    RACDCERT ID(userid) ADD(dsn) TRUST WITHLABEL('label')
  2. If the certificate is not defined, RACF checks to see if there is a matching certificate name filter defined in the DIGTNMAP or DIGTCRIT classes. If so, it returns the user ID associated with the most specific matching filter.
    Note:
    It is advised not to use name filters for certificates used by Developer for System z, as these filters map all certificates to a single user ID. The result is that all your Developer for System z users will log on with the same user ID.
  3. If there is no matching name filter, RACF locates the HostIdMappings certificate extension and extracts the embedded user ID and host name pair. If found and validated, RACF returns the user ID defined within the HostIdMappings extension.

    The user ID and host name pair is valid if all these conditions are true:

    The definition of the HostIdMappings extension in ASN.1 syntax is:

    id-ce-hostIdMappings OBJECT IDENTIFIER::= {1 3 18 0 2 18 1}
    HostIdMappings::= SET OF HostIdMapping
    HostIdMapping::= SEQUENCE{
       hostName        IMPLICIT[1] IA5String,
       subjectId       IMPLICIT[2] IA5String,
       proofOfIdPossession IdProof OPTIONAL
     }
     IdProof::= SEQUENCE{
       secret        OCTET STRING,
       encryptionAlgorithm OBJECT IDENTIFIER
     }
    Note:
    A HostIdMappings extension is not honored if the target user ID was created after the start of the validity period for the certificate containing the HostIdMappings extension. Therefore, if you are creating user IDs specifically for certificates with HostIdMappings extensions, make sure that you create the user IDs before the certificate requests are submitted.

    Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on X.509 certificates, how they are managed by RACF, and how to define certificate name filters. Refer to Security Server RACF Command Language Reference (SA22-7687) for more information on the RACDCERT command.

Authentication by RSE daemon

Developer for System z can do basic X.509 certificate authentication without relying on your security product. Authentication done by RSE daemon requires a user ID and host name to be defined in a certificate extension, and is only activated if the enable.certificate.mapping directive in rsed.envvars is set to FALSE.

This function is intended to be used if your security product does not support authenticating a user based upon an X.509 certificate, or if your certificate would fail the test(s) done by your security product (for example, the certificate has a faulty identifier for the HostIdMappings extension and there is no name filter or definition in DIGTCERT).

The client will query the user for the extension identifier (OID) to use, which is by default the HostIdMappings OID, {1 3 18 0 2 18 1}.

RSE daemon will extract the user ID and host name from it using the format of the HostIdMappings extension. This format is described in Authentication by your security software .

The user ID and host name pair is valid if all these conditions are true:

Attention: It is up to the security administrator to ensure that all CAs known to RSE daemon are highly trusted, because RSE daemon cannot check if the one who signed the client certificate is highly trusted or just trusted. See Certificate Authority (CA) validation for more information on accessible CA certificates.

Port Of Entry (POE) checking

Developer for System z supports Port Of Entry (POE) checking, which allows host access only to trusted TCP/IP addresses. This feature is disabled by default and requires the definition of the BPX.POE security profile, as shown in the following sample RACF commands:

Notes:
  1. RSE must be configured to use POE by uncommenting the "enable.port.of.entry=true" option in rsed.envvars, as documented in Defining extra Java startup parameters with _RSE_JAVAOPTS.
  2. The RSE user ID STCRSE requires UID(0) when this profile is not defined and POE checking is enabled in rsed.envvars.
  3. Defining BPX.POE will impact other TC/PIP applications that support POE checking, such as INETD.
  4. Security zones (EZB.NETACCESS.** profiles, which are IP address ranges) should be set up in the SERVAUTH class to use the full strength of POE checking.

Refer to Communications Server IP Configuration Guide (SC31-8775) for more information on network access control using POE checking.

CICSTS security

Developer for System z allows, through Application Deployment Manager, CICS administrators to control which CICS resource definitions are editable by the developer, their default values, and the display of a CICS resource definition by means of the CICS Resource Definition (CRD) server. Refer to CICSTS considerations for more information on the required CICS TS security definitions.

CRD repository

The CRD server repository VSAM data set holds all the default resource definitions and must therefore be protected against updates, but developers must be allowed to read the values stored here.

CICS transactions

Developer for System z supplies multiple transactions that are used by the CRD server when defining and inquiring CICS resources. When the transaction is attached, CICS resource security checking, if enabled, insures that the user ID is authorized to run the transaction ID.

SSL encrypted communication

The Application Deployment Manager client uses CICS TS Web Services or the RESTful interface to invoke the CRD server. The usage of SSL for this communication is controlled by the CICS TS TCPIPSERVICE definition, as documented in and RACF Security Guide for CICS TS.

SCLM security

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

If security is enabled for a function by the SCLM administrator, SAF calls are made to verify authority to execute the protected function with the caller's or a surrogate user ID.

Refer to SCLM Developer Toolkit Administrator's Guide (SC23-9801), for more information on the required SCLM security definitions.

Developer for System z configuration files

There are several Developer for System z configuration files whose directives impact the security setup. Based upon the information in this chapter, the security administrator and systems programmer can decide what the settings should be for the following directives.

JES Job Monitor - FEJJCNFG

Note:
Details on these and other FEJJCNFG directives are available in FEJJCNFG, JES Job Monitor configuration file.

RSE - rsed.envvars

Note:
Details on these and other rsed.envvars directives are available in rsed.envvars, RSE configuration file.

RSE - ssl.properties

Note:
Details on these and other ssl.properties directives are available in (Optional) RSE SSL encryption.

Security definitions

Customize and submit sample member FEKRACF, which has sample RACF and z/OS UNIX commands to create the basic security definitions for Developer for System z.

FECRACF is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Refer to the RACF Command Language Reference (SA22-7687), for more information on RACF commands.

Note:

The following sections describe the required steps, optional configuration and possible alternatives.

Requirements and checklist

To complete the security setup, the security administrator needs to know the values listed in Table 26. These values were defined during previous steps of the installation and customization of Developer for System z.

Table 26. Security setup variables
Description
  • Default value
  • Where to find the answer
Value
Developer for System z product high level qualifier
  • FEK
  • SMP/E installation
Developer for System z customization high level qualifier
JES Job Monitor started task name
RSE daemon started task name
Lock daemon started task name

The following list is an overview of the required actions to complete the basic security setup of Developer for System z. As documented in the sections below, different methods can be used to fulfill these requirements, depending on the desired security level. Refer to the previous sections for information on the security setup of optional Developer for System z services.

Activate security settings and classes

Developer for System z utilizes a variety of security mechanisms to ensure a secure and controlled host environment for the client. In order to do so, several classes and security settings must be active, as shown with the following sample RACF commands:

Define an OMVS segment for Developer for System z users

A RACF OMVS segment (or equivalent) that specifies a valid non-zero z/OS UNIX user ID (UID), home directory, and shell command must be defined for each user of Developer for System z. Their default group also requires an OMVS segment with a group id.

Replace in the following sample RACF commands the #userid, #user-identifier, #group-name and #group-identifier placeholders with actual values:

Although it is advised not to do so, you can use the shared OMVS segment defined in the BPX.DEFAULT.USER profile of the FACILITY class to fulfill the OMVS segment requirement for Developer for System z.

Define data set profiles

READ access for users and ALTER for system programmers suffices for most Developer for System z data sets. Replace the #sysprog placeholder with valid user IDs or RACF group names. Also ask the system programmer who installed and configured the product for the correct data set names. FEK is the default high-level qualifier used during installation and FEK.#CUST is the default high-level qualifier for data sets created during the customization process.

Notes:
  1. You are strongly advised to protect FEK.SFEKAUTH against updates since this data set is APF authorized. The same is true for FEK.SFEKLOAD and FEK.SFEKLPA, but here because these data sets are program controlled.
  2. The sample commands in this publication and in the FEKRACF job assume that EGN (Enhanced Generic Naming) is active. This allows the usage of the ** qualifier to represent any number of qualifiers in the DATASET class. Substitute ** with * if EGN is not active on your system. Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on EGN.

Some of the optional Developer for System z components require additional security data set profiles. Replace the #sysprog, #ram-developer and #cicsadmin placeholders with valid user ID's or RACF group names:

Use the following sample RACF commands for a more secure setup where READ access is also controlled.

When controlling READ access to system data sets, you must provide Developer for System z servers and users permission to READ the following data sets:

Note:
When you use the Alternate Library for REXX product package, the default REXX runtime library name is REXX.*.SEAGALT. instead of REXX.*.SEAGLPA, as used in the sample above.

Define the Developer for System z started tasks

The following sample RACF commands create the JMON, RSED, and LOCKD started tasks, with protected user IDs (STCJMON, STCRSE, and STCLOCK respectively) and group STCGROUP assigned to them. Replace the #group-id and #user-id-* placeholders with valid OMVS IDs.

Notes:
  1. Ensure that the started tasks user IDs are protected by specifying the NOPASSWORD keyword.
  2. Ensure that RSE server has a unique OMVS uid due to the z/OS UNIX related privileges granted to this uid.
  3. RSE daemon requires a large address space size (2GB) for proper operation. You should set this value in the ASSIZEMAX variable of the OMVS segment for user ID STCRSE. This to ensure that RSE daemon will get the required region size, regardless of changes to MAXASSIZE in SYS1.PARMLIB(BPXPRMxx).
  4. RSE also requires a large number of threads for proper operation. You can set the limit in the THREADSMAX variable of the OMVS segment for user ID STCRSE. This ensures that RSE will get the required thread limit, regardless of changes to MAXTHREADS or MAXTHREADTASKS in SYS1.PARMLIB(BPXPRMxx). Refer to Tuning considerations to determine the correct value for the thread limit.
  5. User ID STCJMON is another good candidate for setting THREADSMAX in the OMVS segment, because JES Job Monitor uses a thread per client connection.

You might want to consider making the STCRSE user ID restricted. Users with the RESTRICTED attribute cannot access protected (MVS) resources they are not specifically authorized to access.

ALTUSER STCRSE RESTRICTED

To ensure that restricted users do not gain access to z/OS UNIX file system resources through the "other" permission bits, you must define the RESTRICTED.FILESYS.ACCESS profile in the UNIXPRIV class with UACC(NONE). Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on restricting user IDs.

Attention: If you use restricted user IDs, you must explicitly add the permission to access a resource with the TSO PERMIT or the z/OS UNIX setfacl commands. This includes resources where the Developer for System z documentation uses UACC (such as the ** profile in the PROGRAM class) or where it relies on common z/OS UNIX conventions (such as everyone having read and execute permission for Java libraries). Test this before activating it on a production system.

Define JES command security

JES Job Monitor issues all JES operator commands requested by a user through an extended MCS (EMCS) console, whose name is controlled with the CONSOLE_NAME directive, as documented in FEJJCNFG, JES Job Monitor configuration file.

The following sample RACF commands give Developer for System z users conditional access to a limited set of JES commands (Hold, Release, Cancel, and Purge). Users only have execution permission if they issue the commands through JES Job monitor. Replace the #console placeholder with the actual console name.

Notes:
  1. Usage of the console is permitted if no MVS.MCSOPER.#console profile is defined
  2. The CONSOLE class must be active for WHEN(CONSOLE(JMON)) to work, but there is no actual profile check in the CONSOLE class for EMCS consoles.
  3. Do not replace JMON with the actual console name in the WHEN(CONSOLE(JMON)) clause. The JMON keyword represents the point-of-entry application, not the console name.
Attention: Defining JES commands with universal access NONE in your security software might impact other applications and operations. Test this before activating it on a production system.

Table 27 and Table 28 show the operator commands issued for JES2 and JES3, and the discrete security profiles that can be used to protect them.

Table 27. JES2 Job Monitor operator commands
Action Command OPERCMDS profile Required access
Hold $Hx(jobid)

with x = {J, S or T}

jesname.MODIFYHOLD.BAT
jesname.MODIFYHOLD.STC
jesname.MODIFYHOLD.TSU
UPDATE
Release $Ax(jobid)

with x = {J, S or T}

jesname.MODIFYRELEASE.BAT
jesname.MODIFYRELEASE.STC
jesname.MODIFYRELEASE.TSU
UPDATE
Cancel $Cx(jobid)

with x = {J, S or T}

jesname.CANCEL.BAT
jesname.CANCEL.STC
jesname.CANCEL.TSU
UPDATE
Purge $Cx(jobid),P

with x = {J, S or T}

jesname.CANCEL.BAT
jesname.CANCEL.STC
jesname.CANCEL.TSU
UPDATE
Table 28. JES3 Job Monitor operator commands
Action Command OPERCMDS profile Required access
Hold *F,J=jobid,H
jesname.MODIFY.JOB
UPDATE
Release *F,J=jobid,R
jesname.MODIFY.JOB
UPDATE
Cancel *F,J=jobid,C
jesname.MODIFY.JOB
UPDATE
Purge *F,J=jobid,C
jesname.MODIFY.JOB
UPDATE
Notes:
  1. The Hold, Release, Cancel, and Purge JES operator commands, and the Show JCL command, can only be executed against spool files owned by the client user ID, unless LIMIT_COMMANDS= with value LIMITED or NOLIMIT is specified in the JES Job Monitor configuration file. Refer to Actions against jobs - target limitations for more information on this.
  2. Users can browse any spool file, unless LIMIT_VIEW=USERID is defined in the JES Job Monitor configuration file. Refer to Access to spool files for more information on this.
  3. Without being authorized for these operator commands, users will still be able to submit jobs and read job output through JES Job Monitor, if they have sufficient authority to possible profiles that protect these resources (such as those in the JESINPUT, JESJOBS and JESSPOOL classes).

Assuming the identity of the JES Job Monitor server by creating a JMON console from a TSO session is prevented by your security software. Even though the console can be created, the point of entry is different (JES Job Monitor versus TSO). JES commands issued from this console will fail the security check, if your security is set up as documented in this publication and the user does not have authority to the JES commands through other means.

Define RSE as a secure z/OS UNIX server

RSE requires UPDATE access to the BPX.SERVER profile to create/delete the security environment for the client's thread. If this profile is not defined, UID(0) is required for RSE.

Attention: Defining the BPX.SERVER profile makes z/OS UNIX as a whole switch from UNIX level security to z/OS UNIX level security, which is more secure. This might impact other z/OS UNIX applications and operations. Test this before activating it on a production system. Refer to UNIX System Services Planning (GA22-7800) for more information on the different security levels.

Define MVS program controlled libraries for RSE

Servers with authority to BPX.SERVER must run in a clean, program-controlled environment. This implies that all programs called by RSE must also be program controlled. For MVS load libraries, program control is managed by your security software.

RSE uses system (SYS1.LINKLIB), Language Environment's runtime (CEE.SCEERUN*) and ISPF's TSO/ISPF Client Gateway (ISP.SISPLOAD) load library.

Note:
Do not use the ** profile if you already have a * profile in the PROGRAM class. It obscures and complicates the search path used by your security software. In this case, you must merge the existing * and the new ** definitions. IBM recommends using the ** profile, as documented in Security Server RACF Security Administrator's Guide (SA22-7683).

The following additional (prerequisite) libraries must be made program controlled to support the use of optional services. This list does not include data sets that are specific to a product that Developer for System z interacts with, such as IBM Debug Tool.

Note:
Libraries that are designed for LPA placement also require program control authorizations if they are accessed through LINKLIST or STEPLIB. This publication documents the usage of the following LPA libraries:

Define application protection for RSE

During client logon, RSE daemon verifies that a user is allowed to use the application.

Note:

Define PassTicket support for RSE

The client's password (or other means of identification, such as an X.509 certificate) is only used to verify his identity upon connection. Afterwards, PassTickets are used to maintain thread security.

PassTickets are system-generated passwords with a lifespan of about 10 minutes. The generated PassTickets are based upon a secret key. This key is a 64 bit number (16 hex characters). Replace in the sample RACF commands below the key16 placeholder with a user-supplied 16 character hex string (characters 0-9 and A-F).

RSE supports the usage of other application IDs, such as the shared OMVSAPPL application ID. OMVSAPPL is used by z/OS UNIX itself and z/OS UNIX based processes that do not create a unique application ID. Uncomment and customize the "APPLID=OMVSAPPL" option in rsed.envvars to activate this, as documented in Defining extra Java startup parameters with _RSE_JAVAOPTS.

It is strongly advised not to use OMVSAPPL as application ID, because it will open the secret key to most z/OS UNIX applications. The same is true for the default MVS application ID; MVS followed by the system's SMF ID, as this will open the secret key to most MVS applications (including user batch jobs).

Notes:
  1. If the PTKTDATA class is already defined, verify that it is defined as a generic class before creating the profiles listed above. The support for generic characters in the PTKTDATA class is new since z/OS release 1.7, with the introduction of a Java interface to PassTickets.
  2. Substitute the wildcard (*) in the IRRPTAUTH.FEKAPPL.* definition with a valid user ID mask to limit the user IDs for which RSE can generate a PassTicket.
  3. Depending on your RACF settings, the user defining a profile may also be on the access list of the profile. It is advised that you remove this permission for the PTKTDATA profiles.
  4. JES Job Monitor and RSE must have the same application ID to allow JES Job Monitor to evaluate the PassTickets presented by RSE.
  5. If the system has a cryptographic product installed and available, you can encrypt the secured signon application key for added protection. In order to do so, use the KEYENCRYPTED keyword instead of KEYMASKED. Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on this.
Attention: The client connection request will fail if PassTickets are not set up correctly.

Define z/OS UNIX program controlled files for RSE

Servers with authority to BPX.SERVER must run in a clean, program-controlled environment. This implies that all programs called by RSE must also be program controlled. For z/OS UNIX files, program control is managed by the extattr command. To execute this command, you need READ access to BPX.FILEATTR.PROGCTL in the FACILITY class, or be UID(0).

RSE server uses RACF's Java shared library (/usr/lib/libIRRRacf.so).

Notes:
  1. Since z/OS 1.9, /usr/lib/libIRRRacf.so is installed program controlled during SMP/E RACF install.
  2. Since z/OS 1.10, /usr/lib/libIRRRacf.so is part of SAF, which ships with base z/OS, so it is available also to non-RACF customers.
  3. The setup might be different if you use a security product other than RACF. Consult the documentation of your security product for more information.
  4. The SMP/E install of Developer for System z sets the program control bit for internal RSE programs.
  5. Use the ls -Eog z/OS UNIX command to display the current status of the program control bit (the file is program controlled if the letter p shows in the second string).
    $ ls -Eog /usr/lib/libIRRRacf.so
    -rwxr-xr-x  aps-  2     69632 Oct  5  2007 /usr/lib/libIRRRacf.so                                 

Verify security settings

Use the following sample commands to display the results of your security-related customizations.

Understanding Developer for System z

The Developer for System z host consists of several components that interact to give the client access to the host services and data. Understanding the design of these components can help you make the correct configuration decisions.

Component overview

Figure 37. Component overview
Component overview

Figure 37 shows a generalized overview of the Developer for System z layout on your host system.

The description in the previous paragraph and list shows the central role assigned to RSE. With few exceptions, all client communication goes through RSE. This allows for easy security related network setup, as only a limited set of ports are used for client-host communication.

To manage the connections and workloads from the clients, RSE is composed of a daemon address space, which controls thread pooling address spaces. The daemon acts as a focal point for connection and management purposes, while the thread pools process the client workloads. Based upon the values defined in the rsed.envvars configuration file, and the amount of actual client connections, multiple thread pool address spaces can be started by the daemon.

RSE as a Java application

Figure 38. RSE as a Java application
 RSE as a Java application

Figure 38 shows a basic view of resource usage (processes and storage) by RSE.

RSE is a Java application, which means that it is active in the z/OS UNIX environment. This allows for easy porting to different host platforms and straightforward communication with the Developer for System z client, which is also a Java application (based on the Eclipse framework). Therefore, basic knowledge of how z/OS UNIX and Java work is very helpful when you try to understand Developer for System z.

In z/OS UNIX, a program runs in a process, which is identified by a PID (Process ID). Each program is active in its own process, so invoking another program creates a new process. The process that started a process is referenced with a PPID (Parent PID), the new process is called a child process. The child process can run in the same address space or it can be spawned (created) in a new address space. A new process that runs in the same address space can be compared to executing a command in TSO, while the spawning one in a new address space is similar to submitting a batch job.

Note that a process can be single- or multi-threaded. In a multi-threaded application (such as RSE), the different threads compete for system resources as were they separate address spaces (with less overhead).

Mapping this process information to the RSE sample in Figure 38, we get the following flow:

  1. When the RSED task is started, it executes BPXBATSL, which invokes z/OS UNIX and creates a shell environment - PID 50331904.
  2. In this process, the rsed.sh shell script is executed, which runs in a separate process (/bin/sh) - PID 67109114.
  3. The shell script sets the environment variables defined in rsed.envvars and executes Java with the required parameters to start the RSE daemon - PID 50331949.
  4. RSE daemon will spawn off a new shell in a child process (RSED8) - PID 307.
  5. In this shell, the environment variables defined in rsed.envvars are set and Java is executed with the required parameters to start the RSE thread pool - PID 308.

Java applications, such as RSE, do not allocate storage directly, but use Java memory management services. These services, like allocating storage, freeing storage, and garbage collection, work within the limits of the Java heap. The minimum and maximum size of the heap is defined (implicitly or explicitly) during Java startup.

This implies that getting the most out of the available address space size is a balancing act of defining a large heap size while leaving enough room for z/OS to store a variable amount of system control blocks (dependant on the number of active threads).

Connection flow

Figure 39. Connection flow
Connection flow

Figure 39 shows a schematic overview of how a client connects to the host using Developer for System z. It also briefly explains how PassTickets are used.

  1. The client logs on to the daemon (port 4035).
  2. RSE daemon authenticates the client, using the credentials presented by the client.
  3. RSE daemon selects an existing thread pool or starts a new one if all are full.
  4. RSE daemon passes the client user ID on to the thread pool.
  5. The thread pool creates a client specific RSE server thread, using the client user ID and a PassTicket for authentication.
  6. The client server thread binds to a port for future client communication.
  7. The client server thread returns the port number for the client to connect to.
  8. The client disconnects from RSE daemon and connects to the provided port number.
  9. The client server thread starts other user specific threads (miners), always using the client user ID and a PassTicket for authentication. These threads provide the user-specific services requested by the client.

The description above shows the thread-oriented design of RSE. Instead of starting an address space per user, multiple users are serviced by a single thread pool address space. Within the thread pool, each miner (a user specific service) is active in its own thread with the user's security context assigned to it, ensuring a secure setup. This design accommodates large number of users with limited resource usage, but does imply that each client will use multiple threads (16 or more, depending on the performed tasks).

From a network point of view, Developer for system z acts similar to FTP in passive mode. The client connects to a focal point (RSE daemon) and then drops the connection and reconnects to a port number provided by the focal point. The following logic controls the selection of the port that is used for the second connection:

  1. If the client specified a non-zero port number in the subsystem properties tab, then RSE server will use that port for the bind. If this port is not available, the connection fails.
  2. If _RSE_PORTRANGE is specified in rsed.envvars, then RSE server will bind to a port from this range. If no port is available, the connection fails. Note that RSE server does not need the port exclusively for the duration of the client connection. It is only in the time span between the (server) bind and the (client) connect that no other RSE server can bind to the port.
  3. If no limitations are set, RSE server will bind to port 0. The result is that TCP/IP chooses the port number.

The usage of PassTickets for all z/OS services that require authentication allows Developer for System z to invoke these services at will without storing the password or constantly prompting the user for it. Use of PassTickets for all z/OS services also allows for alternative authentication methods during logon, such as one-time passwords and X.509 certificates.

Lock daemon

Figure 40. Lock daemon flow
Lock daemon flow

Figure 40 shows a schematic overview of how the lock daemon determines which Developer for System z client owns a data set lock.

  1. The client logs on, which creates a user-specific RSE server thread (USER) inside a thread pool (RSEDx).
  2. RSE server registers a newly-connected user with the lock daemon. The registration information contains the Address Space Identifier (which is the ASID of the thread pool), the Task Control Block (TCB) identifier (user-specific), and the user ID.
  3. The client opens a data set in edit, which instructs RSE server to get an exclusive lock on the data set.
  4. The system registers the ASID, TCB and task name (RSEDx) of the requestor as part of lock process. This information is stored in the Global Resource Serialization (GRS) queues.
  5. An operator (or RSE server on behalf of a client) queries the lock daemon for the lock status of the data set.
  6. The lock daemon scans the GRS queues to learn if the data set is locked.
  7. The daemon retrieves the ASID, TCB and task name of the lock owner.
  8. The retrieved ASID and TCB are compared against the ASID and TCB combos of registered clients.
  9. The related client user ID is returned to the requestor when a match is found. Otherwise, the task name retrieved from GRS is returned.

With the single-server setup of Developer for System z, where multiple users are assigned to a single thread pool address space, z/OS lost the ability to track who owns a lock on a data set or member. System commands stop at address space level, which is the thread pool.

To address this problem, Developer for System z provides the lock daemon. The lock daemon can track all dataset/member locks done by RSE users, as well as locks done by other products, such as ISPF.

RSE server registers a newly-connected user with the lock daemon. The registration information contains the Address Space Identifier (which is the ASID of the thread pool), the Task Control Block (TCB) ID (user-specific), and the user ID.

Note that registration is done at connect time only, so all RSE users active before the lock daemon was started (or restarted) will not be registered.

When the lock daemon receives a dataset query (by means of a modify query operator command or from the client by way of RSE server), the daemon scans the system's Global Resource Serialization (GRS) queues. If the ASID and TCB match that of a registered user, the user ID is returned as lock owner. Otherwise the jobname/user ID related to the ASID is returned as lock owner.

A console message (FEK513W) with the registration information is displayed if the registration fails. This allows an operator to match the values against the output of a DISPLAY GRS,RES=(*,dataset*) operator command in order to find the lock owner.

Note:
Successful registrations are also listed in DD STDOUT of the server if log_level is set to 2. This is useful to do the manual mapping for successful registrations that were removed after a restart of the lock daemon.

Freeing a lock

Under normal circumstances, a data set or member is locked when the client opens it in edit mode, and freed when the client closes the edit session.

Certain error conditions can prevent this mechanism from working as designed. In this case, the user holding the lock can be canceled using RSE's modify cancel operator command, as described in Operator commands. Active data set locks belonging to this user are freed during the process.

z/OS UNIX directory structure

Figure 41. z/OS UNIX directory structure
z/OS UNIX directory structure

Figure 41 shows an overview of the z/OS UNIX directories used by Developer for System z.

The list above shows an overview of the directories touched by Developer for System z, how their location can be changed, and who maintains the data within.

Update privileges for non-system administrators

The data in some directories, such as /var/rdz/projects/, is maintained by non-system administrators, such as project managers, who might not have many update privileges in z/OS UNIX. If there is just one user ID maintaining the files, there is not a problem after the user ID has been made owner of the directory and everything in the directory.

chown -R IBMUSER /var/rdz/projects/

When multiple user IDs need update permission to the directory, you can work with the group-permission bits.

  1. Create a group in your security software that has a valid OMVS segment and connect all user ID's that require update access. This is preferably their default group.
    ADDGROUP RDZPROJ OMVS(GID(1200))
    CONNECT IBMUSER GROUP(RDZPROJ)
    ALTUSER IBMUSER DFLTGRP(RDZPROJ)
  2. Use the z/OS UNIX chgrp command to assign the group to the directory and all files within. This command must be repeated each time a new file is added and the desired group ID is not the default group for the user ID who added the file.
    chgrp -R IBMUSER /var/rdz/projects/
  3. Use the z/OS UNIX chmod command to give the whole group update permission to the directory and all files within.
    chmod -R 775 /var/rdz/projects/

Tuning considerations

As explained in Understanding Developer for System z, RSE (Remote Systems Explorer) is the core of Developer for System z. To manage the connections and workloads from the clients, RSE is composed of a daemon address space, which controls thread pooling address spaces. The daemon acts as a focal point for connection and management purposes, while the thread pools process the client workloads.

This makes RSE a prime target for tuning the Developer for System z setup. However, maintaining hundreds of users, each using 16 or more threads, a certain amount of storage, and possibly 1 or more address spaces requires proper configuration of both Developer for System z and z/OS.

The following topics are covered in this chapter:

Resource usage

Use the information in this section to estimate the normal and maximum resource usage by Developer for System z, so you can plan your system configuration accordingly.

When you use the numbers and formulas presented in this section to define the values for system limits, be aware that you are working with fairly accurate estimates. Leave enough margin when setting the system limits to allow resource usage by temporary and other tasks, or by users connecting multiple times to the host simultaneously. (For example, by way of RSE and TN3270).

Note:

Overview

The following tables give an overview of the number of address spaces, processes, and threads used by Developer for System z. More details on the numbers presented here can be found in the next sections:

Table 29 gives a general overview of the key resources used by the Developer for System z started tasks. These resources are allocated only once. They are shared among all Developer for System z clients.

Table 29. Common resource usage
Started task Address spaces Processes Threads
JMON 1 1 3
LOCKD 1 3 10
RSED 1 3 11
RSEDx (a) 2 10
Note:
(a) There is at least 1 RSE thread pool address space active. Refer to Address space count to determine the actual number of RSE thread pool address spaces.

Table 30 gives a general overview of the key resources used by requisite software. These resources are allocated for each Developer for System z client that invokes the related function.

Table 30. User-specific requisite resource usage
Requisite® software Address spaces Processes Threads
ISPF Client Gateway 1 2 4
APPC 1 1 2
File Manager 1 1 2

Table 31 gives a general overview of the key resources used by each Developer for System z client when executing the specified function. Non-numeric values, such as ISPF, are a reference to the corresponding value in Table 30.

Table 31. User-specific resource usage
User action

Address spaces
User ID
Processes
User ID
                Threads

  User ID      RSEDx         JMON
Logon - - - 16 1
Timer for idle timeout - - - 1 -
Expand PDS(E) ISPF ISPF ISPF - -
Open data set ISPF ISPF ISPF - -
TSO command ISPF ISPF ISPF - -
z/OS UNIX shell 1 1 1 6 -
MVS build 1 - - - -
z/OS UNIX build 3 3 3 - -
CARMA (batch) 1 1 2 1 -
CARMA (crastart) 1 1 2 4 -
CARMA (ispf) 4 4 7 5 -
SCLMDT ISPF ISPF ISPF - -
File Manager Integration ISPF + FM ISPF + FM ISPF + FM - -
Fault Analyzer Integration - - - - -
Note:
ISPF can be substituted by APPC, except for SCLM Developer Toolkit.

Address space count

Table 32 lists the address spaces that are used by Developer for System z, where "u" in the "Count" column indicates that the amount must be multiplied by the number of concurrently active users using the function. z/OS UNIX will substitute "x" in the "Task Name" column by a random 1-digit number.

Table 32. Address space count
Count Description Task name Shared Ends after
1 JES Job Monitor JMON Yes Never
1 Lock daemon LOCKD Yes Never
1 RSE daemon RSED Yes Never
(a) RSE thread pool RSEDx Yes Never
lu ISPF Client Gateway (TSO Commands service and SCLMDT) <userid>x No 15 minutes or user logoff
lu TSO Commands service (APPC) FEKFRSRV No 60 minutes
lu CARMA (batch) CRA<port> No 7 minutes or user logoff
lu CARMA (crastart) <userid>x No 7 minutes or user logoff
4u CARMA (ispf) (1)<userid> or (3)<userid>x No 7 minutes or user logoff
(b) Simultaneous ISPF Client Gateway usage by 1 user <userid>x No Task completion
1u MVS build (batch job) * No Task completion
3u z/OS UNIX build (shell commands) <userid>x No Task completion
1u z/OS UNIX shell <userid> No User logoff
(c) File Manager <userid>x No Task completion

Note:

Use the formula in Figure 42 to estimate the maximum number of address spaces used by Developer for System z.

Figure 42. Maximum number of address spaces
Maximum number of address spaces

Where

Use the formula in Figure 43 to estimate the maximum number of address spaces used by a Developer for System z client (not counting the undocumented temporary address spaces).

Figure 43. Number of address spaces per client
Number of address spaces per client

Where

The definitions in Table 33 can limit the actual number of address spaces.

Table 33. Address space limits
Location Limit Affected resources
rsed.envvars maximum.threadpool.process Limits the number of RSE thread pools
IEASYMxx MAXUSER Limits the number of address spaces
ASCHPMxx MAX Limits the number of APPC initiators for TSO Commands service (APPC)

Process count

Table 34 lists the number of processes per address space that is used by Developer for System z. "u" In the "Address Spaces" column indicates that the amount must be multiplied by the number of concurrently active users using the function.

Table 34. Process count
Processes Address spaces Description User ID
1 1 JES Job Monitor STCJMON
3 1 Lock daemon STCLOCK
3 1 RSE daemon STCRSE
2 (a) RSE thread pool STCRSE
2 (b) ISPF Client Gateway (TSO Commands service and SCLMDT) <userid>
1 1u TSO Commands service (APPC) <userid>
1 1u CARMA (batch) <userid>
1 1u CARMA (crastart) <userid>
1 1u CARMA (ispf) <userid>
1 3u z/OS UNIX build (shell commands) <userid>
1 1u z/OS UNIX shell <userid>
1 (c) File Manager <userid>
(5) (u) SCLM Developer Toolkit <userid>

Note:

Use the formula in Figure 44 to estimate the maximum number of processes used by Developer for System z.

Figure 44. Maximum number of processes
Maximum number of processes

Where

Use the formula in Figure 45 to estimate the maximum number of processes used by a Developer for System z client (not counting the undocumented temporary processes).

Figure 45. Number of processes per client

Where

The definitions in Table 35 can limit the actual number of processes.

Table 35. Process limits
Location Limit Affected resources
BPXPRMxx MAXPROCSYS Limits the total number of processes
BPXPRMxx MAXPROCUSER Limits the number of processes per z/OS UNIX UID

Note:

Thread count

Table 36 lists the number of threads used by selected Developer for System z functions. "u" In the "Threads" columns indicates that the amount must be multiplied by the number of concurrently active users using the function. The thread count is listed per process, as limits are set at this level.

Table 36. Thread count
              Threads
User ID Description
RSEDx Active Bootstrap
- 3 + 1u - STCJMON JES Job Monitor
- 10 2 STCLOCK Lock daemon
- 11 2 STCRSE RSE daemon
10 (a) + 16u - 1 (a) STCRSE RSE thread pool
- 4u (b) 1u (b) <userid> ISPF Client Gateway (TSO Commands service and SCLMDT)
- 2u - <userid> TSO Commands service (APPC)
1u 2u - STCRSE and <userid> CARMA (batch)
4u 2u - STCRSE and <userid> CARMA (crastart)
5u 4u 3u STCRSE and <userid> CARMA (ispf)
- 1u (d) 2u <userid> z/OS UNIX build (shell commands)
6u 1u - STCRSE and <userid> z/OS UNIX shell
- 2u (c) - <userid> File Manager
- (5) - <userid> SCLM Developer Toolkit
1u - - STCRSE Timer for idle timeout
Note:

Use the formula in Figure 46 to estimate the maximum number of threads used by a RSE thread pool. Use the formula in Figure 47 to estimate the maximum number of threads used by JES Job Monitor.

Figure 46. Maximum number of RSE thread pool threads
Maximum number of threads
Figure 47. Maximum number of JES Job Monitor threads
Maximum number of JES Job Monitor threads

Where

The definitions in Table 37 can limit the actual number of threads in a process, which is mostly of importance for the RSE thread pools.

Table 37. Thread limits
Location Limit Affected resources
BPXPRMxx MAXTHREADS Limits the number of threads in a process.
BPXPRMxx MAXTHREADTASKS Limits the number of MVS tasks in a process.
BPXPRMxx MAXASSIZE Limits the address space size, and thus the storage available for thread related control blocks.
rsed.envvars Xmx Sets the maximum Java heap size. This storage is reserved and thus no longer available for thread related control blocks.
rsed.envvars maximum.clients Limits the number of clients (and thus their threads) in an RSE thread pool.
rsed.envvars maximum.threads Limits the number of client threads in a RSE thread pool.
FEJJCNFG MAX_THREADS Limits the number of threads in JES Job Monitor.
Note:
The value for maximum.threads in rsed.envvars must be lower than the value for MAXTHREADS and MAXTHREADTASKS in BPXPRMxx.

Storage usage

RSE is a Java application, which implies that storage (memory) usage planning for Developer for System z must take two storage allocation limits into consideration, Java heap size and Address Space size.

Java heap size limit

Java offers many services to ease coding efforts for Java applications. One of these services is storage management.

Java's storage management allocates large blocks of storage and uses these for storage requests by the application. This storage managed by Java is called the Java heap. Periodic garbage collection (defragmentation) reclaims unused space in the heap and reduces its size.

The maximum Java heap size is defined in rsed.envvars with the Xmx directive. If this directive is not specified, Java uses a default size of 64 MB.

Each RSE thread pool (which services the client actions) is a separate Java application, and thus has a personal Java heap. Note that all thread pools use the same rsed.envvars configuration file, and thus have the same Java heap size limit.

The thread pool's usage of the Java heap depends heavily on the actions done by the connected clients. Regular monitoring of the heap usage is required to set the optimal heap size limit. Use the modify display process operator command to monitor the Java heap usage by RSE thread pools.

Address space size limit

All z/OS applications, including Java applications, are active within an address space, and are thus bound by address space size limitations.

The desired address space size is specified during startup, for example with the REGION parameter in JCL. However, system settings can limit the actual address space size. Refer to Address Space size to learn more about these limits.

RSE thread pools inherit the address space size limits from RSE daemon. The address space size must be sufficient to house the Java heap, Java itself, common storage areas, and all control blocks the system creates to support the thread pool activity, such as a TCB (Task Control Block) per thread. Note that some of this storage usage is below the 16 MB line.

You should monitor the actual address space size before changing any settings that influence it, like changing the size of the Java heap or the amount of users supported by a single thread pool. Use your regular system monitoring software to track the actual storage usage by Developer for system z. If you do not have a dedicated monitoring tool, then basic information can be gathered with tools like the SDSF DA view or TASID (an as-is system information tool available via the ISPF "Support and downloads" webpage).

Size estimate guidelines

As stated before, the actual storage usage by Developer for system z is heavily influenced by user activity. Some actions use a fixed amount of storage (for example, logon), while others are variable (for example, listing data sets with a specified high level qualifier).

Note that RSE displays the current Java heap and address space size limit during startup in console message FEK004I.

Use either of the following scenarios if monitoring shows that the current Java heap size is insufficient for the actual workload:

Sample storage usage analysis

The displays in the following figures show some sample resource usage numbers for a default Developer for system z setup with one modification. The maximum Java heap size is set to 10 MB, as a small maximum will result in a bigger percentile usage and the heap size limits will be reached sooner.

Figure 48. Resource usage with 5 logons
Max Heap Size=10MB and private AS Size=1,959MB

startup

 BPXM023I (STCRSE)
 ProcessId(268     ) Memory Usage(7%) Clients(0)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.01      2740           72
 LOCKD             1.60     28.7M        14183
 RSED              4.47     32.8M        15910
 RSED8             1.15     27.4M        12612

logon 1

 BPXM023I (STCRSE)
 ProcessId(268     ) Memory Usage(13%) Clients(1)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.01      2864           81
 LOCKD             1.64     28.8M        14259
 RSED              4.55     32.8M        15980
 RSED8             3.72     55.9M        24128

logon 2

 BPXM023I (STCRSE)
 ProcessId(268     ) Memory Usage(23%) Clients(2)

 Jobname     Cpu time      Storage     EXCP
--------   -----------    -------  ----------
 JMON              0.02      2944           86
 LOCKD             1.66     28.9M        14268
 RSED              4.58     32.9M        16027
 RSED8             4.20     57.8M        25205

logon 3

 BPXM023I (STCRSE)
 ProcessId(268     ) Memory Usage(37%) Clients(3)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.02      3020           91
 LOCKD             1.67     29.0M        14277
 RSED              4.60     32.9M        16076
 RSED8             4.51     59.6M        26327

logon 4

 BPXM023I (STCRSE)
 ProcessId(268     ) Memory Usage(41%) Clients(4)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.02      3108           96
 LOCKD             1.68     29.0M        14286
 RSED              4.61     32.9M        16125
 RSED8             4.77     62.3M        27404
Figure 49. Resource usage with 5 logons (continued)
logon 5

 BPXM023I (STCRSE)
 ProcessId(268     ) Memory Usage(41%) Clients(4)
 ProcessId(33554706) Memory Usage(13%) Clients(1)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.03      3184          101
 LOCKD             1.69     29.1M        14295
 RSED              4.64     32.9M        16229
 RSED8             4.78     62.4M        27413
 RSED9             4.60     56.6M        24065

Figure 48 and Figure 49 show a scenario where 5 clients log on to an RSE daemon with a 10 MB Java heap.

Figure 50. Resource usage while editing a PDS member
Max Heap Size=10MB and private AS Size=1,959MB

startup

 BPXM023I (STCRSE)
 ProcessId(212     ) Memory Usage(7%) Clients(0)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.01      2736           71
 LOCKD             1.73     30.5M        14179
 RSED              4.35     32.9M        15117
 RSED8             1.43     27.4M        12609

logon

 BPXM023I (STCRSE)
 ProcessId(212     ) Memory Usage(13%) Clients(1)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.01      2864           80
 LOCKD             1.76     30.6M        14255
 RSED              4.48     33.0M        15187
 RSED8             3.53     53.9M        24125

expand large MVS tree (195 data sets)
 BPXM023I (STCRSE)
 ProcessId(212     ) Memory Usage(13%) Clients(1)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 JMON              0.01      2864           80
 LOCKD             1.78     30.6M        14255
 RSED              4.58     33.1M        16094
 RSED8             4.28     56.1M        24740

expand small PDS (21 members)
 BPXM023I (STCRSE)
 ProcessId(212     ) Memory Usage(13%) Clients(1)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 IBMUSER2          0.22      2644          870
 JMON              0.01      2864           80
 LOCKD             1.78     30.6M        14255
 RSED              4.61     33.1M        16108
 RSED8             4.40     56.2M        24937

open medium sized member (86 lines)

 BPXM023I (STCRSE)
 ProcessId(212     ) Memory Usage(13%) Clients(1)

 Jobname     Cpu time      Storage     EXCP
 --------   -----------    -------  ----------
 IBMUSER2          0.22      2644          870
 JMON              0.01      2864           80
 RSED              4.61     33.1M        16108
 RSED8             8.12     62.7M        27044

Figure 50 shows a scenario where 1 client logs on to an RSE daemon with a 10 MB Java heap and edits a PDS member.

z/OS UNIX file system space usage

Most of the Developer for System z related data that is not written to a DD statement ends up in a z/OS UNIX file. The system programmer has control over which data is written and where it goes. However, there is no control over the amount of data written.

The data can be grouped in the following categories:

As documented in Troubleshooting configuration problems, Developer for System z writes the RSE-related host logs to the following z/OS UNIX directories:

By default, only error and warning messages are written to the logs. So if all goes as planned, these directories should hold only empty or nearly-empty files (not counting audit logs).

You can enable logging of informational messages, preferably under direction of the IBM support center, which increases the size of log files noticeably.

Figure 51. z/OS UNIX file system space usage
startup

$ ls -l /var/rdz/logs
total 144
-rw-rw-rw-   1 STCRSE   STCGRP     33642 Jul 10 12:10 rsedaemon.log
-rw-rw-rw-   1 STCRSE   STCGRP      1442 Jul 10 12:10 rseserver.log

logon

$ ls -l /var/rdz/logs
total 144
drwxrwxrwx   3 IBMUSER  SYS1        8192 Jul 10 12:11 IBMUSER
-rw-rw-rw-   1 STCRSE   STCGRP     36655 Jul 10 12:11 rsedaemon.log
-rw-rw-rw-   1 STCRSE   STCGRP      1893 Jul 10 12:11 rseserver.log
$ ls -l /var/rdz/logs/IBMUSER
total 160
-rw-rw-rw-   1 IBMUSER  SYS1        3459 Jul 10 12:11 ffs.log
-rw-rw-rw-   1 IBMUSER  SYS1           0 Jul 10 12:11 ffsget.log
-rw-rw-rw-   1 IBMUSER  SYS1           0 Jul 10 12:11 ffsput.log
-rw-rw-rw-   1 IBMUSER  SYS1         303 Jul 10 12:11 lock.log
-rw-rw-rw-   1 IBMUSER  SYS1         126 Jul 10 12:11 rmt_classloader_cache.jar
-rw-rw-rw-   1 IBMUSER  SYS1        7266 Jul 10 12:11 rsecomm.log
-rw-rw-rw-   1 IBMUSER  SYS1           0 Jul 10 12:11 stderr.log
-rw-rw-rw-   1 IBMUSER  SYS1           0 Jul 10 12:11 stdout.log

logoff
$ ls -l /var/rdz/logs
total 80
drwxrwxrwx   3 IBMUSER  SYS1        8192 Jul 10 12:11 IBMUSER
-rw-rw-rw-   1 STCRSE   STCGRP     36655 Jul 10 12:11 rsedaemon.log
-rw-rw-rw-   1 STCRSE   STCGRP      2208 Jul 10 12:11 rseserver.log
$ ls -l /var/rdz/logs/IBMUSER
total 296
-rw-rw-rw-   1 IBMUSER  SYS1        6393 Jul 10 12:11 ffs.log
-rw-rw-rw-   1 IBMUSER  SYS1           0 Jul 10 12:11 ffsget.log
-rw-rw-rw-   1 IBMUSER  SYS1           0 Jul 10 12:11 ffsput.log
-rw-rw-rw-   1 IBMUSER  SYS1         609 Jul 10 12:11 lock.log
-rw-rw-rw-   1 IBMUSER  SYS1         126 Jul 10 12:11 rmt_classloader_cache.jar
-rw-rw-rw-   1 IBMUSER  SYS1       45157 Jul 10 12:11 rsecomm.log
-rw-rw-rw-   1 IBMUSER  SYS1           0 Jul 10 12:11 stderr.log
-rw-rw-rw-   1 IBMUSER  SYS1         176 Jul 10 12:11 stdout.log

stop

$ ls -l /var/rdz/logs
total 80
drwxrwxrwx   3 IBMUSER  SYS1        8192 Jul 10 12:11 IBMUSER
-rw-rw-rw-   1 STCRSE   STCGRP     36655 Jul 10 12:11 rsedaemon.log
-rw-rw-rw-   1 STCRSE   STCGRP      2490 Jul 10 12:12 rseserver.log

Figure 51 shows the minimal z/OS UNIX file system space usage when using debug level 2 (informational messages).

Except for audit logs, log files are overwritten on every restart (for the RSE started task) or logon (for a client), keeping the total size in check. The keep.last.log directive in rsed.envvars changes this slightly, as it can instruct RSE to keep a copy of the previous logs. Older copies are always removed.

A warning message is sent to the console when the file system holding the audit log files is running low on free space and auditing is active. This console message (FEK103E) is repeated regularly until the low space issue is resolved. Refer to Console messages for a list of console messages generated by RSE.

The definitions in Table 38 control which data is written to the log directories, and where the directories are located.

Table 38. Log output directives
Location Directive Function
resecomm.properties debug_level Set the default log detail level.
rsed.envvars keep.last.log Keep a copy of the previous logs before startup/logon.
rsed.envvars enable.audit.log Keep an audit trace of client actions.
rsed.envvars enable.standard.log Write the stdout and stderr streams of the thread pool (or pools) to a log file.
rsed.envvars DSTORE_TRACING_ON Enable DataStore action logging.
rsed.envvars DSTORE_MEMLOGGING_ON Enable DataStore memory usage logging.
Operator command modify rsecommlog <level> Dynamically change the log detail level of rsecomm.log
Operator command modify rsedaemonlog <level> Dynamically change the log detail level of rsedaemon.log
Operator command modify rseserverlog <level> Dynamically change the log detail level of rseserver.log
Operator command modify rsestandardlog {on|off} Dynamically change the updating of std*.*.log
rsed.envvars daemon.log Home path for RSE started task and audit logs.
rsed.envvars user.log Home path for user logs.

Developer for System z, together with requisite software such as the ISPF Client Gateway, also writes temporary data to /tmp and /var/rdz/WORKAREA. The amount of data written here as a result of user actions is unpredictable, so you should have ample free space in the file systems holding these directories.

Developer for system z always tries to clean up these temporary files, but manual cleanup, as documented in (Optional) WORKAREA cleanup, can be performed at virtually any time.

Key resource definitions

/etc/rdz/rsed.envvars

The environment variables defined in rsed.envvars are used by RSE, Java, and z/OS UNIX. The sample file that comes with Developer for System z is targeted at small to medium sized installations that do not require the optional components of Developer for System z. rsed.envvars, RSE configuration file describes each variable that is defined in the sample file, where the following variables require special attention:

_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xms128m -Xmx256m"
Set initial (Xms) and maximum (Xmx) heap size. The defaults are 128M and 256M respectively. Change to enforce the desired heap size values. If this directive is commented out, the Java default values will be used, which are 1M and 64M respectively.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.clients=60"
Maximum amount of clients serviced by one thread pool. The default is 60. Uncomment and customize to limit the number of clients per thread pool. Note that other limits may prevent RSE from reaching this limit.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.threads=1000"
Maximum amount of threads serviced by one thread pool. The default is 1000. Uncomment and customize to limit the number of threads per thread pool. Note that each client connection uses multiple threads (16 or more) and that other limits may prevent RSE from reaching this limit.
Note:
This value must be lower than the setting for MAXTHREADS and MAXTHREADTASKS in SYS1.PARMLIB(BPXPRMxx).
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dminimum.threadpool.process=10"
The minimum number of active thread pools. The default is 1. Uncomment and customize to start at least the listed number of thread pool processes. Thread pool processes are used for load balancing the RSE server threads. More new processes are started when they are needed. Starting the new processes up front helps prevent connection delays but uses more resources during idle times.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dmaximum.threadpool.process=100"
The maximum number of active thread pools. The default is 100. Uncomment and customize to limit the number of thread pool processes. Thread pool processes are used for load balancing the RSE server threads, so limiting them will limit the amount of active client connections.

SYS1.PARMLIB(BPXPRMxx)

RSE is a Java application, which means that it is active in the z/OS UNIX environment. This promotes BPXPRMxx to become a crucial parmlib member, as it contains the parameters that control the z/OS UNIX environment and file systems. BPXPRMxx is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:

MAXPROCSYS(nnnnn)
Specifies the maximum number of processes that the system allows.

Value Range: nnnnn is a decimal value from 5 to 32767.
Default: 900
MAXPROCUSER(nnnnn)
Specifies the maximum number of processes that a single z/OS UNIX user ID can have concurrently active, regardless of how the processes were created.

Value Range: nnnnn is a decimal value from 3 to 32767.
Default: 25
Note:
  • All RSE processes use the same z/OS UNIX user ID (that of the user who is assigned to RSE daemon), because all clients run as threads within the RSE processes.
  • This value can also be set with the PROCUSERMAX variable in the OMVS security profile segment of the user assigned to the RSED started task.
MAXTHREADS(nnnnnn)
Specifies the maximum number of pthread_created threads, including running, queued, and exited but undetached, that a single process can have concurrently active. Specifying a value of 0 prevents applications from using pthread_create.

Value Range: nnnnnn is a decimal value from 0 to 100000.
Default: 200
Note:
  • Each client uses at least 16 threads within the RSE thread pool process, and multiple clients are active within the process.
  • This value can also be set with the THREADSMAX variable in the OMVS security profile segment of the user assigned to the RSED started task. When set, the THREADSMAX value is used for both MAXTHREADS and MAXTHREADTASKS.
MAXTHREADTASKS(nnnnn)
Specifies the maximum number of MVS tasks that a single process can have concurrently active for pthread_created threads.

Value Range: nnnnn is a decimal value from 0 to 32768.
Default: 1000
Note:
  • Each active thread has an MVS task (TCB, Task Control Block).
  • Each concurrent MVS task requires additional storage, some of which must be below the 16MB line.
  • Each client uses at least 16 threads within the RSE thread pool process, and multiple clients are active within the process.
  • This value can also be set with the THREADSMAX variable in the OMVS security profile segment of the user assigned to the RSED started task. When set, the THREADSMAX value is used for both MAXTHREADS and MAXTHREADTASKS.
MAXUIDS(nnnnn)
Specifies the maximum number of z/OS UNIX user IDs (UIDs) that can operate concurrently.

Value Range: nnnnn is a decimal value from 1 to 32767.
Default: 200
MAXASSIZE(nnnnn)
Specifies the RLIMIT_AS resource values that will be established as the initial values for new processes. RLIMIT_AS indicates the address space region size.

Value Range: nnnnn is a decimal value from 10485760 (10 Megabytes)
                     to 2147483647 (2 Gigabytes).
Default: 209715200 (200 Megabytes)
Note:
  • This value should be set to 2G.
  • This value can also be set with the ASSIZEMAX variable in the OMVS security profile segment of the user assigned to the RSED started task.
MAXFILEPROC(nnnnnn)
Specifies the maximum number of descriptors for files, sockets, directories, and any other file system objects that a single process can have concurrently active or allocated.

Value Range: nnnnnn is a decimal value from 3 to 524287.
Default: 64000
Note:
  • A thread pool has all his client threads in a single process.
  • This value can also be set with the FILEPROCMAX variable in the OMVS security profile segment of the user assigned to the RSED started task.
MAXMMAPAREA(nnnnn)
Specifies the maximum amount of data space storage space (in pages) that can be allocated for memory mappings of z/OS UNIX files. Storage is not allocated until the memory mapping is active.

Value Range: nnnnn is a decimal value from 1 to 16777216.
Default: 40960
Note:
This value can also be set with the MMAPAREAMAX variable in the OMVS security profile segment of the user assigned to the RSED started task.

Use the SETOMVS or SET OMVS operator command to dynamically (until next IPL) increase or decrease the value of any of the previous BPXPRMxx variables. To make a permanent change, edit the BPXPRMxx member that will be used for IPLs. Refer to MVS System Commands (SA22-7627) for more information on these operator commands.

The following definitions are sub-parameters of the NETWORK statement.

MAXSOCKETS(nnnnnnnn)
Specifies the maximum number of sockets supported by this file system for this address family. This is an optional parameter.

Value Range: nnnnnnnn is a decimal value from 0 to 16777215.
Default: 100
INADDRANYCOUNT(nnnn)
Specifies the number of ports that the system reserves for use with PORT 0, INADDR_ANY binds, starting with the port number specified in the INADDRANYPORT parameter. This value is only needed for CINET (multiple TCP/IP stacks).

Value Range: nnnn is a decimal value from 1 to 4000.
Default: If neither INADDRANYPORT or INADDRANYCOUNT
             is specified, the default for INADDRANYCOUNT is 1000.  
             Otherwise, no ports are reserved (0).

Various resource definitions

EXEC card in the server JCL

The following definitions are recommended to be added to the EXEC card in the JCL of the Developer for System z servers.

REGION=0M
REGION=0M is recommended for the RSE daemon and JES Job Monitor started tasks, RSED and JMON respectively. By doing so, the address space size is limited only by the available private storage, or by the IEFUSI or IEALIMIT system exits. Note that IBM strongly recommends not to use these exits for z/OS UNIX address spaces, like RSE daemon.
TIME=NOLIMIT
TIME=NOLIMIT is recommended to be used for all Developer for System z servers. This because the CPU time of all Developer for System z clients accumulates in the server address spaces.

FEK.#CUST.PARMLIB(FEJJCNFG)

The environment variables defined in FEJJCNFG are used by JES Job Monitor. The sample file that comes with Developer for System z is targeted at small to medium sized installations. FEJJCNFG, JES Job Monitor configuration file describes each variable that is defined in the sample file, where the following variables require special attention:

MAX_THREADS
Maximum number of users that can be using one JES Job Monitor at a time. The default is 200. The maximum value is 2147483647. Increasing this number may require you to increase the size of the JES Job Monitor address space.

SYS1.PARMLIB(IEASYSxx)

IEASYSxx holds system parameters and is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:

MAXUSER=nnnnn
This parameter specifies a value that, under most conditions, the system uses to limit the number of jobs and started tasks that can run concurrently during a given IPL.

Value Range: nnnnn is a decimal value from 0-32767. Note that the
           sum of the values specified for the MAXUSER, RSVSTRT,
           and RSVNONR system parameters cannot exceed 32767.
Default Value: 255

SYS1.PARMLIB(IVTPRMxx)

IVTPRMxx sets parameters for the Communication Storage Manager (CSM), and is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:

FIXED MAX(maxfix)
Defines the maximum amount of storage dedicated to fixed CSM buffers.

Value Range:  maxfix is a value from 1024K to 2048M.
Default: 100M
ECSA MAX(maxecsa)
Defines the maximum amount of storage dedicated to ECSA CSM buffers.

Value Range:  maxecsa is a value from 1024K to 2048M.
Default: 100M

SYS1.PARMLIB(ASCHPMxx)

The ASCHPMxx parmlib member contains scheduling information for the ASCH transaction scheduler, and is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:

MAX(nnnnn)
An optional parameter of the CLASSADD definition that specifies the maximum number of APPC transaction initiators that are allowed for a particular class of transaction initiators. After this limit is reached, no new address spaces are created and incoming requests are queued to wait until existing initiator address spaces become available. The value should not exceed the maximum number of address spaces allowed by your installation, and you should be aware of competing products on the system that will also require address spaces.

Value Range:  nnnnn is a decimal value from 1 to 64000.
Default: 1
Note:
If you use APPC to start the TSO Commands service, then the transaction class used must have enough transaction initiators to allow one initiator for each concurrent user of Developer for System z.

Monitoring

Since user workloads can change the need for system resources, the system should be monitored regularly to measure resource usage so that Rational Developer for System z and system configurations can be adjusted in response to user requirements. The following commands can be used to aid in this monitoring process.

Monitoring RSE

RSE thread pools are the focal point for user activity in Developer for System z, and thus require monitoring for optimal use. RSE daemon can be queried for information that cannot be gathered with regular system monitoring tools.

Monitoring z/OS UNIX

Most z/OS UNIX limits that are of interest for Developer for System z can be displayed using operator commands. Some commands even show the current usage and the high-water mark for a specific limit. Refer to MVS System Commands (SA22-7627) for more information on these commands.

Monitoring the network

When supporting a large number of clients connecting to the host, then not only Developer for System z, but also your network infrastructure must be able to handle the workload. Network management is a broad and well documented subject that falls out of the scope of Developer for System z documentation. Therefore, only the following pointers are provided.

Monitoring z/OS UNIX file systems

Developer for System z uses z/OS UNIX file systems to store various types of data, such as logs and temporary files. Use the z/OS UNIX df command to see how many file descriptors are still available and how much free space is left before the next extent of the underlying HFS or zFS data set.

$ df
Mounted on    Filesystem         Avail/Total    Files      Status
/tmp          (OMVS.TMP)         1393432/1396800 4294967248 Available
/u/ibmuser    (OMVS.U.IBMUSER)   1248/1728      4294967281 Available
/usr/lpp/rdz  (OMVS.FEK.HHOP760) 3062/43200     4294967147 Available
/var          (OMVS.VAR)         27264/31680    4294967054 Available

Sample setup

The following sample setup shows the required configuration to support these requirements:

Thread pool count

By default, Developer for system z tries to add 60 users to a single thread pool. However, our requirements indicate that the inactivity time-out will be active. Table 36 shows that this will add 1 thread per connected client. This thread is a timer thread, and thus constantly active. This will prevent RSE from putting 60 users in a single thread pool, as 60*(16+1)=1020, and maximum.threads is set to 1000 by default.

We could increase maximum.threads, but due to the requirement to have on average 5 MB of Java heap per user, we choose to lower maximum.clients to 50. This keeps us within the default 256 MB maximum Java heap size (5*50 = 250).

With 50 clients per thread pool and the need to support 500 connections, we now know we will need 10 thread pool address spaces.

Determine minimum limits

Using the formulas shown earlier in this chapter and the criteria stated at the beginning of this section, we can determine the resource usage that must be accommodated.

Defining limits

Now that the resource usage numbers are known, we can customize the limiting directives with appropriate values.

Performance considerations

z/OS is a highly customizable operating system, and (sometimes small) system changes can have a huge impact on the overall performance. This chapter highlights some of the changes that can be made to improve the performance of Developer for System z.

Refer to the MVS Initialization and Tuning Guide (SA22-7591) and UNIX System Services Planning (GA22-7800) for more information on system tuning.

Use zFS file systems

zFS (zSeries® File System) and HFS (Hierarchical File System) are both UNIX file systems that can be used in a z/OS UNIX environment. However, zFS provides the following features and benefits:

Refer to UNIX System Services Planning (GA22-7800) to learn more about zFS.

Avoid use of STEPLIB

Each z/OS UNIX process that has a STEPLIB that is propagated from parent to child or across an exec will consume about 200 bytes of Extended Common Storage Area (ECSA). If no STEPLIB environment variable is defined, or when it is defined as STEPLIB=CURRENT, z/OS UNIX propagates all currently active TASKLIB, STEPLIB, and JOBLIB allocations during a fork(), spawn(), or exec() function.

Developer for System z has a default of STEPLIB=NONE coded in rsed.envvars, as described in rsed.envvars, configuration file. For the reasons mentioned above, it is advised not to change this directive and place the targeted data sets in LINKLIST or LPA (Link Pack Area) instead.

Improve access to system libraries

Certain system libraries and load modules are heavily used by z/OS UNIX and application development activities. Improving access to these, such as adding them to the Link Pack Area (LPA) can improve your system performance. Refer to MVS Initialization and Tuning Reference (SA22-7592) for more information on changing the SYS1.PARMLIB members described as follows:

Language Environment (LE) runtime libraries

When C programs (including the z/OS UNIX shell) are run, they frequently use routines from the Language Environment (LE) runtime library. On average, about 4 MB of the runtime library are loaded into memory for every address space running a LE-enabled program, and copied on every fork.

The CEE.SCEELPA data set contains a subset of the LE runtime routines, which are heavily used by z/OS UNIX. You should add this data set to SYS1.PARMLIB(LPALSTxx) for maximum performance gain. By doing so, the modules are read from disk only once and are stored in a shared location.

Note:
Add the following statement to SYS1.PARMLIB(PROGxx) if you prefer to add the load modules into dynamic LPA (Link Pack Area):
LPA ADD MASK(*) DSNAME(CEE.SCEELPA) 

It is also advised to place the LE runtime libraries CEE.SCEERUN and CEE.SCEERUN2 in LINKLIST, by adding the data sets to SYS1.PARMLIB(LNKLSTxx) or SYS1.PARMLIB(PROGxx). This eliminates z/OS UNIX STEPLIB overhead and there is reduced input/output due to management by LLA and VLF, or similar products.

Note:
Add the C/C++ DLL class library CBC.SCLBDLL also to LINKLIST for the same reasons.

If you decide not to put these libraries in LINKLIST, then you must set up the appropriate STEPLIB statement in rsed.envvars, as described in rsed.envvars, configuration file. Although this method always uses additional virtual storage, you can improve performance by defining the LE runtime libraries to LLA or a similar product. This reduces the I/O that is needed to load the modules.

Application development

On systems where application development is the primary activity, performance may also benefit if you put the linkage editor into dynamic LPA, by adding the following lines to SYS1.PARMLIB(PROGxx):

LPA ADD MODNAME(CEEBINIT,CEEBLIBM,CEEEV003,EDCZV) DSNAME(CEE.SCEERUN)
LPA ADD MODNAME(IEFIB600,IEFXB603) DSNAME(SYS1.LINKLIB)

For C/C++ development, you can also add the CBC.SCCNCMP compiler data set to SYS1.PARMLIB(LPALSTxx).

The statements above are samples of possible LPA candidates, but the needs at your site may vary. Refer to Language Environment Customization (SA22-7564) for information on putting other LE load modules into dynamic LPA. Refer to UNIX System Services Planning (GA22-7800) for more information on putting C/C++ compiler load modules into dynamic LPA.

Improving performance of security checking

To improve the performance of security checking done for z/OS UNIX, define the BPX.SAFFASTPATH profile in the FACILITY class of your security software. This reduces overhead when doing z/OS UNIX security checks for a wide variety of operations. These include file access checking, IPC access checking, and process ownership checking. Refer to UNIX System Services Planning (GA22-7800) for more information on this profile.

Note:
Users do not need to be permitted to the BPX.SAFFASTPATH profile.

Workload management

Each site has specific needs, and can customize the z/OS operating system to get the most out of the available resources to meet those needs. With workload management, you define performance goals and assign a business importance to each goal. You define the goals for work in business terms, and the system decides how much resource, such as CPU and storage, should be given to the work to meet its goal.

Developer for System z performance can be balanced by setting the correct goals for its processes. Some general guidelines are listed as follows:

Refer to MVS Planning Workload Management (SA22-7602) for more information on this subject.

Fixed Java heap size

With a fixed-size heap, no heap expansion or contraction occurs and this can lead to significant performance gains in some situations. However, using a fixed-size heap is usually not a good idea, because it delays the start of garbage collection until the heap is full, at which point it will be a major task. It also increases the risk of fragmentation, which requires a heap compaction. Therefore, use fixed-size heaps only after proper testing or under the direction of the IBM support center. Refer to Java Diagnostics Guide (SC34-6650) for more information on heap sizes and garbage collection.

By default, the initial heap size of a z/OS Java Virtual Machine (JVM) is 1 megabyte. The maximum size is 64 megabytes. The limits can be set with the -Xms (initial) and -Xmx (maximum) Java command-line options.

In Developer for System z, Java command-line options are defined in the _RSE_JAVAOPTS directive of rsed.envvars, as described in Defining extra Java startup parameters with _RSE_JAVAOPTS.

#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xms128m -Xmx128m"

Java -Xquickstart option

Note:
Java -Xquickstart is only useful if you use the REXEC/SSH alternate startup method for RSE server. This method is documented in (Optional) Using REXEC (or SSH).

The -Xquickstart option can be used for improving startup time of some Java applications. -Xquickstart causes the JIT (Just In Time) compiler to run with a subset of optimizations; that is, a quick compile. This quick compile allows for improved startup time.

-Xquickstart is appropriate for shorter running applications, especially those where execution time is not concentrated into a small number of methods. -Xquickstart can degrade performance if it is used on longer-running applications that contain hot methods.

To enable the -Xquickstart option for the RSE server, add the following directive to the end of rsed.envvars:

_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xquickstart"

Class sharing between JVMs

The IBM Java Virtual Machine (JVM) version 5 and higher allows you to share bootstrap and application classes between JVMs by storing them in a cache in shared memory. Class sharing reduces the overall virtual memory consumption when more than one JVM shares a cache. Class sharing also reduces the startup time for a JVM after the cache has been created.

The shared class cache is independent of any active JVM and persists beyond the lifetime of the JVM that created the cache. Because the shared class cache persists beyond the lifetime of any JVM, the cache is updated dynamically to reflect any modifications that might have been made to JARs or classes on the file system.

The overhead to create and populate a new cache is minimal. The JVM startup cost in time for a single JVM is typically between 0 and 5% slower compared with a system not using class sharing, depending on how many classes are loaded. JVM startup time improvement with a populated cache is typically between 10% and 40% faster compared with a system not using class sharing, depending on the operating system and the number of classes loaded. Multiple JVMs running concurrently will show greater overall startup time benefits.

Refer to the Java SDK and Runtime Environment User Guide to learn more about class sharing.

Enable class sharing

To enable class sharing for the RSE server, add the following directive to the end of rsed.envvars. The first statement defines a cache named RSE with group access and it allows the RSE server to start even if class sharing fails. The second statement is optional and it sets the cache size to 6 megabytes (system default is 16 MB). The third statement adds the class sharing parameters to the Java startup options.

_RSE_CLASS_OPTS=-Xshareclasses:name=RSE,groupAccess,nonFatal
#_RSE_CLASS_OPTS="$_RSE_CLASS_OPTS -Xscmx6m
_RSE_JAVAOPTS="$_RSE_JAVAOPTS $_RSE_CLASS_OPTS"
Note:
As mentioned in Cache security, all users using the shared class must have the same primary group ID (GID). This means that the users must have the same default group defined in the security software, or that the different default groups have the same GID in their OMVS segment.

Cache size limits

The maximum theoretical shared cache size is 2 GB. The size of cache you can specify is limited by the amount of physical memory and swap space available to the system. Because the virtual address space of a process is shared between the shared class cache and the Java heap, increasing the maximum size of the Java heap will reduce the size of the shared class cache you can create.

Cache security

Access to the shared class cache is limited by operating system permissions and Java security permissions.

By default, class caches are created with user-level security, so only the user that created the cache can access it. On z/OS UNIX, there is an option, groupAccess, which gives access to all users in the primary group of the user that created the cache. However, regardless of the access level used, a cache can only be destroyed by the user that created it or by a root user (UID 0).

Refer to Java SDK and Runtime Environment User Guide to learn more about extra security options using a Java SecurityManager.

SYS1.PARMLIB(BPXPRMxx)

Some of the SYS1.PARMLIB(BPXPRMxx) settings affect shared classes performance. Using the wrong settings can stop shared classes from working. These settings might also have performance implications. For further information about performance implications and use of these parameters, refer to MVS Initialization and Tuning Reference (SA22-7592) and UNIX System Services Planning (GA22-7800). The most significant BPXPRMxx parameters that affect the operation of shared classes are the following:

Disk space

The shared class cache requires disk space to store identification information about the caches that exist on the system. This information is stored in /tmp/javasharedresources. If the identification information directory is deleted, the JVM cannot identify the shared classes on the system and must recreate the cache.

Cache management utilities

The Java -Xshareclasses line command can take a number of options, some of which are cache management utilities. Three of them are shown in the sample below ($ is the z/OS UNIX prompt). Refer to Java SDK and Runtime Environment User Guide for a complete overview of supported command-line options.

$ java -Xshareclasses:listAllCaches
Shared Cache            OS shmid        in use          Last detach time
RSE                     401412          0               Mon Jun 18 17:23:16 2007

Could not create the Java virtual machine.

$ java -Xshareclasses:name=RSE,printStats

Current statistics for cache "RSE":


base address       = 0x0F300058
end address        = 0x0F8FFFF8
allocation pointer = 0x0F4D2E28

cache size         = 6291368
free bytes         = 4355696
ROMClass bytes     = 1912272
Metadata bytes     = 23400
Metadata % used    = 1%

# ROMClasses       = 475
# Classpaths       = 4
# URLs             = 0
# Tokens           = 0
# Stale classes    = 0
% Stale classes    = 0%

Cache is 30% full

Could not create the Java virtual machine.

$ java -Xshareclasses:name=RSE,destroy
JVMSHRC010I Shared Cache "RSE" is destroyed
Could not create the Java virtual machine.
Notes:
  1. Cache utilities perform the required operation on the specified cache without starting the JVM, so the "Could not create the Java virtual machine." message is normal.
  2. A cache can be destroyed only if all JVMs using it have shut down, and the user issuing the command has sufficient permissions.

CICSTS considerations

Traditionally, the role of defining resources to CICS has been the domain of the CICS administrator. There has been a reluctance to allow the application developer to define CICS resources for various reasons:

Developer for System z addresses these issues by allowing CICS administrators to control CICS resource definition defaults, and to control the display properties of a CICS resource definition parameter by means of the CICS Resource Definition (CRD) server, which is part of Application Deployment Manager.

For example, the CICS administrator can supply certain CICS resource definition parameters that might not be updated by the application developer. Other CICS resource definition parameters may be updatable, with or without supplied defaults, or the CICS resource definition parameter can be hidden to avoid unnecessary complexity.

Once the application developer is satisfied with the CICS resource definitions they may be installed immediately in the running CICS test environment, or the definitions may be exported in a manifest for further editing and approval by a CICS administrator. The CICS administrator can use the administrative utility (batch utility) or the Manifest Processing tool to implement resource definition changes.

Note:
The Manifest Processing tool is a plugin for IBM CICS Explorer.

Refer to (Optional) Application Deployment Manager for more information on the tasks needed to set up Application Deployment Manager on your host system.

Customizing Application Deployment Manager adds the following services to Developer for System z:

The Application Deployment Manager CICS Resource Definition (CRD) server consists of the CRD server itself, a CRD repository, associated CICS resource definitions, and, when using the Web Service interface, Web Service bind files, and a sample pipeline message handler. The CRD server must run in a Web Owning Region (WOR), which is referenced in the Developer for System z documentation as the CICS primary connection region.

Refer to the Developer for System z Information Center (http://publib.boulder.ibm.com/infocenter/ratdevz/v7r6/index.jsp) to learn more about the services Application Deployment Manager available in the current release of Developer for System z.

RESTful versus Web Service

CICS Transaction Server provides in version 4.1 and higher support for an HTTP interface designed using Representational State Transfer (RESTful) principles. This RESTful interface is now the strategic CICSTS interface for use by client applications. The older Web Service interface has been stabilized, and enhancements will be for the RESTful interface only.

Application Deployment Manager follows this statement of direction and requires the RESTful CRD server for all services that are new to Developer for System version 7.6 or higher.

The RESTful and Web Service interfaces can be active concurrently in a single CICS region, if desired. In this case, there will be two CRD servers active in the region. Both servers will share the same CRD repository. Note that CICS will issue some warnings about duplicate definitions when the second interface is defined to the region.

Primary versus non-primary connection regions

A CICS test environment may consist of several Multi-Region Option (MRO) connected regions. Over time, unofficial designations have been used to categorize these regions. Typical designations are Terminal Owning Region (TOR), Web Owning Region (WOR), Application Owning Region (AOR), and Data Owning Region (DOR).

A Web Owning Region is used to implement CICS Web Services support, and the Application Deployment Manager CICS Resource Definition (CRD) server must run in this region. This region is known to Application Deployment Manager as the CICS primary connection region. The CRD client implements a Web service connection to the CICS primary connection region.

CICS non-primary connection regions are all other regions that the CRD server can service. This service includes viewing resources using IBM CICS Explorer and defining resources using the CICS resource definition editor.

If CICSPlex SM Business Application Services (BAS) is used to manage the CICS resource definitions of the CICS primary connection region, then all other CICS regions managed by BAS can be serviced by the CRD server.

CICS regions not managed by BAS require additional changes to be serviceable by the CRD server.

CICS resource install logging

Actions done by the CRD server against the CICS resources are logged in the CICS CSDL TD queue, which typically points to DD MSGUSR of your CICS region.

If CICSPlex SM Business Application Services (BAS) is used to manage your CICS resource definitions, then the CICSPlex SM EYUPARM directive BASLOGMSG must be set to (YES) for the logging to be created.

Application Deployment Manager security

CRD repository security

The CRD server repository VSAM data set holds all the default resource definitions and must therefore be protected against updates, but developers must be allowed to read the values stored here. Refer to Define data set profiles for sample RACF commands to protect the CRD repository.

Pipeline security

When a SOAP message is received by CICS through the Web Service interface, the message is processed by a pipeline. A pipeline is a set of message handlers that are executed in sequence. CICS reads the pipeline configuration file to determine which message handlers should be invoked in the pipeline. A message handler is a program in which you can perform special processing of Web service requests and responses.

Application Deployment Manager provides a sample pipeline configuration file that specifies the invocation of a message handler and a SOAP header processing program.

The pipeline message handler (ADNTMSGH) is used for security by processing the user ID and password in the SOAP header. ADNTMSGH is referenced by the sample pipeline configuration file and must therefore be placed into the CICS RPL concatenation.

Transaction security

CPIH is the default transaction ID under which an application invoked by a pipeline will run. Typically, CPIH is set for a minimal level of authorization.

Developer for System z supplies multiple transactions that are used by the CRD server when defining and inquiring CICS resources. These transaction IDs are set by the CRD server, depending on the requested operation. Refer to (Optional) Application Deployment Manager for more information on customizing the transaction IDs.

Transaction Description
ADMS For requests from the Manifest Processing tool to change CICS resources. Typically, this is intended for CICS administrators. This transaction requires a high level or authorization.
ADMI For requests that define, install or uninstall CICS resources. This transaction might require a medium level of authorization, depending on your site policies.
ADMR For all other requests that retrieve CICS environmental or resource information. This transaction might require a minimal level of authorization, depending on your site policies.

Some, or all, of the resource definition requests done by the CRD server transactions should be secured. At a minimum, the update commands (update default Web service parameters, default descriptor parameters, and file name to data set name binding) should be secured to prevent all but CICS administrators from issuing these commands used to set global resource defaults.

When the transaction is attached, CICS resource security checking, if enabled, insures that the user ID is authorized to run the transaction ID.

Resource checking is controlled by the RESSEC option in the transaction that is running, the RESSEC system initialization parameter, and for the CRD server, the XPCT system initialization parameter.

Resource checking occurs only if the XPCT system initialization parameter has a value other than NO and either the RESSEC option in the TRANSACTION definition is YES or the RESSEC system initialization parameter is ALWAYS.

The following RACF commands give a sample on how the CRD server transactions can be protected. Refer to RACF Security Guide for CICSTS for more information on defining CICS security.

SSL encrypted communication

SSL encryption of the data stream is supported when the Application Deployment Manager client uses the Web Services interface to invoke the CRD server. The usage of SSL for this communication is controlled by the SSL(YES) keyword in the CICSTS TCPIPSERVICE definition, as documented in RACF Security Guide for CICSTS.

Resource security

CICSTS provides the ability to protect resources and the commands to manipulate them. Certain Application Deployment Manager actions might fail if security is active, but not configured completely (for example, granting permissions to manipulate new resource types).

Upon function failure in Application Deployment Manager, examine the CICS log for messages like the following, and take corrective action, as documented in RACF Security Guide for CICSTS.

DFHXS1111 %date %time %applid %tranid Security violation by user 
%userid at netname %portname for resource %resource in class 
%classname. SAF codes are (X'safresp',X'safreas'). ESM codes are 
(X'esmresp',X'esmreas').

Administrative utility

Developer for System z provides the administrative utility to let CICS administrators provide the default values for CICS resource definitions. These defaults can be read-only, or can be editable by the application developer.

The administrative utility provides the following functions:

The administrative utility is invoked by sample job ADNJSPAU in data set FEK.#CUST.JCL. The usage of this utility requires UPDATE access to the CRD repository.

ADNJSPAU is located in FEK.#CUST.JCL, unless the z/OS system programmer specified a different location when he customized and submitted job FEK.SFEKSAMP(FEKSETUP). See Customization setup for more details.

Note:
The CRD repository must be closed in CICS before running the ADNJSPAU job. The repository can be opened again after job completion. For example, after signing on to CICS, enter the following commands to close and open the file, respectively:

Input control statements are used to update the CRD repository for a CICS test environment, for which the following general syntax rules apply:

The following sample definitions follow the structure of the DFHCSDUP commands, as defined in the CICS Resource Definition Guide for CICSTS. The only difference is the insertion of the following display permission keywords used to group the attribute values into three permission sets:

UPDATE Attributes following this keyword will be updatable by an application developer using Developer for System z. This is also the default for omitted attributes.
PROTECT Attributes following this keyword will display, but be protected from update by an application developer using Developer for System z.
HIDDEN Attributes following this keyword will not display, and will be protected from update by an application developer using Developer for System z.

See the following ADNJSPAU code sample.

Figure 52. ADNJSPAU - CICSTS administrative utility
//ADNJSPAU JOB <JOB PARAMETERS>
//*
//ADNSPAU  EXEC PGM=ADNSPAU,REGION=1M
//STEPLIB  DD DISP=SHR,DSN=FEK.SFEKLOAD
//ADMREP   DD DISP=OLD,DSN=FEK.#CUST.ADNREPF0
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
*
* CICSPlex SM parameters
*
DEFINE CPSMNAME(        )
*DEFINE STAGINGGROUPNAME(ADMSTAGE)
*
* Manifest export rule
*
DEFINE MANIFESTEXPORTRULE(installOnly)
*
* CICS resource definition defaults
* Omitted attributes default to UPDATE.
*
*   DB2TRAN default attributes
*
DEFINE DB2TRAN()
       UPDATE DESCRIPTION()
              ENTRY()
              TRANSID()
*
*   DOCTEMPLATE default attributes
*
DEFINE DOCTEMPLATE()
       UPDATE DESCRIPTION()
              TEMPLATENAME()
              FILE() TSQUEUE() TDQUEUE() PROGRAM() EXITPGM()
              DDNAME(DFHHTML) MEMBERNAME()
              HFSFILE()
              APPENDCRLF(YES) TYPE(EBCDIC)
*
*   File default attributes
*
DEFINE FILE()
       UPDATE  DESCRIPTION()
               RECORDSIZE() KEYLENGTH()
               RECORDFORMAT(V) ADD(NO)
               BROWSE(NO) DELETE(NO) READ(YES) UPDATE(NO)
               REMOTESYSTEM() REMOTENAME()
       PROTECT DSNAME() RLSACCESS(NO) LSRPOOLID(1) STRINGS(1)
               STATUS(ENABLED) OPENTIME(FIRSTREF)
               DISPOSITION(SHARE) DATABUFFERS(2) INDEXBUFFERS(1)
               TABLE(NO) MAXNUMRECS(NOLIMIT)
               READINTEG(UNCOMMITTED) DSNSHARING(ALLREQS)
               UPDATEMODEL(LOCKING) LOAD(NO)
               JNLREAD(NONE) JOURNAL(NO)
               JNLSYNCREAD(NO) JNLUPDATE(NO)
               JNLADD(NONE) JNLSYNCWRITE(YES)
               RECOVERY(NONE) FWDRECOVLOG(NO)
               BACKUPTYPE(STATIC)
               PASSWORD() NSRGROUP()
               CFDTPOOL() TABLENAME()
*
* Mapset default attributes
*
DEFINE MAPSET()
       UPDATE  DESCRIPTION()
       PROTECT RESIDENT(NO) STATUS(ENABLED)
               USAGE(NORMAL) USELPACOPY(NO)
** Processtype default attributes
*
DEFINE PROCESSTYPE()
       UPDATE  DESCRIPTION()
               FILE(BTS)
       PROTECT STATUS(ENABLED)
               AUDITLOG() AUDITLEVEL(OFF)
*
* Program default attributes
*
DEFINE PROGRAM()
       UPDATE  DESCRIPTION()
               CEDF(YES) LANGUAGE(LE370)
               REMOTESYSTEM() REMOTENAME() TRANSID()
       PROTECT API(CICSAPI) CONCURRENCY(QUASIRENT)
               DATALOCATION(ANY) DYNAMIC(NO)
               EXECKEY(USER) EXECUTIONSET(FULLAPI)
               RELOAD(NO) RESIDENT(NO)
               STATUS(ENABLED) USAGE(NORMAL) USELPACOPY(NO)
       HIDDEN JVM(NO) JVMCLASS() JVMPROFILE(DFHJVMPR)
*
* TDQueue default attributes
*
DEFINE TDQUEUE()
       UPDATE  DESCRIPTION()
               TYPE(INTRA)
* Extra partition parameters
               DDNAME() DSNAME()
               REMOTENAME() REMOTESYSTEM() REMOTELENGTH(1)
               RECORDSIZE() BLOCKSIZE(0) RECORDFORMAT(UNDEFINED)
               BLOCKFORMAT() PRINTCONTROL() DISPOSITION(SHR)
* Intra partition parameters
               FACILITYID() TRANSID() TRIGERRLEVEL(1)
               USERID()
* Indirect parameters
               INDIRECTNAME()
       PROTECT WAIT(YES) WAITACTION(REJECT)
* Extra partition parameters
               DATABUFFERS(1)
               SYSOUTCLASS() ERROROPTION(IGNORE)
               OPENTIME(INITIAL) REWIND(LEAVE) TYPEFILE(INPUT)
* Intra partition parameters
               ATIFACILITY(TERMINAL) RECOVSTATUS(NO)
*
* Transaction default attributes
*
DEFINE TRANSACTION()
       UPDATE  DESCRIPTION()
               PROGRAM()
               TWASIZE(0)
               REMOTESYSTEM() REMOTENAME() LOCALQ(NO)
       PROTECT PARTITIONSET() PROFILE(DFHCICST)
               DYNAMIC(NO) ROUTABLE(NO)
               ISOLATE(YES) STATUS(ENABLED)
               RUNAWAY(SYSTEM) STORAGECLEAR(NO)
               SHUTDOWN(DISABLED)
               TASKDATAKEY(USER) TASKDATALOC(ANY)
               BREXIT() PRIORITY(1) TRANCLASS(DFHTCL00)
               DTIMOUT(NO) RESTART(NO) SPURGE(NO) TPURGE(NO)
               DUMP(YES) TRACE(YES) CONFDATA(NO)
               OTSTIMEOUT(NO) WAIT(YES) WAITTIME(00,00,00)
               ACTION(BACKOUT) INDOUBT(BACKOUT)
               RESSEC(NO) CMDSEC(NO)
               TRPROF()
               ALIAS() TASKREQ()
               XTRANID() TPNAME() XTPNAME()
*
* Optional file name to VSAM data set name binding
*
*DEFINE DSBINDING() DSNAME()
/*

Administrative utility messages

The following messages are issued by the Administrative utility to the SYSPRINT DD. Messages WZAD1803E, WZAD1891E, WZAD1892E, and WZAD1893E contain file status, VSAM return, VSAM function, and VSAM feedback codes. VSAM return, function, and feedback codes are documented in DFSMS Macro Instructions for Data Sets (SC26-7408). File status codes are documented in Enterprise COBOL for z/OS Language Reference (SC27-1408).

WZAD1800I
completed successfully on line <last control statement line number>

Explanation: The system programmer administrative utility completed successfully.

User response: None.

WZAD1801W
completed with warnings on line <last control statement line number>

Explanation: The system programmer administrative utility completed with one or more warnings found when processing control statements.

User response: Check other warning messages.

WZAD1802E
encountered an error on line < line number>

Explanation: The system programmer administrative utility encountered a severe error.

User response: Check other warning messages.

WZAD1803E
Repository open error, status=<file status code> RC=<VSAM return code> FC=<VSAM function code> FB=<VSAM feedback code>

Explanation: The system programmer administrative utility encountered a severe error opening the CRD repository.

User response: Check VSAM status, return, function, and feedback codes.

WZAD1804E
Unrecognized input record on line <line number>

Explanation: The system programmer administrative utility encountered an unrecognized input control statement.

User response: Check a DEFINE command was followed by a single space, followed by the keyword CPSMNAME, STAGINGGROUPNAME, MANIFESTEXPORTRULE, DSBINDING, DB2TRAN, DOCTEMPLATE, FILE, MAPSET, PROCESSTYPE, PROGRAM, TDQUEUE, or TRANSACTION.

WZAD1805E
Processing keyword <keyword> on line <line number>

Explanation: The system programmer administrative utility is processing the DEFINE keyword input control statement.

User response: None.

WZAD1806E
Invalid manifest export rule on line <line number>

Explanation: The system programmer administrative utility encountered an invalid manifest export rule.

User response: Check that the MANIFESTEXPORTRULE keyword value is "installOnly", "exportOnly", or "both".

WZAD1807E
Missing DSNAME keyword on line <line number>

Explanation: The system programmer administrative utility was processing a DEFINE DSBINDING control statement which is missing the DSNAME keyword.

User response: Check that the DEFINE DSBINDING control statement contains the DSNAME keyword.

WZAD1808E
Invalid keyword value for keyword <keyword> on line <line number>

Explanation: The system programmer administrative utility was processing a DEFINE control statement and encountered an invalid value for the named keyword.

User response: Check that the length and value of the named keyword is correct.

WZAD1890W
Keyword syntax error on line <line number>

Explanation: The system programmer administrative utility was processing a DEFINE control statement and encountered a syntax error for a keyword or keyword value.

User response: Check that the keyword value is enclosed in parenthesis and immediately follows the keyword. The keyword and keyword value must both be contained on the same line.

WZAD1891W
Repository duplicate key write error, status=<file status code> RC=<VSAM return code> FC=<VSAM function code> FB=<VSAM feedback code>

Explanation: The system programmer administrative utility encountered a duplicate key error writing to the CRD repository.

User response: Check VSAM status, return, function, and feedback codes.

WZAD1892W
Repository write error, status=<file status code> RC=<VSAM return code> FC=<VSAM function code> FB=<VSAM feedback code>

Explanation: The system programmer administrative utility encountered a severe error writing to the CRD repository.

User response: Check VSAM status, return, function, and feedback codes.

WZAD1893W
Repository read error, status=<file status code> RC=<VSAM return code> FC=<VSAM function code> FB=<VSAM feedback code>

Explanation: The system programmer administrative utility encountered a severe error reading from the CRD repository.

User response: Check VSAM status, return, function, and feedback codes.

Customizing the TSO environment

This appendix is provided to assist you with mimicking a TSO logon procedure by adding DD statements and data sets to the TSO environment in Developer for System z.

The TSO Commands service

The TSO Commands service is the Developer for System z component which executes TSO and (batch) ISPF commands, and returns the result to the requesting client. These commands can be requested implicitly by the product, or explicitly by the user.

The sample members provided with Developer for System z create a minimal TSO/ISPF environment. If the developers in your shop need access to custom or third-party libraries, the z/OS system programmer must add the necessary DD statements and libraries to the TSO Commands service environment. Although the implementation is different in Developer for System z, the logic behind it is identical to the TSO logon procedure.

Note:
The TSO Commands service is a non-interactive command-line tool, so commands or procedures that prompt for data or display ISPF panels will not work. A 3270 emulator, such as the Host Connect Emulator which is part of the Developer for System z client, is needed to execute these.

Access methods

Since version 7.1, Developer for System z provides a choice on how to access the TSO Commands service.

Note:
ISPF's TSO/ISPF Client Gateway service replaces the SCLM Developer Toolkit function used in version 7.1.

Check rsed.envvars to determine which access method is used for version 7.1 and higher hosts. If defaults were used during the configuration process, rsed.envvars resides in /etc/rdz/.

Using the TSO/ISPF Client Gateway access method

Basic customization - ISPF.conf

The ISPF.conf configuration file (by default located in /etc/rdz/) defines the TSO/ISPF environment used by Developer for System z. There is only one active ISPF.conf configuration file, which is used by all Developer for System z users.

The main section of the configuration file defines the DD names and the related data set concatenations, like that in the following sample:

sysproc=ISP.SISPCLIB,FEK.SFEKPROC
ispmlib=ISP.SISPMENU
isptlib=ISP.SISPTENU
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB
ispllib=ISP.SISPLOAD
myDD=HLQ1.LLQ1,HLQ2.LLQ2

Advanced - Use existing ISPF profiles

By default, the TSO/ISPF Client Gateway creates a temporary ISPF profile for the TSO Commands service. However, you can instruct the TSO/ISPF Client Gateway z to use a copy of an existing ISPF profile. The key here is the _RSE_CMDSERV_OPTS statement in rsed.envvars.

#_RSE_CMDSERV_OPTS="$_RSE_CMDSERV_OPTS &ISPPROF=&SYSUID..ISPPROF"

Uncomment the statement (remove the leading pound sign (#) character) and provide the fully qualified data set name of the existing ISPF profile to use this facility.

The following variables can be used in the data set name:

Notes:
  1. If the data set name passed in "ISPPROF" is invalid, a temporary, empty ISPF profile is used instead.
  2. The ISPF profile (both temporary and copied) is deleted at the end of the session. Changes made to the profile are not merged into the existing ISPF profile.

Advanced - Using an allocation exec

The allocjob statement in ISPF.conf (which is commented out by default) points to an exec which can be used to provide further data set allocations by user ID.

*allocjob = FEK.#CUST.CNTL(CRAISPRX)

Uncomment the statement (remove the leading asterisk (*) character) and provide the fully qualified reference to the allocation exec to use this facility.

Note:
As the exec is called before ISPF is initialized, you cannot use VPUT and VGET. You can however create your own implementation of these functions using a PDS(E) or VSAM file.

Advanced - Use multiple allocation execs

Although ISPF.conf only supports calling one allocation exec, there are no limits on that exec calling another exec. And the user ID of the client being passed as parameter opens the door to calling personalized allocation execs. You can, for example, check if member USERID'.EXEC(ALLOC)' exists and execute it.

An elaborate variation to this theme enables you to use the existing TSO logon procedures, as follows:

Advanced - Multiple ISPF.conf files with multiple Developer for System z setups

If the allocation exec scenarios described above cannot handle your specific needs, you can create different instances of Developer for System z's RSE communication server, each using their own ISPF.conf file. The main drawback of the method described below is that Developer for System z users must connect to different servers on the same host to get the desired TSO environment.

Note:
Creating a second instance of the RSE server only requires duplicating and updating configuration files, startup JCL and started task definitions. A new installation of the product is not necessary, nor is any code duplicated.
$ cd /etc/rdz
$ mkdir /etc/rdz/tso2
$ cp rsed.envvars /etc/rdz/tso2
$ cp ISPF.conf /etc/rdz/tso2
$ ls /etc/rdz/tso2
ISPF.conf          rsed.envvars
$ oedit /etc/rdz/tso2/rsed.envvars
      -> change: _CMDSERV_CONF_HOME=/etc/rdz/tso2
      -> uncomment and change: -Ddaemon.log=/var/rdz/logs/tso2
      -> add at the END:
         # -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
         CFG_BASE=/etc/rdz
         CLASSPATH=.:$CFG_BASE:$CLASSPATH
         # -- 
$ oedit /etc/rdz/tso2/ISPF.conf
      -> change: change as needed

The commands in the previous example copy the Developer for System z configuration files that require changes to a newly created tso2 directory. The _CMDSERV_CONF_HOME variable in rsed.envvars must be updated to define the new ISPF.conf home directory and daemon.log must be updated to define a new log location (which is created automatically if it does not exist). The CLASSPATH update ensures that RSE can find the configuration files that were not copied to tso2. The ISPF.conf file itself can be updated to match your needs. Note that the ISPF workarea (variable _CMDSERV_WORK_HOME in rsed.envvars) can be shared among both instances.

What is left now is creating a new started task for RSE that uses a new port number and the new /etc/rdz/tso2 configuration files.

Refer to the related sections in this publication for more information on the actions shown above.

Using the APPC access method

Basic customization - APPC transaction JCL

The definition of an APPC transaction consists of APPC parameters and a transaction JCL. The sample JCL to create a Developer for System z APPC transaction, FEK.#CUST.JCL(FEKAPPCC), holds two options to define the transaction JCL, with and without ISPF support.

//SYSIN    DD DDNAME=SYSINISP            * use SYSINTSO or SYSINISP

The client gets the TSO/ISPF environment defined in the transaction JCL, so by customizing this section, following regular DD rules, you can customize the environment for the client.

...
//CMDSERV  EXEC PGM=IKJEFT01,DYNAMNBR=50,
//      PARM='ISPSTART CMD(%FEKFRSRV TIMEOUT=60) NEWAPPL(ISR) NESTMACS'
//SYSPROC  DD DISP=SHR,DSN=FEK.SFEKPROC
//ISPPLIB  DD DISP=SHR,DSN=ISP.SISPPENU
//ISPMLIB  DD DISP=SHR,DSN=ISP.SISPMENU
//ISPTLIB  DD DISP=SHR,DSN=ISP.SISPTENU
//ISPSLIB  DD DISP=SHR,DSN=ISP.SISPSENU
//ISPPROF  DD DISP=(NEW,DELETE,DELETE),DSN=&&PROF,
//            SPACE=(TRK,(1,1,5)),LRECL=80,RECFM=FB,UNIT=SYSALLDA
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTSIN  DD DUMMY
//MYDD     DD DISP=SHR,DSN=HLQ1.LLQ1
//            DISP=SHR,DSN=HLQ2.LLQ2
Note:
An existing APPC transaction can be modified using the APPC ISPF panels.

Advanced - Use existing ISPF profiles

If ISPF support is selected, Developer for System z creates by default a temporary ISPF profile for the TSO Commands service. However, you can instruct Developer for System z to use a copy of an existing ISPF profile. As described in the FEK.SFEKSAMP(FEKAPPCC) sample job, you must perform the following:

...
//COPY     EXEC PGM=IEBCOPY   * (optional) clone existing ISPF profile
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DISP=SHR,DSN=&SYSUID..ISPROF
//SYSUT2   DD DISP=(MOD,PASS),DSN=&&PROF,
//            UNIT=SYSALLDA,
//            LIKE=&SYSUID..ISPROF
//*
//CMDSERV  EXEC PGM=IKJEFT01,DYNAMNBR=50,
//      PARM='ISPSTART CMD(%FEKFRSRV TIMEOUT=60) NEWAPPL(ISR) NESTMACS'
//*ISPPROF  DD DISP=(NEW,DELETE,DELETE),DSN=&&PROF,
//*            SPACE=(TRK,(1,1,5)),LRECL=80,RECFM=FB
//ISPPROF  DD DISP=(OLD,DELETE,DELETE),DSN=&&PROF
Note:
If an invalid data set name is used, the startup of the APPC transaction (and thus the TSO Commands service) will fail.

Advanced - Using an allocation exec

The sample transaction JCL calls the TSO Command service directly by passing its name (FEKFRSRV) as parameter to program IKJEFT01. You can change this to call another exec. This exec can do allocations based on the current user ID and then call the TSO Command service.

Contrary to the TSO/ISPF Client Gateway access method, variables stored in the user's ISPF profile can be used by this exec to assist in customizing the environment. But keep in mind that updates to the profile will be lost at session end since you are using a temporary copy, not the actual profile.

Note, however, that the use of an allocation exec in the APPC transaction is not supported and the description above is as-is.

Advanced - Multiple APPC transactions with multiple Developer for System z setups

If you need multiple unique TSO environments, you can create different instances of Developer for System z's RSE communication server, each using their own APPC transaction. The main drawback of the method described below is that Developer for System z users must connect to different servers on the same host to get the desired TSO environment.

Note:
Creating a second instance of the RSE server only requires duplicating and updating configuration files, startup JCL and started task definitions. A new installation of the product is not necessary, nor is any code duplicated.
$ cd /etc/rdz
$ mkdir /etc/rdz/tso2
$ cp rsed.envvars  /etc/rdz/tso2
$ ls /etc/rdz/tso2/
rsed.envvars
$ oedit /etc/rdz/tso2/rsed.envvars
      -> uncomment and change: _FEKFSCMD_TP_NAME_=FEKFTSO2
      -> uncomment and change: -Ddaemon.log=/var/rdz/logs/tso2
      -> add at the END:
         # -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
         CFG_BASE=/etc/rdz
         CLASSPATH=.:$CFG_BASE:$CLASSPATH 
         # -- 

The commands above create a new tso2 directory and copy the Developer for System z configuration files that require changes to the new location. The _FEKFSCMD_TP_NAME_ variable in rsed.envvars must be updated to define the new APPC transaction name, and daemon.log must be updated to define a new daemon log location (which is created automatically if it does not exist). The CLASSPATH update ensures that RSE can find the configuration files that were not copied to tso2.

Figure 53. FEKAPPCC - create a second APPC transaction
//FEKAPPCC JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),NOTIFY=&SYSUID
//*
//TPADD    EXEC PGM=ATBSDFMU
//SYSSDLIB DD DISP=SHR,DSN=SYS1.APPCTP
//SYSSDOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DDNAME=SYSINISP          * use SYSINTSO or SYSINISP
//SYSINISP DD DATA,DLM='QT'
     TPADD
       TPNAME(FEKFTSO2)
       ACTIVE(YES)
       TPSCHED_DELIMITER(DLM1)
       KEEP_MESSAGE_LOG(ERROR)
       MESSAGE_DATA_SET(&SYSUID..FEKFTSO2.&TPDATE..&TPTIME..LOG)
       DATASET_STATUS(MOD)
       CLASS(A)
       JCL_DELIMITER(DLM2)
//FEKFTSO2 JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1)
//*
//CMDSERV  EXEC PGM=IKJEFT01,DYNAMNBR=50,
//  PARM='ISPSTART CMD(%FEKFRSRV TIMEOUT=60) NEWAPPL(ISR) NESTMACS'
//SYSPROC  DD DISP=SHR,DSN=FEK.SFEKPROC
//ISPPLIB  DD DISP=SHR,DSN=ISP.SISPPENU
//ISPMLIB  DD DISP=SHR,DSN=ISP.SISPMENU
//ISPTLIB  DD DISP=SHR,DSN=ISP.SISPTENU
//ISPSLIB  DD DISP=SHR,DSN=ISP.SISPSENU
//ISPPROF  DD DISP=(NEW,DELETE,DELETE),DSN=&&PROF,
//            SPACE=(TRK,(1,1,5)),LRECL=80,RECFM=FB,UNIT=SYSALLDA
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTSIN  DD DUMMY
//MYDD     DD DISP=SHR,DSN=HLQ1.LLQ1
//            DISP=SHR,DSN=HLQ2.LLQ2
DLM2
DLM1
QT

Next, create a new APPC transaction by customizing and submitting sample job FEK.#CUST.JCL(FEKAPPCC), as shown in the sample above. On top of the normal customization (described in the JCL) you must also change the TPNAME to TPNAME(FEKFTSO2) to match the _FEKFSCMD_TP_NAME_ definition in the new rsed.envvars. You should also change the name in the MESSAGE_DATA_SET variable and the JOB name of the transaction JCL.

What is left now is creating a new started task for RSE that uses a new port number and the new /etc/rdz/tso2 configuration files.

Refer to the related sections in this publication for more information on the actions shown above.

Running multiple instances

There are times that you want multiple instances of Developer for System z active on the same system, for example, when testing an upgrade. However, some resources such as TCP/IP ports cannot be shared, so the defaults are not always applicable. Use the information in this appendix to plan the coexistence of the different instances of Developer for System z, after which you can use this configuration guide to customize them.

Although it is possible to share certain parts of Developer for System z between two (or more) instances, it is advised NOT to do so, unless their software levels are identical and the only changes are in configuration members. Developer for System z leaves enough customization room to make multiple instances that do not overlap and we strongly advise you to use these features.

Note:

Identical setup across a sysplex

Developer for System z configuration files (and code) can be shared across different systems in a sysplex, with each system running its own identical copy of Developer for System z, if a few guidelines are obeyed.

Identical software level, different configuration files

In a limited set of circumstances, you can share all but (some of) the customizable parts. An example is providing non-SSL access for on-site usage, and SSL encoded communication for off-site usage.

Attention: The shared setup CANNOT be used safely to test maintenance, a technical preview, or a new release.

To set up another instance of an active Developer for System z installation, redo the customization steps for the parts that are different, using different data sets, directories, and ports to avoid overlapping the current setup.

In the SSL sample mentioned above, the current RSE daemon setup can be cloned, after which the cloned setup can be updated. Next the RSE daemon startup JCL can be cloned and customized with a new TCP/IP port and the location of the updated configuration files. The MVS customizations (JES Job Monitor, and so on) can be shared between the SSL and non-SSL instances. This would result in the following actions:

$ cd /etc/rdz
$ mkdir /etc/rdz/ssl
$ cp rsed.envvars /etc/rdz/ssl
$ cp ssl.properties /etc/rdz/ssl
$ ls /etc/rdz/ssl/
rsed.envvars    ssl.properties
$ oedit /etc/rdz/ssl/rsed.envvars
      -> uncomment and change: -Ddaemon.log=/var/rdz/logs/ssl
      -> add at the END:
         # -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
         CFG_BASE=/etc/rdz
         CLASSPATH=.:$CFG_BASE:$CLASSPATH
         # -- 
$ oedit /etc/rdz/ssl/ssl.properties
      -> change: change as needed

The commands above copy the Developer for System z configuration files that require changes to a newly created ssl directory. The daemon.log variable in rsed.envvars must be updated to define a new log location (which is created automatically if it does not exist). The CLASSPATH update ensures that RSE can find the configuration files that were not copied to ssl. The ssl.properties file itself can be updated to match your needs.

What is left now is creating a new started task for RSE that uses a new port number and the new /etc/rdz/ssl configuration files.

Refer to the related sections in this publication for more information on the actions shown above.

All other situations

When code changes are involved (maintenance, technical previews, new release), or your changes are fairly complex, you should do another installation of Developer for System z. This section describes possible points of conflict between the different installations.

The following list is a brief overview of items that must or are strongly advised to be different between the instances of Developer for System z:

A more detailed overview is listed as follows:

Migration guide

Migration considerations

This section highlights installation and configuration changes compared to previous releases of the product. It also gives some general guidelines to migrate to this release. Refer to the related sections in this manual for more information.

Note:
The migration information listed here is for Developer for System z versions that are still supported at the time of publication.

Backing up previously configured files

If you are a previous user of Developer for System z, it is recommended that you save the related customized files before installing this version of IBM Developer for System z.

Customizable Developer for system z files can be found at the following locations:

Previous Developer for system z setups also document changes to configuration files owned by other products.

This section highlights installation and configuration changes compared to previous releases of the product. Refer to the related sections in this manual for more information.

Migrate from version 7.5 to version 7.6

IBM Rational Developer for System z, FMID HHOP760

Configurable files

Table 39 gives an overview of files that are customized in version 7.6. Note that the Developer for System z sample libraries, FEK.SFEKSAMP, FEK.SFEKSAMV and /usr/lpp/rdz/samples/, come with more customizable members than listed here, such as sample CARMA source code and jobs to compile them.

Note:
Sample job FEKSETUP copies all listed members to different data sets and directories, default FEK.#CUST.* and /etc/rdz/*.
Table 39. Version 7.6 customizations
Member/File Default location Purpose Migration notes
FEKSETUP
FEK.SFEKSAMP
[FEK.#CUST.JCL]
JCL to create data sets and directories, and populate them with customizable files Updated to include new customizable members
JMON
FEK.SFEKSAMP(FEJJJCL)
[FEK.#CUST.PROCLIB]
JCL for JES Job Monitor Added option to change LE options
FEJJJCL
FEK.SFEKSAMP
[FEK.#CUST.PROCLIB(JMON)]
Shipping name for JMON member See JMON member
RSED
FEK.SFEKSAMP(FEKRSED)
[FEK.#CUST.PROCLIB]

JCL for RSE daemon none
FEKRSED
FEK.SFEKSAMP
[FEK.#CUST.PROCLIB(RSED)]

Shipping name for RSED member See RSED member
LOCKD
FEK.SFEKSAMP(FEKLOCKD)
[FEK.#CUST.PROCLIB]

JCL for lock daemon NEW, customization is required
FEKLOCKD
FEK.SFEKSAMP
[FEK.#CUST.PROCLIB(LOCKD)]

Shipping name for LOCKD member See LOCKD member
ELAXF*
FEK.SFEKSAMP
[FEK.#CUST.PROCLIB]

JCL for remote project builds, and so forth none
FEKRACF
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL for security definitions Minor updates
FEJJCNFG
FEK.SFEKSAMP
[FEK.#CUST.PARMLIB]

JES Job Monitor configuration file New optional directives have been added
FEJTSO
FEK.SFEKSAMP
[FEK.#CUST.CNTL]

JCL for TSO submits none
CRA$VMSG
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the CARMA message VSAM none
CRA$VDEF
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the CARMA configuration VSAM none
CRA$VSTR
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the CARMA custom information VSAM none
CRASUBMT
FEK.SFEKSAMP
[FEK.#CUST.CNTL]

CARMA batch startup CLIST none
CRAISPRX
FEK.SFEKSAMP
[FEK.#CUST.CNTL]

Sample DD allocation exec for CARMA using TSO/ISPF Client Gateway none
CRA#VSLM
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the SCLM RAM's message VSAM none
CRA#ASLM
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the SCLM RAM's data sets none
CRA#VPDS
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the PDS RAM's message VSAM none
CRA#CRAM
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to compile the skeleton RAM none
CRA#VCAD
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the CARMA configuration VSAM for CA Endevor® RAM NEW, customization is optional
CRA#VCAS
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the CARMA custom information VSAM for CA Endevor® RAM NEW, customization is optional
CRA#UADD
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to merge RAM definitions NEW, customization is optional
CRA#UQRY
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to extract RAM definitions NEW, customization is optional
CRAXJCL
FEK.SFEKSAMP
[FEK.#CUST.ASM]

Sample source code for IRXJCL replacement none
CRA#CIRX
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to compile CRAXJCL none
ADNCSDRS
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to define the RESTful CRD server to primary CICS region NEW, customization is optional
ADNCSDTX
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to define alternate transaction IDs to CICS region NEW, customization is optional
ADNTXNC
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create alternate transaction IDs NEW, customization is optional
ADNMSGHC
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to compile ADNMSGHS Renamed, was ADNCMSGH
ADNMSGHS
FEK.SFEKSAMP
[FEK.#CUST.COBOL]

Sample source code for the Pipeline Message Handler Renamed, was ADNSMSGH
ADNVCRD
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create the CRD repository Renamed, was ADNVSAM
ADNCSDWS
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to define the Web Service CRD server to primary CICS region Renamed, was ADNPCCSD
ADNCSDAR
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to define the CRD server to non-primary CICS regions Renamed, was ADNARCSD
ADNJSPAU
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to update the CRD defaults Definitions for the RESTful service are added, customizations must be redone
ADNVMFST
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create and define the Manifest repository Renamed, was ADNMFEST
ELAXMSAM
FEK.SFEKSAMP
[FEK.#CUST.PROCLIB]

JCL procedure of the WLM address space for the PL/I and COBOL Stored Procedure Builder none
ELAXMJCL
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to define the PL/I and COBOL Stored Procedure Builder to DB2 none
FEKAPPCC
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to create an APPC transaction none
FEKAPPCL
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to display an APPC transaction none
FEKAPPCX
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to delete an APPC transaction none
FEKLOGS
FEK.SFEKSAMP
[FEK.#CUST.JCL]

JCL to collect log files NEW, customization is optional
rsed.envvars
/usr/lpp/rdz/samples/
[/etc/rdz/]

RSE environment variables Older copies must be replaced by this one (customizations must be redone).
ISPF.conf
/usr/lpp/rdz/samples/
[/etc/rdz/]

TSO/ISPF Client Gateway configuration file ISP.SISPCLIB added to SYSPROC for SCLMDT
CRASRV.properties
/usr/lpp/rdz/samples/
[/etc/rdz/]

CARMA configuration file none
crastart.conf
/usr/lpp/rdz/samples/
[/etc/rdz/]

CARMA configuration file for CRASTART usage none
ssl.properties
/usr/lpp/rdz/samples/
[/etc/rdz/]

RSE SSL configuration file New optional directives have been added
rsecomm.properties
/usr/lpp/rdz/samples/
[/etc/rdz/]

RSE trace configuration file none
propertiescfg.properties
/usr/lpp/rdz/samples/
[/etc/rdz/]

Host based property groups configuration file none
projectcfg.properties
/usr/lpp/rdz/samples/
[/etc/rdz/]

Host based projects configuration file none
FMIEXT.properties
/usr/lpp/rdz/samples/
[/etc/rdz/]

File Manager Integration configuration file Older copies must be replaced by this one (customizations must be redone).
uchars.settings
/usr/lpp/rdz/samples/
[/etc/rdz/]

Uneditable characters configuration file none

Migrate from version 7.1 to version 7.5

IBM Rational Developer for System z, FMID HHOP750

Configurable files

Table 40 gives an overview of files that are customized in version 7.5. Note that the Developer for System z sample libraries, FEK.SFEKSAMP, FEK.SFEKSAMV and /usr/lpp/rdz/samples/, come with more customizable members than listed here, such as sample CARMA source code and jobs to compile them.

Note:
Sample job FEKSETUP copies all listed members to different data sets and directories, default FEK.#CUST.* and /etc/rdz/*.
Table 40. Version 7.5 customizations
Member/File Default location Purpose Migration notes
FEKSETUP FEK.SFEKSAMP

[FEK.#CUST.JCL]

JCL to create data sets and directories, and populate them with customizable files NEW, customization is required
JMON FEK.SFEKSAMP(FEJJJCL)

[FEK.#CUST.PROCLIB]

JCL for JES Job Monitor STEPLIB changed to SFEKAUTH
RSED FEK.SFEKSAMP(FEKRSED)

[FEK.#CUST.PROCLIB]

JCL for RSE daemon NEW, customization is required
ELAXF* FEK.SFEKSAMP

[FEK.#CUST.PROCLIB]

JCL for remote project builds, and so on ELAXFTSO, ELAXFCP1 and ELAXFPP1 are new
FEKRACF FEK.SFEKSAMP

[FEK.#CUST.JCL]

JCL for security definitions NEW, required
FEJJCNFG FEK.SFEKSAMP

[FEK.#CUST.PARMLIB]

JES Job Monitor configuration file
  • Some directives became optional
  • New optional directives have been added
FEJTSO FEK.SFEKSAMP

[FEK.#CUST.CNTL]

JCL for TSO submits Job name can now be a variable
CRAISPRX FEK.SFEKSAMP

[FEK.#CUST.CNTL]

Sample DD allocation exec for CARMA using TSO/ISPF Client Gateway NEW, customization is optional
CRAXJCL FEK.SFEKSAMP

[FEK.#CUST.ASM]

Sample source code for IRXJCL replacement NEW, customization is optional
CRA#CIRX FEK.SFEKSAMP

[FEK.#CUST.JCL]

JCL to compile CRAXJCL NEW, customization is optional
ADNSMSGH FEK.SFEKSAMP

[FEK.#CUST.COBOL]

Sample source code for the Pipeline Message Handler Older copies must be replaced by this one (customizations must be redone)
ADNPCCSD FEK.SFEKSAMP

[FEK.#CUST.JCL]

JCL to define the CRD server to primary CICS region Older copies must be replaced by this one (customizations must be redone)
ADNJSPAU FEK.SFEKSAMP

[FEK.#CUST.JCL]

JCL to update the CRD defaults NEW, customization is optional
ADNMFEST FEK.SFEKSAMP

[FEK.#CUST.JCL]

JCL to create and define the Manifest repository NEW, customization is optional
rsed.envvars /usr/lpp/rdz/samples/

[/etc/rdz/]

RSE environment variables Older copies must be replaced by this one (customizations must be redone)
ISPF.conf /usr/lpp/rdz/samples/

[/etc/rdz/]

TSO/ISPF Client Gateway configuration file Identical to the ISPF.conf shipped with SCLMDT in v7.1
CRASRV.properties /usr/lpp/rdz/samples/

[/etc/rdz/]

CARMA configuration file
  • Startup script changed location and name
  • New optional directives have been added
crastart.conf /usr/lpp/rdz/samples/

[/etc/rdz/]

CARMA configuration file for CRASTART usage NEW, customization is optional
FMIEXT.properties /usr/lpp/rdz/samples/

[/etc/rdz/]

File Manager Integration configuration file
  • Startup script changed location and name
  • New optional directives have been added
uchars.settings /usr/lpp/rdz/samples/

[/etc/rdz/]

Uneditable characters configuration file NEW, customization is optional

Migrate from version 7.0 to version 7.1

IBM Rational Developer for System z, FMID HHOP710

IBM Common Access Repository Manager (CARMA), FMID HCMA710

Configurable files

Table 23 gives an overview of files that are customized in version 7.1. Note that the CARMA and Developer for System z sample libraries, CRA.SCRASAMP, FEK.SFEKSAMP and /usr/lpp/wd4z/rse/lib/, come with more customizable members than listed here, such as sample CARMA source code and jobs to compile them.

Table 41. Version 7.1 customizations
Member/File Default location Purpose Migration notes
ELAXF* FEK.SFEKSAMP JCL for remote project builds, and other jobs ELAXFADT is new
CRA$VMSG CRA.SCRASAMP JCL to create the CARMA message VSAM
  • renamed, was CRAMREPR
  • the VSAM created by this job is updated
CRA$VDEF CRA.SCRASAMP JCL to create the CARMA configuration VSAM
  • renamed, was CRAREPR
  • the VSAM created by this job is updated
CRA$VSTR CRA.SCRASAMP JCL to create the CARMA custom information VSAM renamed, was CRASREPR
CRASUBMT CRA.SCRASAMP CARMA batch startup CLIST add DD CARMALOG
CRA#VSLM CRA.SCRASAMP JCL to create the SCLM RAM's message VSAM renamed, was CRALREPR
CRA#ASLM CRA.SCRASAMP JCL to create the SCLM RAM's data sets renamed, was CRASALX
CRA#VPDS CRA.SCRASAMP JCL to create the PDS RAM's message VSAM renamed, was CRATREPR
CRA#CRAM CRA.SCRASAMP JCL to compile the skeleton RAM renamed, was CRARAMCM
FEKAPPCC FEK.SFEKSAMP JCL to create an APPC transaction exploit ISPF NEST support
rsed.envvars
/usr/lpp/wd4z/rse/lib/
[/etc/wd4z/]

RSE environment variables Older copies must be replaced by this one (customizations must be redone)
FMIEXT.properties
/usr/lpp/wd4z/rse/lib/
[/etc/wd4z/]

File Manager Integration configuration file NEW, customization is required when used

Appendixes

Appendix A. Setting up SSL and X.509 authentication

This appendix is provided to assist you with some common problems that you may encounter when setting up Secure Socket Layer (SSL), or during checking and/or modifying an existing setup. This appendix also provides a sample setup to support users authenticating themselves with an X.509 certificate.

Secure communication means ensuring that your communication partner is who he claims to be, and transmitting information in a manner that makes it difficult for others to intercept and read the data. SSL provides this ability in a TCP/IP network. It works by using digital certificates to identify yourself and a public key protocol to encrypt the communication. Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on digital certificates and the public key protocol used by SSL.

The actions needed to set up SSL communications for Developer for System z will vary from site to site, depending on the exact needs, the RSE communication method used and what's already available at the site.

In this appendix we will clone the current RSE definitions, so that we have a 2nd RSE daemon connection that will use SSL. We will also create our own security certificates to be used by the different parts of the RSE connection.

Throughout this appendix, a uniform naming convention is used:

Some tasks described below expect you to be active in z/OS UNIX. This can be done by issuing the TSO command OMVS. Use the exit command to return to TSO.

Decide where to store private keys and certificates

The identity certificates and the encryption/decryption keys used by SSL are stored in a key file. Different implementations of this key file exist, depending on the application type.

However, all implementations follow the same principle. A command generates a key pair (a public key and associated private key). The command then wraps the public key into an X.509 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored as an entry (identified by an alias) in a key file.

The RSE daemon is a System SSL application and uses a key database file. This key database can be a physical file created by gskkyman or a key ring managed by your SAF-compliant security software (for example, RACF). The RSE server (which is started by the daemon) is a Java SSL application and uses a key store file created by keytool or a key ring managed by your security software.

Table 42. SSL certificate storage mechanisms
Certificate storage Created and managed by RSE daemon RSE server
key ring SAF-compliant security product supported supported
key database z/OS UNIX's gskkyman supported /
key store Java's keytool / supported

To connect through SSL, we need both the key store and the key database, either as a z/OS UNIX file or as a SAF-compliant key ring:

Notes:
  1. SAF-compliant key rings are the preferred method for managing certificates.
  2. A shared certificate can be used if RSE daemon and RSE server use the same certificate management method.
  3. RSE daemon must run program controlled. Using System SSL within implies that SYS1.SIEALNKE must be made program controlled by your security software.
  4. In order to run a System SSL application (daemon connection), SYS1.SIEALNKE must be in LINKLIST or STEPLIB. If you prefer the STEPLIB method, add the following statement to the end of rsed.envvars.
    STEPLIB=$STEPLIB:SYS1.SIEALNKE

    Be aware, however, that:

  5. System SSL uses the Integrated Cryptographic Service Facility (ICSF) if it is available. ICSF provides hardware cryptographic support which will be used instead of the System SSL software algorithms. Refer to System SSL Programming (SC24-5901) for more information.

Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for information on RACF and digital certificates. gskkyman documentation can be found in System SSL Programming (SC24-5901), and keytool documentation is available at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.

Create a key ring with RACF

Do not execute this step if you use gskkyman to create the RSE daemon key database and keytool to create the RSE server key store.

The RACDCERT command installs and maintains private keys and certificates in RACF. RACF supports multiple private keys and certificates to be managed as a group. These groups are called key rings.

Refer to Security Server RACF Command Language Reference (SA22-7687) for details on the RACDCERT command.

RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ACCESS(READ) ID(stcrse)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(stcrse)
SETROPTS RACLIST(FACILITY) REFRESH

RACDCERT ID(stcrse) GENCERT SUBJECTSDN(CN('rdz rse ssl') +
  OU('rdz') O('IBM') L('Raleigh') SP('NC') C('US')) +
  NOTAFTER(DATE(2017-05-21)) WITHLABEL('rdzrse') KEYUSAGE(HANDSHAKE)

RACDCERT ID(stcrse) ADDRING(rdzssl.racf)
RACDCERT ID(stcrse) CONNECT(LABEL('rdzrse') RING(rdzssl.racf) +
  DEFAULT USAGE(PERSONAL))

The sample above starts by creating the necessary profiles and permitting user ID STCRSE access to key rings and certificates owned by that user ID. The user ID used must match the user ID used to run the SSL RSE daemon. The next step is creating a new, self-signed, certificate with label rdzrse. No password is needed. This certificate is then added to a newly created key ring (rdzssl.racf). Just as with the certificate, no password is needed for the key ring.

The result can be verified with the following list option:

RACDCERT ID(stcrse) LIST
Digital certificate information for user STCRSE:

 Label: rdzrse
 Certificate ID: 2QjW1OXi0sXZ1aaEqZmihUBA
 Status: TRUST
 Start Date: 2007/05/24 00:00:00
 End Date:   2017/05/21 23:59:59
 Serial Number:
      >00<
 Issuer's Name:
      >CN=rdz rse ssl.OU=rdz.O=IBM.L=Raleigh.SP=NC.C=US<
 Subject's Name:
      >CN=rdz rse ssl.OU=rdz.O=IBM.L=Raleigh.SP=NC.C=US<
 Private Key Type: Non-ICSF
 Private Key Size: 1024
 Ring Associations:
   Ring Owner: STCRSE
   Ring:
      >rdzssl.racf<

(Optional) Using a signed certificate

Certificates can be either self-signed or signed by a Certificate Authority (CA). A certificate signed by a CA means that the CA guarantees that the owner of the certificate is who he claims to be. The signing process adds the CA credentials (also a certificate) to your certificate, making it a multi-element certificate chain.

When using a certificate signed by a CA you can avoid trust validation questions by the Developer for System z client, if the client already trusts the CA.

Follow these steps to create and use a CA signed certificate:

  1. Create a self-signed certificate.
    RACDCERT ID(stcrse) GENCERT WITHLABEL('rdzrse') . . .
  2. Create a signing request for this certificate.
    RACDCERT ID(stcrse) GENREQ (LABEL('rdzrse')) DSN(dsn)
  3. Send the signing request to your CA of choice.
  4. Check if the CA credentials (also a certificate) are already known.
    RACDCERT CERTAUTH LIST
  5. Mark the CA certificate as trusted.
    RACDCERT CERTAUTH ALTER(LABEL('CA cert')) TRUST

    Or add the CA certificate to the database.

    RACDCERT CERTAUTH ADD(dsn) WITHLABEL('CA cert') TRUST
  6. Add the signed certificate to the database; this will replace the self-signed one.
    RACDCERT ID(stcrse) ADD(dsn) WTIHLABEL('rdzrse') TRUST
    Note:
    Do NOT delete the self-signed certificate before replacing it. If you do, you lose the private key that goes with the certificate, which makes the certificate useless.
  7. Create a key ring.
    RACDCERT ID(stcrse) ADDRING(rdzssl.racf)
  8. Add the signed certificate to the key ring.
    RACDCERT ID(stcrse) CONNECT(ID(stcrse) LABEL('rdzrse') 
    RING(rdzssl.racf))
  9. Add the CA certificate to the key ring.
    RACDCERT ID(stcrse) CONNECT(CERTAUTH LABEL('CA cert') 
    RING(rdzssl.racf))

Clone the existing RSE setup

In this step a new instance of the RSE configuration files is created, so that the SSL setup can run parallel with the existing one(s). The following sample commands expect the configuration files to be in /etc/rdz/, which is the default location used in Customization setup.

$ cd /etc/rdz
$ mkdir ssl
$ cp rsed.envvars ssl
$ cp ssl.properties ssl
$ ls ssl
rsed.envvars    ssl.properties

The z/OS UNIX commands listed above create a subdirectory called ssl and populate it with the configuration files that require changes. We can share the other configuration files, the installation directory, and the MVS components, because they are not SSL-specific.

By reusing most of the existing configuration files, we can focus on the changes that are actually required for setting up SSL and avoid doing the complete RSE setup again. (For example, we can avoid defining a new location for ISPF.conf.)

Update rsed.envvars to enable coexistence

So far, the definitions are an exact copy of the current setup, which implies that the logs of the new RSE daemon will overlay the current server log files. RSE also needs to know where to find the configuration files that were not copied to the ssl directory. Both issues can be addressed by minor changes to rsed.envvars.

$ oedit /etc/rdz/ssl/rsed.envvars
	   -> uncomment and change: -Ddaemon.log=/var/rdz/logs/ssl
	   -> add at the END:
         # -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
         CFG_BASE=/etc/rdz
         CLASSPATH=.:$CFG_BASE:$CLASSPATH 
         # -- 

The changes above define a new log location (which will be created by RSE daemon if the log location does not exist). The changes also update the CLASSPATH so that the SSL RSE processes will first search the current directory (/etc/rdz/ssl) for configuration files and then search the original directory (/etc/rdz).

Update ssl.properties to enable SSL

By updating ssl.properties, RSE is instructed to start using SSL encrypted communication.

$ oedit /etc/rdz/ssl/ssl.properties
      -> change: enable_ssl=true
      -> uncomment and change: daemon_keydb_file=rdzssl.racf
      -> uncomment and change: daemon_key_label=rdzrse
      -> uncomment and change: server_keystore_file=rdzssl.racf
      -> uncomment and change: server_keystore_label=rdzrse
      -> uncomment and change: server_keystore_type=JCERACFKS

The changes above enable SSL and tell the RSE daemon and RSE server that their (shared) certificate is stored under label rdzrse in key ring rdzssl.racf. The JCERACFKS keyword tells RSE server that a SAF-compliant key ring is used as key store.

Activate SSL by creating a new RSE daemon

As stated before, we will create a second connection that will use SSL, which implies creating a new RSE daemon. The RSE daemon can be a started task or user job. We will use the user job method for initial (test) setup. The following instructions expect the sample JCL to be in FEK.#CUST.PROCLIB(RSED), which is the default location used in Customization setup:

  1. Create a new member FEK.#CUST.PROCLIB(RSEDSSL) and copy in sample JCL FEK.#CUST.PROCLIB(RSED).
  2. Customize RSEDSSL by adding a job card on top and an exec statement at the bottom. Also provide a new port number (4047) and the location of the SSL-related configuration files (/etc/rdz/ssl), as shown in the following code sample. Note that we enforce the usage of user ID STCRSE, as this user ID was given the proper access authority to certificates and key rings in a previous step.
Figure 54. RSEDSSL - RSE daemon user job for SSL
//RSEDSSL  JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),USER=STCRSE
//*
//* RSE DAEMON - SSL
//*
//RSED     PROC IVP='',              * 'IVP' to do an IVP test
//            PORT=4047,
//            HOME='/usr/lpp/rdz',
//            CNFG='/etc/rdz/ssl'
//*
//RSE      EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT,
//            PARM='PGM &HOME./bin/rsed.sh &IVP &PORT &CNFG' 
//STDOUT   DD SYSOUT=* 
//STDERR   DD SYSOUT=* 
//PEND 
//* 
//RSED     EXEC RSED 
//*

Note:
The user ID assigned to the RSEDSSL job must have the same authorizations as the original RSE daemon. FACILITY profile BPX.SERVER and PTKTDATA profile IRRPTAUTH.FEKAPPL.* are the key elements here.

Test the connection

The SSL host configuration is complete and the RSE daemon for SSL can be started by submitting job FEK.#CUST.PROCLIB(RSEDSSL), which was created earlier.

The new setup can now be tested by connecting with the Developer for System z client. Since we created a new configuration for use by SSL (by cloning the existing one), a new connection must be defined on the client, using port 4047 for the RSE daemon.

Upon connection, the host and client will start with some handshaking in order to set up a secure path. Part of this handshaking is the exchange of certificates. If the Developer for System z client does not recognize the host certificate or the CA that signed it, Developer for System z client will prompt the user asking if this certificate can be trusted.

Figure 55. Import Host Certificate dialog
Import Host Certificate

By clicking the Finish button the user can accept this certificate as trusted, after which the connection initialization continues.

Note:
RSE daemon and RSE server might use two different certificate locations, resulting in two different certificates and thus two confirmations.

Once a certificate is known to the client, this dialog is not shown again. The list of trusted certificates can be managed by selecting Window > Preferences... > Remote Systems > SSL, which shows the following dialog:

Figure 56. Preferences dialog - SSL
preferences

If SSL communication fails, the client will return an error message. More information is available in the different server and user log files, as described in RSE daemon and thread pool logging and RSE user logging.

(Optional) Add X.509 client authentication support

RSE daemon supports users authenticating themselves with an X.509 certificate. Using SSL encrypted communication is a prerequisite for this function, because it is an extension to the host authentication with a certificate used in SSL.

There are multiple ways to do certificate authentication for a user, as described in Client authentication using X.509 certificates. The next steps document the setup needed to support the method where your security software authenticates the certificate using the HostIdMappings certificate extension.

  1. Change the certificate that identifies the Certificate Authority (CA) used to sign the client certificate to a highly trusted CA certificate. Although the TRUST status is sufficient for certificate validation, a change to HIGHTRUST is done, because it is used for the certificate authentication part of the logon process.
    RACDCERT CERTAUTH ALTER(LABEL('HighTrust CA')) HIGHTRUST
  2. Add the CA certificate to the key ring, rdzssl.racf, so that it is available to validate the client certificates.
    RACDCERT ID(stcrse) CONNECT(CERTAUTH LABEL('HighTrust CA') +
      RING(rdzssl.racf))

    This concludes the security software setup for the CA certificate.

  3. Define a resource (format IRR.HOST.hostname) in the SERVAUTH class for the host name, CDFMVS08.RALEIGH.IBM.COM, defined in the HostIdMappings extension of your client certificate.
    RDEFINE SERVAUTH  IRR.HOST.CDFMVS08.RALEIGH.IBM.COM  UACC(NONE)
  4. Grant the RSE started task user ID, STCRSE, access to this resource with READ authority.
    PERMIT IRR.HOST.CDFMVS08.RALEIGH.IBM.COM  CLASS(SERVAUTH) +
      ACCESS(READ) ID(stcrse)
  5. Activate your changes to the SERVAUTH class. Use the first command if the SERVAUTH class is not active yet. Use the second one to refresh an active setup.
    SETROPTS CLASSACT(SERVAUTH) RACLIST(SERVAUTH)
    or
    SETROPTS RACLIST(SERVAUTH) REFRESH

    This concludes the security software setup for the HostIdMappings extension.

  6. Restart the RSE started task to start accepting client logons using X.509 certificates.

(Optional) Create a key database with gskkyman

Do not execute this step if you use an SAF-compliant key ring for the RSE daemon key database.

gskkyman is a z/OS UNIX shell-based, menu-driven, program that creates, populates, and manages a z/OS UNIX file that contains private keys, certificate requests, and certificates. This z/OS UNIX file is called a key database.

Note:
The following statements might be necessary to set up the environment for gskkyman. Refer to System SSL Programming (SC24-5901) for more information on this.
PATH=$PATH:/usr/lpp/gskssl/bin
export NLSPATH=/usr/lpp/gskssl/lib/nls/msg/En_US.IBM-1047/%N:$NLSPATH
export STEPLIB=$STEPLIB:SYS1.SIEALNKE
$ cd /etc/rdz/ssl
$ gskkyman       Database Menu

   1 - Create new database
   
Enter option number: 1
Enter key database name (press ENTER to return to menu): rdzssl.kdb
Enter database password (press ENTER to return to menu): rsessl
Re-enter database password: rsessl
Enter password expiration in days (press ENTER for no expiration):
Enter database record length (press ENTER to use 2500):

Key database /etc/rdz/ssl/rdzssl.kdb created.

Press ENTER to continue.

       Key Management Menu

       6 - Create a self-signed certificate
   
Enter option number (press ENTER to return to previous menu): 6

       Certificate Type

   5 - User or server certificate with 1024-bit RSA key
   
Select certificate type (press ENTER to return to menu): 5
Enter label (press ENTER to return to menu): rdzrse
Enter subject name for certificate
  Common name (required): rdz rse ssl
  Organizational unit (optional): rdz
  Organization (required): IBM
  City/Locality (optional): Raleigh
  State/Province (optional): NC
  Country/Region (2 characters - required): US
Enter number of days certificate will be valid (default 365): 3650

Enter 1 to specify subject alternate names or 0 to continue: 0

Please wait .....

Certificate created.

Press ENTER to continue.

       Key Management Menu

         0 - Exit program

Enter option number (press ENTER to return to previous menu): 0
$ ls -l rdzssl.*
total 152
-rw-------   1 IBMUSER  SYS1       35080 May 24 14:24 rdzssl.kdb
-rw-------   1 IBMUSER  SYS1          80 May 24 14:24 rdzssl.rdb
$ chmod 644 rdzssl.*
$ ls -l rdzssl.*
-rw-r--r--   1 IBMUSER  SYS1       35080 May 24 14:24 rdzssl.kdb
-rw-r--r--   1 IBMUSER  SYS1          80 May 24 14:24 rdzssl.rdb

The sample above starts by creating a key database called rdzssl.kdb with password rsessl. Once the database exists, it is populated by creating a new, self-signed, certificate, valid for about 10 years (not counting leap days). The certificate is stored under the label rdzrse and with the same password (rsessl) as the one used for the key database (this is an RSE requisite).

gskkyman allocates the key database with a (very secure) 600 permission bit mask (only owner has access). Unless the daemon uses the same user ID as the creator of the key database, permissions have to be set less restrictive. 644 (owner has read/write, everyone has read) is a usable mask for the chmod command.

The result can be verified by selecting the Show certificate information option in the Manage keys and certificates submenu, as follows:

$ gskkyman

       Database Menu

   2 - Open database
   
Enter option number: 2
Enter key database name (press ENTER to return to menu): rdzssl.kdb
Enter database password (press ENTER to return to menu): rsessl

       Key Management Menu

          1 - Manage keys and certificates
   
Enter option number (press ENTER to return to previous menu): 1

       Key and Certificate List

          1 - rdzrse

   Enter label number (ENTER to return to selection menu, p for previous list): 1

       Key and Certificate Menu

   1 - Show certificate information
   
Enter option number (press ENTER to return to previous menu): 1

                        Certificate Information

                 Label: rdzrse
             Record ID: 14
      Issuer Record ID: 14
               Trusted: Yes
               Version: 3
         Serial number: 45356379000ac997
           Issuer name: rdz rse ssl
                        rdz
                        IBM
                        Raleigh
                        NC
                        US
          Subject name: rdz rse ssl
                        rdz
                        IBM
                        Raleigh
                        NC
                        US
        Effective date: 2007/05/24
       Expiration date: 2017/05/21
  Public key algorithm: rsaEncryption
       Public key size: 1024
   Signature algorithm: sha1WithRsaEncryption
      Issuer unique ID: None
     Subject unique ID: None
  Number of extensions: 3

Enter 1 to display extensions, 0 to return to menu: 0

       Key and Certificate Menu

     0 - Exit program

Enter option number (press ENTER to return to previous menu): 0

The following ssl.properties sample shows that the daemon_* directives differ from the SAF key ring sample shown earlier.

$ oedit /etc/rdz/ssl/ssl.properties
      -> change: enable_ssl=true
      -> uncomment and change: daemon_keydb_file=rdzssl.kdb
      -> uncomment and change: daemon_keydb_password=rsessl
      -> uncomment and change: daemon_key_label=rdzrse
      -> uncomment and change: server_keystore_file=rdzssl.racf
      -> uncomment and change: server_keystore_label=rdzrse
      -> uncomment and change: server_keystore_type=JCERACFKS

The changes above enable SSL and tell the RSE daemon that the certificate is stored under label rdzrse in key database rdzssl.kdb with password rsessl. RSE server is still using a SAF compliant key ring.

(Optional) Create a key store with keytool

Do not execute this step if you use a SAF-compliant key ring for the RSE server key store.

"keytool -genkey" generates a private key pair and a matching self-signed certificate, which is stored as an entry (identified by an alias) in a (new) key store file.

Note:
Java must be included in your command search directories. The following statement might be necessary to be able to execute keytool, where /usr/lpp/java/J5.0 is the directory where Java is installed: PATH=$PATH:/usr/lpp/java/J5.0/bin

All information can be passed as a parameter, but due to command-line length limitations some interactivity is required, as follows:

$ cd /etc/rdz/ssl
$ keytool -genkey -alias rdzrse -validity 3650 -keystore rdzssl.jks -storepass
 rsessl -keypass rsessl
What is your first and last name?
  [Unknown]:  rdz rse ssl
What is the name of your organizational unit?
  [Unknown]:  rdz
What is the name of your organization?
  [Unknown]:  IBM
What is the name of your City or Locality?
  [Unknown]:  Raleigh
What is the name of your State or Province?
  [Unknown]:  NC
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=rdz rse ssl, OU=rdz, O=IBM, L=Raleigh, ST=NC, C=US correct? (type "yes"
or "no")
  [no]:  yes
$ ls -l rdzssl.*
-rw-r--r--   1 IBMUSER  SYS1        1224 May 24 14:17 rdzssl.jks

The self-signed certificate created above is valid for about 10 years (not counting leap days). It is stored in /etc/rdz/ssl/rdzssl.jks using alias rdzrse. Its password (rsessl) is identical to the key store password, which is a requisite for RSE.

The result can be verified with the -list option, as follows:

$ keytool -list -alias rdzrse -keystore rdzssl.jks -storepass rsessl -v
Alias name: rdzrse
Creation date: May 24, 2007
Entry type: keyEntry
Certificate chain length: 1
Certificate 1¨:
Owner: CN=rdz rse ssl, OU=rdz, O=IBM, L=Raleigh, ST=NC, C=US
Issuer: CN=rdz rse ssl, OU=rdz, O=IBM, L=Raleigh, ST=NC, C=US
Serial number: 46562b2b
Valid from: 5/24/07 2:17 PM until: 5/21/17 2:17 PM
Certificate fingerprints:
         MD5:  9D:6D:F1:97:1E:AD:5D:B1:F7:14:16:4D:9B:1D:28:80
         SHA1: B5:E2:31:F5:B0:E8:9D:01:AD:2D:E6:82:4A:E0:B1:5E:12:CB:10:1C

The following ssl.properties sample shows that the server_* directives differ from the SAF key ring sample shown earlier.

$ oedit /etc/rdz/ssl/ssl.properties
      -> change: enable_ssl=true
      -> uncomment and change: daemon_keydb_file=rdzssl.racf
      -> uncomment and change: daemon_key_label=rdzrse
      -> uncomment and change: server_keystore_file=rdzssl.jks
      -> uncomment and change: server_keystore_password=rsessl
      -> uncomment and change: server_keystore_label=rdzrse
      -> optionally uncomment and change: server_keystore_type=JKS

The changes above enable SSL and tell the RSE server that the certificate is stored under label rdzrse in key store rdzssl.jks with password rsessl. RSE daemon is still using a SAF-compliant key ring.

Appendix B. Setting up TCP/IP

This appendix is provided to assist you with some common problems that you may encounter when setting up TCP/IP, or during checking or modifying an existing setup.

Refer to Communications Server: IP Configuration Guide (SC31-8775) and Communications Server: IP Configuration Reference (SC31-8776) for additional information on TCP/IP configuration.

Hostname dependency

When using APPC for the TSO Commands service, Developer for System z is dependent upon TCP/IP having the correct hostname when it is initialized. This implies that the different TCP/IP and Resolver configuration files must be set up correctly.

You can test your TCP/IP configuration with the fekfivpt Installation Verification Program (IVP). The command should return an output like that in this sample ($ is the z/OS UNIX prompt):

$ fekfivpt

Wed Jul  2 13:11:54 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars

-------------------------------------------------------------
TCP/IP resolver configuration (z/OS UNIX search order):
-------------------------------------------------------------
Resolver Trace Initialization Complete -> 2008/07/02 13:11:54.745964

res_init Resolver values:
 Global Tcp/Ip Dataset  = None
 Default Tcp/Ip Dataset = None
 Local Tcp/Ip Dataset   = /etc/resolv.conf
 Translation Table      = Default
 UserId/JobName         = USERID
 Caller API             = LE C Sockets
 Caller Mode            = EBCDIC
 (L) DataSetPrefix = TCPIP
 (L) HostName      = CDFMVS08
 (L) TcpIpJobName  = TCPIP
 (L) DomainOrigin  = RALEIGH.IBM.COM
 (L) NameServer    = 9.42.206.2
                     9.42.206.3
 (L) NsPortAddr    = 53            (L) ResolverTimeout    = 10
 (L) ResolveVia    = UDP           (L) ResolverUdpRetries = 1
 (*) Options NDots = 1
 (*) SockNoTestStor
 (*) AlwaysWto     = NO            (L) MessageCase        = MIXED
 (*) LookUp        = DNS LOCAL
res_init Succeeded
res_init Started: 2008/07/02 13:11:54.755363
res_init Ended: 2008/07/02 13:11:54.755371
************************************************************************
MVS TCP/IP NETSTAT CS V1R9       TCPIP Name: TCPIP           13:11:54
Tcpip started at 01:28:36 on 06/23/2008 with IPv6 enabled

-------------------------------------------------------------
host IP address:
-------------------------------------------------------------
hostName=CDFMVS08
hostAddr=9.42.112.75
bindAddr=9.42.112.75
localAddr=9.42.112.75

Success, addresses match

Understanding resolvers

The resolver acts on behalf of programs as a client that accesses name servers for name-to-address or address-to-name resolution. To resolve the query for the requesting program, the resolver can access available name servers, use local definitions (for example, /etc/resolv.conf, /etc/hosts, /etc/ipnodes, HOSTS.SITEINFO, HOSTS.ADDRINFO or ETC.IPNODES), or use a combination of both.

When the resolver address space starts, it reads an optional resolver setup data set pointed to by the SETUP DD card in the resolver JCL procedure. If the setup information is not provided, the resolver uses the applicable native MVS or z/OS UNIX search order without any GLOBALTCPIPDATA, DEFAULTTCPIPDATA, GLOBALIPNODES, DEFAULTIPNODES or COMMONSEARCH information.

Understanding search orders of configuration information

It is important to understand the search order for configuration files used by TCP/IP functions, and when you can override the default search order with environment variables, JCL, or other variables you provide. This knowledge allows you to accommodate your local data set and HFS file naming standards, and it is helpful to know the configuration data set or HFS file in use when diagnosing problems.

Another important point to note is that when a search order is applied for any configuration file, the search ends with the first file found. Therefore, unexpected results are possible if you place configuration information in a file that never gets found, either because other files exist earlier in the search order, or because the file is not included in the search order chosen by the application.

When searching for configuration files, you can explicitly tell TCP/IP where most configuration files are by using DD statements in the JCL procedures or by setting environment variables. Otherwise, you can let TCP/IP dynamically determine the location of the configuration files, based on search orders documented in Communications Server: IP Configuration Guide (SC31-8775).

The TCP/IP stack's configuration component uses TCPIP.DATA during TCP/IP stack initialization to determine the stack's HOSTNAME. To get its value, the z/OS UNIX environment search order is used.

Note:
Use the trace resolver facility to determine what TCPIP.DATA values are being used by the resolver and where they were read from. For information on dynamically starting the trace, refer to Communications Server: IP Diagnosis Guide (GC31-8782). Once the trace is active, issue a TSO NETSTAT HOME command and a z/OS UNIX shell netstat -h command to display the values. Issuing a PING of a host name from TSO and from the z/OS UNIX shell also shows activity to any DNS servers that might be configured.

Search orders used in the z/OS UNIX environment

The particular file or table that is searched for can be either an MVS data set or an HFS file, depending on the resolver configuration settings and the presence of given files on the system.

Base resolver configuration files

The base resolver configuration file contains TCPIP.DATA statements. In addition to resolver directives, it is referenced to determine, among other things, the data set prefix (DATASETPREFIX statement's value) to be used when trying to access some of the configuration files specified in this section.

The search order used to access the base resolver configuration file is the following:

  1. GLOBALTCPIPDATA

    If defined, the resolver GLOBALTCPIPDATA setup statement value is used (see also Understanding resolvers). The search continues for an additional configuration file. The search ends with the next file found.

  2. The value of the environment variable RESOLVER_CONFIG

    The value of the environment variable is used. This search will fail if the file does not exist or is allocated exclusively elsewhere.

  3. /etc/resolv.conf
  4. //SYSTCPD DD card

    The data set allocated to the DD name SYSTCPD is used. In the z/OS UNIX environment, a child process does not have access to the SYSTCPD DD. This is because the SYSTCPD allocation is not inherited from the parent process over the fork() or exec function calls.

  5. userid.TCPIP.DATA

    userid is the user ID that is associated with the current security environment (address space, task, or thread).

  6. jobname.TCPIP.DATA

    jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.

  7. SYS1.TCPPARMS(TCPDATA)
  8. DEFAULTTCPIPDATA

    If defined, the resolver DEFAULTTCPIPDATA setup statement value is used (see also Understanding resolvers).

  9. TCPIP.TCPIP.DATA

Translate tables

The translate tables (EBCDIC-to-ASCII and ASCII-to-EBCDIC) are referenced to determine the translate data sets to be used. The search order used to access this configuration file is the following. The search order ends at the first file being found:

  1. The value of the environment variable X_XLATE The value of the environment variable is the name of the translate table produced by the TSO CONVXLAT command.
  2. userid.STANDARD.TCPXLBIN

    userid is the user ID that is associated with the current security environment (address space or task/thread).

  3. jobname.STANDARD.TCPXLBIN

    jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.

  4. hlq.STANDARD.TCPXLBIN

    hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.

  5. If no table is found, the resolver uses a hard-coded default table, identical to the table listed in data set member SEZATCPX(STANDARD).

Local host tables

By default, resolver first attempts to use any configured domain name servers for resolution requests. If the resolution request cannot be satisfied, local host tables are used. Resolver behavior is controlled by TCPIP.DATA statements.

The TCPIP.DATA resolver statements define if and how domain name servers are to be used. The LOOKUP TCPIP.DATA statement can also be used to control how domain name servers and local host tables are used. For more information on TCPIP.DATA statements, refer to Communications Server: IP Configuration Reference (SC31-8776).

The resolver uses the Ipv4-unique search order for sitename information unconditionally for getnetbyname API calls. The Ipv4-unique search order for sitename information is the following. The search ends at the first file being found:

  1. The value of the environment variable X_SITE

    The value of the environment variable is the name of the HOSTS.SITEINFO information file created by the TSO MAKESITE command.

  2. The value of the environment variable X_ADDR

    The value of the environment variable is the name of the HOSTS.ADDRINFO information file created by the TSO MAKESITE command.

  3. /etc/hosts
  4. userid.HOSTS.SITEINFO

    userid is the user ID that is associated with the current security environment (address space or task/thread).

  5. jobname.HOSTS.SITEINFO

    jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.

  6. hlq.HOSTS.SITEINFO

    hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.

Applying this set up information to Developer for System z

As stated before, Developer for System z is dependent upon TCP/IP having the correct hostname when it is initialized, when using APPC. This implies that the different TCP/IP and Resolver configuration files must be set up correctly.

In the following example we will focus on some configuration tasks for TCP/IP and Resolver. Note that this does not cover a complete setup of TCP/IP or Resolver, it just highlights some key aspects that might be applicable to your site:

  1. In the JCL below we see that TCP/IP will use SYS1.TCPPARMS(TCPDATA) to determine the stack's hostname.
    //TCPIP    PROC PARMS='CTRACE(CTIEZB00)',PROF=TCPPROF,DATA=TCPDATA
    //*
    //* TCP/IP NETWORK
    //*
    //TCPIP    EXEC PGM=EZBTCPIP,REGION=0M,TIME=1440,PARM=&PARMS
    //PROFILE  DD  DISP=SHR,DSN=SYS1.TCPPARMS(&PROF)
    //SYSTCPD  DD  DISP=SHR,DSN=SYS1.TCPPARMS(&DATA)
    //SYSPRINT DD  SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
    //ALGPRINT DD  SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
    //CFGPRINT DD  SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
    //SYSOUT   DD  SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
    //CEEDUMP  DD  SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
    //SYSERROR DD  SYSOUT=*
  2. SYS1.TCPPARMS(TCPDATA) tells us that we want the system name to be the hostname and that we do not use a domain name server (DNS); all names will be resolved through site table lookup.
    ; HOSTNAME specifies the TCP host name of this system.  If not
    ; specified, the default HOSTNAME will be the node name specified
    ; in the IEFSSNxx PARMLIB member.
    ;
    ; HOSTNAME
    ;
    ; DOMAINORIGIN specifies the domain origin that will be appended
    ; to host names passed to the resolver.  If a host name contains
    ; any dots, then the DOMAINORIGIN will not be appended to the
    ; host name.
    ;
    DOMAINORIGIN  RALEIGH.IBM.COM
    ;
    ; NSINTERADDR specifies the IP address of the name server.
    ; LOOPBACK (14.0.0.0) specifies your local name server. If a name
    ; server will not be used, then do not code an NSINTERADDR statement.
    ; (Comment out the NSINTERADDR line below).  This will cause all names
    ; to be resolved via site table lookup.
    ;
    ; NSINTERADDR  14.0.0.0
    ;
    ; TRACE RESOLVER will cause a complete trace of all queries to and
    ; responses from the name server or site tables to be written to
    ; the user's console.  This command is for debugging purposes only.
    ;
    ; TRACE RESOLVER
  3. In the Resolver JCL we see that the SETUP DD statement is not used. As mentioned in Understanding resolvers, this means that GLOBALTCPIPDATA and other variables will not be used.
    //RESOLVER PROC PARMS='CTRACE(CTIRES00)'
    //*
    //* IP NAME RESOLVER - START WITH SUB=MSTR
    //*
    //RESOLVER EXEC PGM=EZBREINI,REGION=0M,TIME=1440,PARM=&PARMS
    //*SETUP    DD  DISP=SHR,DSN=USER.PROCLIB(RESSETUP),FREE=CLOSE
  4. If we assume that the RESOLVER_CONFIG environment variable is not set, we can see in Table 43 that Resolver will try to use /etc/resolv.conf as base configuration file.
    TCPIPJOBNAME TCPIP
    DomainOrigin RALEIGH.IBM.COM
    HostName CDFMVS08

    As mentioned in Search orders used in the z/OS UNIX environment, the base configuration file contains TCPIP.DATA statements. If the system name is CDFMVS08 (TCPDATA stated that the system name is used as hostname) we can see that /etc/resolv.conf is in sync with SYS1.TCPPARMS(TCPDATA). There are no DNS definitions so site table lookup will be used.

  5. Table 43 also tells us that if we do not have to do anything to use the default ASCII-EBCDIC translation table.
  6. Assuming that the TSO MAKESITE command is not used (can create the X_SITE and X_ADDR variables), /etc/hosts will be the site table used for name lookup.
    #  Resolver /etc/hosts file cdfmvs08
    9.42.112.75   cdfmvs08                     # CDFMVS08 Host
    9.42.112.75   cdfmvs08.raleigh.ibm.com     # CDFMVS08 Host
    127.0.0.1     localhost

    The minimal content of this file is information about the current system. In the sample above we define both cdfmvs08 and cdfmvs08.raleigh.ibm.com as a valid name for the IP address of our z/OS system.

    If we were using a domain name server (DNS), the DNS would hold the /etc/hosts info, and /etc/resolv.conf and SYS1.TCPPARMS(TCPDATA) would have statements that identify the DNS to our system.

    To avoid confusion, you should keep the TCP/IP and Resolver configuration files in sync with each other.

Table 43. Local definitions available to resolver
File type description APIs affected Candidate files
Base resolver configuration files All APIs
  1. GLOBALTCPIPDATA
  2. RESOLVER_CONFIG environment variable
  3. /etc/resolv.conf
  4. SYSTCPD DD-name
  5. userid.TCPIP.DATA
  6. jobname.TCPIP.DATA
  7. SYS1.TCPPARMS(TCPDATA)
  8. DEFAULTTCPIPDATA
  9. TCPIP.TCPIP.DATA
Translate tables All APIs
  1. X_XLATE environment variable
  2. userid.STANDARD.TCPXLBIN
  3. jobname.STANDARD.TCPXLBIN
  4. hlq.STANDARD.TCPXLBIN
  5. Resolver-provided translate table, member STANDARD in SEZATCPX
Local host tables
endhostent
endnetent
getaddrinfo
gethostbyaddr
gethostbyname
gethostent
GetHostNumber
GetHostResol
GetHostString
getnameinfo
getnetbyaddr
getnetbyname
getnetent
IsLocalHost
Resolve
sethostent
setnetent
IPv4
  1. X_SITE environment variable
  2. X_ADDR environment variable
  3. /etc/hosts
  4. userid.HOSTS.xxxxINFO
  5. jobname.HOSTS.xxxxINFO
  6. hlq.HOSTS.xxxxINFO

IPv6

  1. GLOBALIPNODES
  2. RESOLVER_IPNODES environment variable
  3. userid.ETC.IPNODES
  4. jobname.ETC.IPNODES
  5. hlq.ETC.IPNODES
  6. DEFAULTIPNODES
  7. /etc/ipnodes

Note:
Table 43 is a partial copy from a table in Communications Server: IP Configuration Guide (SC31-8775). See that manual for the full table.

Host address is not resolved correctly

When you see problems where TCP/IP Resolver cannot resolve the host address properly, it is most likely due to a missing or incomplete resolver configuration file. A clear indication for this problem is the following message in lock.log:

clientip(0.0.0.0) <> callerip(<host IP address>)

To verify this, execute the fekfivpt TCP/IP IVP, as described in Installation verification. The resolver configuration section of the output will look like the following sample:

Resolver Trace Initialization Complete -> 2008/07/02 13:11:54.745964

res_init Resolver values:
 Global Tcp/Ip Dataset  = None
 Default Tcp/Ip Dataset = None
 Local Tcp/Ip Dataset   = /etc/resolv.conf
 Translation Table      = Default
 UserId/JobName         = USERID
 Caller API             = LE C Sockets
 Caller Mode            = EBCDIC

Ensure that the definitions in the file (or data set) referenced by "Local Tcp/Ip Dataset" are correct.

This field will be blank if you do not use a default name for the IP resolver file (using the z/OS UNIX search order). If so, add the following statement to rsed.envvars, where <resolver file> or <resolver data> represents the name of your IP resolver file:

RESOLVER_CONFIG=<resolver file>

or

RESOLVER_CONFIG='<resolver data set>'

Appendix C. Setting up INETD

This appendix is provided to assist you with some common problems that you may encounter when setting up INETD, or during checking or modifying an existing setup. INETD is used by Developer for System z for REXEC/SSH functionality.

The INETD daemon provides service management for an IP network. It reduces system load by invoking other daemons only when they are needed and by providing several simple internet services (such as echo) internally. INETD reads the inetd.conf configuration file to determine which extra services to provide. ETC.SERVICES is used to link the services to ports.

inetd.conf

The services that rely on INETD are defined in inetd.conf, which is read by INETD at startup time. The default location and name of inetd.conf is /etc/inetd.conf. A sample inetd.conf file can be found at /samples/inetd.conf.

The following syntax rules apply to inetd.conf entries:

Each entry consists of 7 positional fields, corresponding to the form:

service_name socket_type protocol wait_flag userid server_program
                        server_program_arguments

[ip_address:]service_name
ip_address is a local IP, followed by a colon (:). If specified, the address is used instead of INADDR_ANY or the current default. To specifically request INADDR_ANY, use "*:". If ip_address (or a colon) is specified without any other entries on the line, it becomes the default for subsequent lines until a new default is specified. service_name is a well-known or user-defined service name. The name specified must match one of the server names defined in ETC.SERVICES.
socket_type
stream or dgram, to indicate that a stream or datagram socket is used for the service.
protocol[,sndbuf=n[,rcvbuf=n]]

protocol can be tcp[4|6] or udp[4|6], and is used to further qualify the service name. Both the service name and the protocol must match an entry in ETC.SERVICES, except that the "4" or "6" should not be included in the ETC.SERVICES entry.

sndbuf and rcvbuf specify the size of the send and receive buffers. The size, represented by n, may be in bytes, or a "k" or "m" may be added to indicate kilobytes or megabytes respectively. sndbug and rcvbuf can be used in either order.

wait_flag[.max]

wait or nowait.wait indicates the daemon is single-threaded and another request will not be serviced until the first one completes. If nowait is specified, INETD issues an accept when a connect request is received on a stream socket. If wait is specified, it is the responsibility of the server to issue the accept if this is a stream socket.

max is the maximum number of users allowed to request service in a 60 second interval. The default is 40. If exceeded, the service's port is shut down.

userid[.group]

userid is the user ID that the forked daemon is to execute under. This user ID can be different than the INETD user ID. The permissions assigned to this user ID depend on the needs of the service. The INETD user ID needs BPX.DAEMON permission to switch the forked process to this user ID.

The optional group value, which is separated from userid by a dot (.), allows the server to run with a different group ID than the default for this user ID.

server_program
server_program is the full pathname of the service. For example, /usr/sbin/rlogind is the full pathname for the rlogind command.
server_program_arguments
Maximum of 20 arguments. The first argument is the server name.

ETC.SERVICES

INETD uses ETC.SERVICES to map port numbers and protocols to the services it must support. It can be either an MVS data set or z/OS UNIX file. A sample is shipped in SEZAINST(SERVICES), which is also available as /usr/lpp/tcpip/samples/services. The search order for ETC.SERVICES depends on INETD's startup method; z/OS UNIX or native MVS.

The following syntax rules apply to the services information specification:

Each entry consists of four positional fields, corresponding to the form:

service_name   port_number/protocol   aliases 

service_name
Specifies a well-known or user-defined service name
port_number
Specifies the socket port number used for the service
protocol
Specifies the transport protocol used for the service. Valid values are tcp and udp
aliases
Specifies a list of unofficial service names

Search order used in the z/OS UNIX environment

The search order used to access ETC.SERVICES in z/OS UNIX is the following. The search ends at the first file being found:

  1. /etc/services
  2. userid.ETC.SERVICES

    userid is the user ID that is used to start INETD

    .
  3. hlq.ETC.SERVICES

    hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.

Search order used in the native MVS environment

The search order used to access ETC.SERVICES in native MVS is the following. The search ends at the first data set being found:

  1. //SERVICES DD card

    The data set allocated to DD statement SERVICES is used

  2. userid.ETC.SERVICES

    userid is the user ID that is used to start INETD

    .
  3. jobname.ETC.SERVICES

    jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure

  4. hlq.ETC.SERVICES

    hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.

Note:
Starting INETD through BPXPATCH does not result in using the native MVS search order, since BPXBATCH executes the start command in the z/OS UNIX environment. The native MVS search order is only used when starting an MVS load module, such as SEZALOAD(FTP).

PROFILE.TCPIP port definitions

Do not confuse PORT (or PORTRANGE) definitions in PROFILE.TCPIP with ports defined in ETC.SERVICES since these definitions serve different purposes. Ports defined in PROFILE.TCPIP are used by TCPIP to see if the port is reserved for a certain service. ETC.SERVICES is used by INETD to map a port to a service.

When INETD receives a request on a monitored port, it forks a child process (with the requested service) called inetdx, where inetd is the job name for INETD (depends on the startup method) and x is a single digit number.

This complicates port reservation, so if an INETD monitored port is reserved in PROFILE.TCPIP, you should use the name of the started JCL procedure for the z/OS UNIX Kernel Address Space to allow almost any process to bind to the port. This name is typically OMVS, unless a different name is explicitly specified in the STARTUP_PROC parameter of the BPXPRMxx parmlib member.

The following list explains how to determine the job name, given the environment in which the application is run:

Note:
Although it is advised not to do so, ports defined in ETC.SERVICES may differ from the reserved port number for the service in PROFILE.TCPIP.

/etc/inetd.pid

The INETD process creates a temporary file, /etc/inetd.pid, which contains the PID (Process ID) of the currently executing INETD daemon. This PID value is used to identify syslog records that originated from the INETD process, and to provide the PID value for commands that require one, such as kill. It is also used as a lock mechanism to prevent more than 1 INETD process being active.

Startup

The z/OS UNIX implementation of INETD is located by default in /usr/sbin/inetd and supports two optional, non-positional, startup parameters:

/usr/sbin/inetd [-d] [inetd.conf] 

-d
Debug option. Debug output is written to stderr, which can be routed to a file by the syslogd daemon. Refer to Communications Server IP Configuration Guide (SC31-8775) for more information on syslogd. Note that when started this way, INETD will not fork a child process to start a service.
inetd.conf
Configuration file. Default value is /etc/inetd.conf

You should start INETD at IPL time. The most common way to do this is to start it from /etc/rc or /etc/inittab (z/OS 1.8 and higher only). It can also be started from a job or started task using BPXBATCH or from a shell session of a user with appropriate authority.

/etc/rc

When started from the z/OS UNIX initialization shell script, /etc/rc, INETD uses the z/OS UNIX search order to find ETC.SERVICES. A sample /etc/rc file is shipped as /samples/rc. The following sample commands can be used to start INETD:

# Start INETD
_BPX_JOBNAME='INETD' /usr/sbin/inetd /etc/inetd.conf &
sleep 5

/etc/inittab

z/OS 1.8 and higher provide an alternative method, /etc/inittab, for issuing commands during z/OS UNIX initialization. /etc/inittab allows the definition of the respawn parameter, which restarts the process automatically when it ends (a WTOR is sent to the operator for a second restart within 15 minutes). When started from /etc/inittab, INETD uses the z/OS UNIX search order to find ETC.SERVICES. A sample /etc/inittab is shipped as /samples/inittab. The following sample command can be used to start INETD:

# Start INETD
inetd::respfrk:/usr/sbin/inetd /etc/inetd.conf

Note:
Be aware that the respfrk parameter used in the sample will transfer the respawn attribute to all forked processes, including RSE. When the client closes the connection, respawn will start it up again. The RSE server will end again later, due to timeout. Refer to UNIX System Services Planning (GA22-7800) to learn more about inittab.

BPXBATCH

The BPXBATCH startup method works both for started tasks and user jobs. Note that INETD is a background process, so the BPXBATCH step starting INETD will end within seconds after startup. When started by BPXBATCH, INETD uses the z/OS UNIX search order to find ETC.SERVICES. The JCL listed in the following code sample is a sample procedure to start INETD (the KILL step removes an active INETD process, if any):

Figure 57. INETD startup JCL
//INETD    PROC PRM=
//*
//KILL     EXEC PGM=BPXBATCH,REGION=0M,
//         PARM='SH ps -e | grep inetd | cut -c 1-10 | xargs -n 1 kill'
//*
//INETD    EXEC PGM=BPXBATCH,REGION=0M,
//            PARM='PGM /usr/sbin/inetd &PRM'
//STDERR   DD SYSOUT=*
//* STDIN, STDOUT and STDENV are defaulted to /dev/null
//*

Notes:
  1. STDIN, STDOUT and STDERR must be z/OS UNIX files when allocated. STDENV can be either a MVS data set or a z/OS UNIX file. Since z/OS 1.7, SYSOUT can be assigned to STDOUT and STDERR. Refer to UNIX System Services Command Reference (SA22-7802) to learn more about BPXBATCH.
  2. inetd.conf can be a MVS data set or member when INETD is started by BPXBATCH. To do so, code the PARM statement like the following sample (use only single quotes (')):
    //  PARM='PGM /usr/sbin/inetd //''SYS1.TCPPARMS(INETCONF)'' &PRM'

Shell session

When started from within a shell session, INETD uses the z/OS UNIX search in order to find ETC.SERVICES. The following sample commands can be used (by a person with sufficient authority) to stop and start INETD (# is the z/OS UNIX prompt):

# ps -e | grep inetd
      7 ?         0:00 /usr/sbin/inetd
# kill 7
# _BPX_JOBNAME='INETD' /usr/sbin/inetd &
Note:
This method is not advisable for the initial startup, /etc/rc or /etc/inittab are more appropriate since they are executed when z/OS UNIX initializes.

Security

INETD is a z/OS UNIX process and therefore requires valid OMVS definitions in the security software for the user ID associated with INETD. UID, HOME, and PROGRAM must be set for the user ID, together with the GID for the user's default group. If INETD is started by /etc/rc or /etc/inittab, the user ID is inherited from the z/OS UNIX kernel, default OMVSKERN.

ADDGROUP OMVSGRP OMVS(GID(1))
ADDUSER OMVSKERN DFLTGRP(OMVSGRP) NOPASSWORD +
        OMVS(UID(0) HOME('/') PROGRAM('/bin/sh'))

INETD is a daemon that requires access to functions such as setuid(). Therefore the user ID used to start INETD requires READ access to the BPX.DAEMON profile in the FACILITY class. If this profile is not defined, UID 0 is mandatory.

PERMIT BPX.DAEMON CLASS(FACILITY) ACCESS(READ) ID(OMVSKERN)

The INETD user ID also requires EXECUTE permission for the inetd program (/usr/sbin/inetd), READ access to your inetd.conf and ETC.SERVICES file and WRITE access to /etc/inetd.pid. If you want to run INETD without UID 0, you can give CONTROL access to the SUPERUSER.FILESYS profile in the UNIXPRIV class to provide the necessary permits for z/OS UNIX files.

Programs requiring daemon authority must be program controlled if BPX.DAEMON is defined in the FACILITY class. This is already done for the default INETD program (/usr/sbin/inetd), but must be set manually if you use a copy or a custom version. Use the extattr +p command to make a z/OS UNIX file program controlled. Use the RACF PROGRAM class to make an MVS load module program controlled.

System programmers who need to restart INETD from within their shell session will start INETD using their permits. Therefore, they must have the same list of permits as the regular INETD user ID. On top of that, they also need permits to list and stop the INETD process. This can be accomplished in multiple ways.

Refer to UNIX System Services Command Reference (SA22-7802) to learn more about the extattr and su commands. Refer to UNIX System Services Planning (GA22-7800) to learn more about the UNIXPRIV class and BPX.* profiles in the FACILITY class. Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on the OMVS segment definitions and the PROGRAM class.

Developer for System z requirements

Developer for System z is dependent upon INETD for managing REXEC and/or SSH. It might also impose extra requirements on top of the INETD setup described above.

REXEC (or SSH) is used for the following two purposes, as described in (Optional) Using REXEC (or SSH).

The remote actions in z/OS UNIX subprojects do not require special settings. The alternative RSE startup method however does require special settings.

INETD

INETD's environmental settings, which are passed on when starting a process, and the permissions for INETD's user ID must be set properly in order for INETD to start the RSE server.

REXEC (or SSH)

The REXEC (or SSH) daemon that is started by INETD when a client connects to port 512 (or 22, respectively) is used to perform authentication, start the RSE server, and return the port number for further communication back to the client. In order to do so, the user ID assigned to the REXEC (or SSH) daemon (in inetd.conf) requires the following permissions:

Appendix D. Setting up APPC

This appendix is provided to assist you with some common problems that you may encounter when setting up APPC (Advanced Program-to-Program Communication), or during checking or modifying an existing setup.

Refer to MVS Planning: APPC/MVS Management (SA22-7599) and MVS Initialization and Tuning Reference (SA22-7592) for additional information on APPC management and the parmlib members discussed below.

Note that this does not cover a complete set-up of APPC, it just highlights some key aspects that might be applicable to your site.

Member SYS1.SAMPLIB(ATBALL) contains a list and descriptions of all APPC-related (sample) members in SYS1.SAMPLIB.

VSAM

APPC/MVS stores its configuration data in the following SYS1.PARMLIB members and two VSAM data sets:

A TP is an application program that uses APPC to communicate with a TP on the same or another system to access resources. The APPC setup for Developer for System z activates a new TP called FEKFRSRV, which is referred to as the TSO Commands service.

The following job is a concatenation of sample members SYS1.SAMPLIB(ATBTPVSM) and SYS1.SAMPLIB(ATBSIVSM), and can be used to define the APPC VSAMs.

Figure 58. JCL to create APPC VSAMs
//APPCVSAM JOB <job parameters>
//*
//* CAUTION: This is neither a JCL procedure nor a complete job.
//* Before using this sample, you will have to make the following
//* modifications:
//* 1.  Change the job parameters to meet your system requirements.
//* 2.  Change ****** to the volume that will hold the APPC VSAMs.
//*
//TP       EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
   DEFINE CLUSTER (NAME(SYS1.APPCTP) -
                   VOLUME(******) -
                   INDEXED REUSE -
                   SHAREOPTIONS(3 3) -
                   RECORDSIZE(3824 7024) -
                   KEYS(112 0) -
                   RECORDS(300 150)) -
          DATA    (NAME(SYS1.APPCTP.DATA)) -
          INDEX   (NAME(SYS1.APPCTP.INDEX))
//*
//SI       EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
   DEFINE CLUSTER (NAME(SYS1.APPCSI) -
                   VOLUME(******) -
                   INDEXED REUSE -
                   SHAREOPTIONS(3 3) -
                   RECORDSIZE(248 248) -
                   KEYS(112 0) -
                   RECORDS(50 25)) -
          DATA    (NAME(SYS1.APPCSI.DATA)) -
          INDEX   (NAME(SYS1.APPCSI.INDEX))
//*

VTAM

APPC is an implementation of the Systems Network Architecture (SNA) LU 6.2 protocol. SNA provides formats and protocols that define a variety of physical and logical SNA components, such as the Logical Unit (LU). LU 6.2 is a type of logical unit that is specifically designed to handle communications between application programs.

In order to use SNA on MVS, you need to install and configure VTAM (Virtual Telecommunications Access Method). VTAM must be active before the APPC system tasks can be used.

The APPC-specific part of the VTAM setup consists of three steps:

  1. Define the mode-name used (for example, APPCHOST) to VTAM by using SYS1.SAMPLIB(ATBLJOB) to assemble and link edit SYS1.SAMPLIB(ATBLMODE) into your SYS1.VTAMLIB. See member SYS1.SAMPLIB(ATBLMODE) for details.
  2. Define APPC/MVS as a VTAM application by copying sample member SYS1.SAMPLIB(ATBAPPL) to a dataset in the SYS1.VTAMLST concatenation. See member SYS1.SAMPLIB(ATBAPPL) for details.
  3. Use console command v net,act,id=atbappl to activate the newly defined application (where net equals the name of your VTAM started task). Use console command d net,appls to verify that the application is active. Add the member name to SYS1.VTAMLST(ATCCONxx) if you want it to be activated when VTAM starts.

The ACBNAME of MVSLU01 used in sample member SYS1.SAMPLIB(ATBAPPL) can be changed to match site standards, but must match the definitions in the SYS1.PARMLIB(APPCPMxx) member.

Figure 59. SYS1.SAMPLIB(ATBAPPL)
MVSLU01 APPL   ACBNAME=MVSLU01,                                        C
               APPC=YES,                                               C
               AUTOSES=0,                                              C
               DDRAINL=NALLOW,                                         C
               DLOGMOD=APPCHOST,                                       C
               DMINWNL=5,                                              C
               DMINWNR=5,                                              C
               DRESPL=NALLOW,                                          C
               DSESLIM=10,                                             C
               LMDENT=19,                                              C
               MODETAB=LOGMODES,                                       C
               PARSESS=YES,                                            C
               SECACPT=CONV,                                           C
               SRBEXIT=YES,                                            C
               VPACING=1

Refer to Communications Server IP SNA Network Implementation Guide (SC31-8777) for more information on configuring VTAM.

SYS1.PARMLIB(APPCPMxx)

To enable and support the flow of conversations between systems, sites must define Logical Units (LUs) between which sessions can bind. A site needs to define at least one LU before APPC/MVS processing can take place, even when APPC processing remains on a single system. LUs are some of the definitions done in SYS1.PARMLIB(APPCPMxx).

The TSO Commands service requires that APPC is set up to have a base LU that can handle both inbound and outbound requests.

The LU definition must be added to the SYS1.PARMLIB(APPCPMxx) member and needs to include the BASE and SCHED(ASCH) parameters. The APPCPMxx member also specifies which transaction profile (TP) and side information (SI) VSAM data sets will be used.

The following code sample is a SYS1.PARMLIB(APPCPMxx) member that can be used for the TSO Commands service.

Figure 60. SYS1.PARMLIB(APPCPMxx)
LUADD
  ACBNAME(MVSLU01)
  BASE
  SCHED(ASCH)
  TPDATA(SYS1.APPCTP)
SIDEINFO DATASET(SYS1.APPCSI)

When a system has multiple LU names, you might have to make changes depending on which LU the system selects as the BASE LU. The BASE LU for the system is determined by the following:

  1. The system base LU is represented by the last LUADD statement that contains both the NOSCHED and BASE parameters. This type of system base LU allows outbound requests to be processed when no transaction schedulers are active.
  2. If no LUADD statements contain both NOSCHED and BASE, the system base LU is represented by the last LUADD statement that contains the BASE parameter and specifies ASCH as APPC/MVS transaction scheduler. This can be done by either coding SCHED(ASCH) or not coding the SCHED parameter at all (ASCH is the default value for SCHED).
    Note:
    Operator command D APPC,LU,ALL will show all active LU definitions and mark the base LU.

If your system has a LU with BASE and NOSCHED parameters, this LU would be used as the BASE LU but the TSO Command service will not work because this LU does not have a transaction scheduler to handle requests to the FEKFRSRV transaction. If this LU cannot be changed to remove the NOSCHED parameter, the rsed.envvars environment variable _FEKFSCMD_PARTNER_LU can be set to the LU that has BASE and SCHED(ASCH), such as:

_FEKFSCMD_PARTNER_LU=MVSLU01

See rsed.envvars, RSE configuration file for more information on rsed.envvars.

SYS1.PARMLIB(ASCHPMxx)

The APPC/MVS transaction scheduler (default name is ASCH) initiates and schedules transaction programs in response to inbound requests for conversations. Member SYS1.PARMLIB(ASCHPMxx) controls its functioning, for example, with transaction class definitions.

The APPC transaction class used for the TSO Commands service must have enough APPC initiators to allow one initiator for each user of Developer for System z.

The TSO Commands service also needs the default specifications to be specified in the OPTIONS and TPDEFAULT sections.

The following code sample is a SYS1.PARMLIB(ASCHPMxx) member that can be used for the TSO Commands service.

Figure 61. SYS1.PARMLIB(ASCHPMxx)
CLASSADD
  CLASSNAME(A)
  MAX(20)
  MIN(1)
  MSGLIMIT(200)

OPTIONS
  DEFAULT(A)

TPDEFAULT
  REGION(2M)
  TIME(5)
  MSGLEVEL(1,1)
  OUTCLASS(X)
Notes:
  1. For debugging purposes, the IBM support center might ask you to increase the value of MSGLIMIT, so that more output is written to the log file.
  2. Operator command D ASCH,ALL will show all active APPC transaction scheduler classes.

Activating APPC changes

The configuration changes documented in the steps above can now be activated. This can be done in various ways, depending on the circumstances:

Console commands D APPC and D ASCH can be used to verify the APPC setup. Refer to MVS System Commands (GC28-1781) for more information on the mentioned console commands.

Defining the TSO Commands service transaction

Once APPC/MVS is active, the Developer for System z TSO Commands service can be defined, as described in (Optional) APPC transaction for the TSO Commands service.

The documented way to define the APPC transaction is by customizing and submitting FEK.#CUST.JCL(FEKAPPCC).

The APPC transaction can also be defined interactively through the APPC ISPF interface, which is documented in a whitepaper. This whitepaper also describes how to set up the APPC transaction to collect user-specific accounting information.

The APPC and WebSphere Developer for System z (SC23-5885-00) whitepaper is available at the Developer for System z internet library, http://www-306.ibm.com/software/awdtools/devzseries/library/.

Note:
The Transaction Program (TP) JCL that is used by APPC to start the TSO Commands service has changed in Developer for System z version 7.1. If you follow the directions in the whitepaper to define the TP, you must add the NESTMACS keyword to the PARM line, for example:
//  PARM='ISPSTART CMD(%FEKFRSRV TIMEOUT=60) NEWAPPL(ISR) NESTMACS'

(Optional) Alternative setup options

Developer for System z supports alternative APPC and VTAM setup options, some of which are documented in this section.

Alternative transaction name

The default transaction name for the TSO Commands service is FEKFRSRV, as described in (Optional) APPC transaction for the TSO Commands service. As described in the same section, this name can be changed when you define the transaction to APPC.

Note that changing the transaction name in APPC implies that the new name must be assigned to _FEKFSCMD_TP_NAME_ in rsed.envvars, as described in rsed.envvars, RSE configuration file.

Multiple LUs

APPC is a communication protocol that lets a program (the partner node) interact with a program on the host (the local node). With Developer for System z, both the partner node (TSO Commands server) and the local node (RSE server) are active on the same z/OS system. And by default, they both use the same (BASE) LU definition to communicate with each other.

You can specify an alternative partner LU name for the TSO Commands service in the _FEKFSCMD_PARTNER_LU_ directive of rsed.envvars, as described in rsed.envvars, RSE configuration file. Note that you cannot change the local LU, which must always be a valid BASE LU (have the BASE and SCHED keywords).

LU security

VTAM supports a secure APPC setup, where the communication between the partner and local LU must be defined to the security software.

This is activated by adding VERIFY=REQUIRED to the VTAM definition of the local (BASE) LU. The security definitions must be done in the APPCLU class, as described in MVS Planning: APPC/MVS Management (SA22-7599).

Note that when this setup is active in VTAM, and the setup in your security software is not completed, the communication with the TSO commands service will fail to initialize without any message in the system log indicating that VTAM refused to set up the connection. The APPC IVP test (fekfivpa) will fail with message "Return code 1 - Allocate Failure no retry".

Appendix E. Requisites

This appendix lists the host prerequisites and corequisites for this version of Developer for System z.

Refer to Rational Developer for System z Prerequisites (SC23-7659) in the Developer for System z online library at http://www-01.ibm.com/software/awdtools/rdz/library/ for an up-to-date list of required and optional requisites.

The products listed in this section are all available at the time of publication for this manual. See the IBM Software Support Lifecycle Web site http://www.ibm.com/software/support/lifecycle/, to see whether a selected product is still available at the time that you want to use the related Developer for System z function.

z/OS host prerequisites

Use of Developer for System z requires that you have the following environment with the appropriate prerequisites:

z/OS

One of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5694-A01 z/OS v 1.11

ISPF:

  • APAR OA27721 (TSO/ISPF Client Gateway)
    PTF UA48038

TCP/IP:

  • No PTF or Service Level required
5694-A01 z/OS v 1.10

ISPF:

  • APAR OA27721 (TSO/ISPF Client Gateway)
    PTF UA48037

TCP/IP:

  • APAR PK74282 (CSM fixed storage growth)
    PTF UK41810
5694-A01 z/OS v 1.9

ISPF:

  • APAR OA27721 (TSO/ISPF Client Gateway)
    PTF UA48036

TCP/IP:

  • APAR PK74282 (CSM fixed storage growth)
    PTF UK41812
5694-A01 z/OS v 1.8

ISPF:

  • APAR OA20345 (nested command output)
    PTF UA33575
  • APAR OA20449 (add NESTMACS support)
    PTF UA34052
  • APAR OA27721 (TSO/ISPF Client Gateway)
    PTF UA48017

TCP/IP:

  • APAR PK74282 (CSM fixed storage growth)
    PTF UK41811

The related product Web site is:

http://www-03.ibm.com/systems/z/os/zos/
Notes:
  1. Remote (host-based) actions for z/OS UNIX subprojects require that the z/OS UNIX version of REXEC or SSH is active on the host.
  2. z/OS includes the following components, which need to be installed, configured, and operational:

SMP/E

In order to install Developer for System z, one of the following levels must be installed:

Program Number Product Name PTFs or Service Levels Required
5655-G44 IBM System Modification Program Extended (SMP/E) for z/OS v 3.5 No PTF or Service Level required
5655-G44 IBM System Modification Program Extended (SMP/E) for z/OS v 3.4 No PTF or Service Level required

The related product Web site is as follows:

http://www-03.ibm.com/systems/z/os/zos/smpe/

SDK for z/OS Java 2 Technology Edition

In order to support applications that use Remote Systems Explorer (RSE), one of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5655-R31 IBM 31 bit SDK for z/OS, Java 2 Technology Edition, v 6.0 No PTF or Service Level required
5655-N98 IBM 31 bit SDK for z/OS, Java 2 Technology Edition, v 5.0 APAR PK54746 (bind to wrong address), Java 5.0 service release 7

The related product Web site is:

http://www.ibm.com/servers/eserver/zseries/software/java/
Attention: The 64 bit version is not supported.

z/OS host corequisites

The products listed in this section and other stated software are required to support specific features of Developer for System z. The Developer for System z workstation client can be successfully installed without these requisites. However, a stated host requisite must be installed and operational at run time for the corresponding feature to work as designed.

z/OS

Program Number Product Name PTFs or Service Levels Required
5694-A01 z/OS v 1.11

HLASM

No PTF or Service Level required

XL C/C++

No PTF or Service Level required

SCLM

No PTF or Service Level required

LE (PL/I)

No PTF or Service Level required
5694-A01 z/OS v 1.10

HLASM

No PTF or Service Level required

XL C/C++

No PTF or Service Level required

SCLM

  • APAR OA26997 (enable member security)
    PTF number not yet available

LE (PL/I)

No PTF or Service Level required
5694-A01 z/OS v 1.9

HLASM

No PTF or Service Level required

XL C/C++

No PTF or Service Level required

SCLM

  • APAR OA27379 (SCLM Search and member security)
    PTF UA46330 + UA46331, UA46332, UA46333, UA46334
    (language dependant)
  • APAR OA26997 (enable member security)
    PTF number not yet available

LE (PL/I)

No PTF or Service Level required
5694-A01 z/OS v 1.8

HLASM

No PTF or Service Level required

XL C/C++

No PTF or Service Level required

SCLM

  • APAR OA21104 (informational build mode)
    PTF UA35046 + UA35056, UA35057, UA35058, or
    UA35059 (language-dependent)
  • APAR OA16924 (enhance SCLMINFO)
    PTF UA29772 + UA29922, UA29923, UA29924, or
    UA29925 (language-dependent)
  • APAR OA16804 (add surrogate userid support)
    PTF UA33524 + UA33533, UA33534, UA33535, or
    UA33536 (language-dependent)

LE (PL/I)

  • APAR PK41552 (new PL/I messages for
    Developer for System z )
    PTF UK24482 (English) or UK24483 (Japanese)

The related product Web site is:

http://www-03.ibm.com/systems/z/os/zos/
Note:
JES3 v 1.10 or higher is a corequisite for JES3 users who want to use the Job Monitor support for viewing the output of active jobs.
  1. High Level Assembler (HLASM) must be installed on the host with the listed service level, in order to compile assembler programs developed or edited within Developer for System z.

    The related product Web site is:

  2. The XL C/C++ compiler must be installed on the host with the listed service level, in order to compile C/C++ programs developed or edited within Developer for System z.

    The related product Web site is:

  3. SCLM must be installed on the host with the listed service level, in order to support SCLM Developer Toolkit.

    The related product Web site is:

    Note:
    • APAR OA16804 is only required if you want to use secure build, promote, and deploy.
    • APAR OA26997 is only required for member security support.
    • APAR OA27379 is only required for member security support or SCLM search functionality.
  4. Language Environment must be installed on the host with the listed service level, in order to support Enterprise Service Tools for PL/I.

    The related product Web site is:

COBOL compiler

To compile COBOL programs developed or edited within Developer for System z , one of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5655-S71 IBM Enterprise COBOL for z/OS v 4.1 No PTF or Service Level required
5535-G53 IBM Enterprise COBOL for z/OS v 3.4 No PTF or Service Level required

The related product Web site is:

http://www.ibm.com/software/awdtools/cobol/zos/
Note:
IBM Enterprise COBOL for z/OS v 4.1 is required for Enterprise Service Tools to generate Compiled XML Conversion that uses the XMLSS-based XML PARSE capability in COBOL v 4.1.

PL/I compiler

To compile PL/I programs developed or edited within Developer for System z, one of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5655-H31 IBM Enterprise PL/I for z/OS v 3.8 No PTF or Service Level required
5655-H31 IBM Enterprise PL/I for z/OS v 3.7 No PTF or Service Level required
5655-H31 IBM Enterprise PL/I for z/OS v 3.6 No PTF or Service Level required
5655-H31 IBM Enterprise PL/I for z/OS v 3.5 No PTF or Service Level required

The related product Web site is:

http://www.ibm.com/software/awdtools/pli/plizos/
Note:
PL/I v 3.6 or higher is a prerequisite for Enterprise Service Tools for PL/I.

Debug Tool for z/OS

To support remote debugging from Developer for System z, one of the following levels must be installed on the host:

Program Number Product Name Programming Language APARs, PTFs, or Service Levels Required
5655-U27 IBM Debug Tool for z/OS V9.1 COBOL, PL/I, C/C++, assembler, and additional features all available maintenance
5655-S16 IBM Debug Tool Utilities and Advanced Functions for z/OS V8.1.0 COBOL, PL/I, C/C++, assembler, and additional features all available maintenance
5655-S17 IBM Debug Tool for z/OS V8.1.0 COBOL, PL/I, Assembler, C/C++ all available maintenance
5655-R45 IBM Debug Tool Utilities and Advanced Functions for z/OS V7.1.0 COBOL, PL/I, C/C++, assembler, and additional features all available maintenance
5655-R44 IBM Debug Tool for z/OS V7.1.0 COBOL, PL/I, Assembler, C/C++ all available maintenance

The related product Web site is:

http://www.ibm.com/software/awdtools/debugtool/
Note:
Debug Tool Utilities and Advanced Functions (DTU&AF) is a superset of Debug Tool.

Starting with version 9, Debug Tool for z/OS and Debug Tool Utilities and Advanced Functions have been merged into a single offering.

CICS Transaction Server

To support applications with embedded CICS statements, one of the following levels must be installed:

Program Number Product Name PTFs or Service Levels Required
5655-S97 IBM CICS Transaction Server for z/OS v 4.1 No PTF or Service Level required
5697-E93 IBM CICS Transaction Server for z/OS v 3.2 UK34221
5697-E93 IBM CICS Transaction Server for z/OS v 3.1 UK15767, UK15764, UK11782, UK11294, UK12233, UK12521, UK15261, UK15271, UK34221, UK34078

The related product Web site is:

http://www.ibm.com/software/htp/cics/tserver/
Notes:
  1. The CICS Transaction Server requires additional configuration to work with the debug tool.
  2. The RESTful interface available in CICS Transaction Server v 4.1 or higher is required to support Application Deployment Manager, Service Component Architecture, and Enterprise Service Tools features that are new to IBM Rational Developer for System z v 7.6 or higher.
  3. CICS Transaction Server v 3.2 or higher is required to support many features of Enterprise Service Tools.

    For the complete list of specifics on runtime requirements refer to the Enterprise Service Tools documentation the IBM Rational Developer for System z Information Center at http://publib.boulder.ibm.com/infocenter/ratdevz/v7r6/.

  4. CICS Transaction Server v 3.1 with service UK34221 is the minimum for Application Deployment Manager.

IMS

To support applications using IMS database and data communications, one of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5635-A02 IBM IMS v 11.1 No PTF or Service Level required
5635-A01 IBM IMS v 10.1 No PTF or Service Level required
5655-J38 BM IMS v 9.1 No PTF or Service Level required

The related product Web site is:

http://www.ibm.com/software/data/ims/ims/
Notes:
  1. IMS requires additional configuration to work with the debug tool.
  2. Version 10.1 or higher of IMS, IMS Connect, and IMS SOAP Gateway are required for Enterprise Service Tools.

DB2 for z/OS

To support DB2, one of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5635-DB2 IBM DB2 for z/OS v 9.1 No PTF or Service Level required
5625-DB2 IBM DB2® Universal Database™ for z/OS v 8.1 No PTF or Service Level required

The related product Web site is:

http://www.ibm.com/software/data/db2/zos/

Rational Team Concert for System z

For Jazz-based source control using Developer for System z remote projects, the following level must be installed.

Program Number Product Name
5724-V82 Rational Team Concert for System z Server v 2.0

The related product Web site is:

http://www-01.ibm.com/software/awdtools/rtcz/
Note:
Rational Team Concert Server v 1.0 or Rational Team Concert for System z Server v 1.0.1 provides selective support for some Developer for System z functions such as local projects. We recommend Rational Team Concert for System z Server v 2.0 for a more integrated and full featured experience

File Manager

To support File Manager integration, one of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5655-U29 IBM File Manager for z/OS v 10.1 No PTF or Service Level required

The related product Web site is:

http://www.ibm.com/software/awdtools/filemanager/

Fault Analyzer

To support Fault Analyzer integration, the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5655-U28 IBM Fault Analyzer v 9.1 No PTF or Service Level required

The related product Web site is as follows:

http://www.ibm.com/software/awdtools/faultanalyzer/

REXX

To use SCLM Developer Toolkit, one of the following levels must be installed on the host:

Program Number Product Name PTFs or Service Levels Required
5695-014 IBM Library for REXX on zSeries v 1.4 No PTF or Service Level required
5695-014 IBM Library for REXX on zSeries Alternate Library v 1.4.0 (FMIDs HWJ9143, JWJ9144) No PTF or Service Level required

A version of the REXX/370 Alternate Library is available from the product Web site:

http://www.ibm.com/software/awdtools/rexx/rexxzseries/

Ported tools

IBM Ported Tools for z/OS must be installed (in z/OS UNIX) to use sftp or scp to do secure deployment in SCLM Developer Toolkit.

A version of IBM Ported Tools for z/OS is available from the product Web site:

http://www-03.ibm.com/servers/eserver/zseries/zos/unix/port_tools.html

Ant

Apache Ant must be installed (in z/OS UNIX) to do JAVA/J2EE builds in SCLM Developer Toolkit.

Apache Ant is an open-source, Java-based build tool that you can download from the product Web site:

http://ant.apache.org/

Bibliography

Referenced publications

The following publications are referenced in this document:

Table 44. Referenced publications
Publication title Order number Reference Reference Web site
Java Diagnostic Guide SC34-6650 Java 5.0 http://www.ibm.com/developerworks/java/jdk/diagnosis/
Java SDK and Runtime Environment User Guide / Java 5.0 http://www-03.ibm.com/servers/eserver/zseries/software/java/
Program Directory for IBM Rational Developer for System z GI11-8298 Developer for System z http://www-306.ibm.com/software/awdtools/rdz/library/
Rational Developer for System z Common Access Repository Manager Developer's Guide SC23-7660 Developer for System z http://www-306.ibm.com/software/awdtools/rdz/library/
Rational Developer for System z Prerequisites SC23-7659 Developer for System z http://www-306.ibm.com/software/awdtools/rdz/library/
Rational Developer for System z Host Configuration Quick Start GI11-9201 Developer for System z http://www-306.ibm.com/software/awdtools/rdz/library/
Rational Developer for System z Host Planning Guide GI11-8296 Developer for System z http://www-306.ibm.com/software/awdtools/rdz/library/
SCLM Developer Toolkit Administrator's Guide SC23-9801 Developer for System z http://www-306.ibm.com/software/awdtools/rdz/library/
APPC and WebSphere Developer for System z SC23-5885 Whitepaper http://www-306.ibm.com/software/awdtools/rdz/library/
Communications Server IP Configuration Guide SC31-8775 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Communications Server IP Configuration Reference SC31-8776 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Communications Server IP Diagnosis Guide GC31-8782 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Communications Server IP System Administrator's Commands SC31-8781 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Communications Server SNA Network Implementation Guide SC31-8777 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Communications Server SNA Operations SC31-8779 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Cryptographic Services System SSL Programming SC24-5901 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
DFSMS™ Macro Instructions for Data Sets SC26-7408 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
DFSMS Using data sets SC26-7410 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Language Environment Customization SA22-7564 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Language Environment Debugging Guide GA22-7560 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
MVS Initialization and Tuning Guide SA22-7591 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
MVS Initialization and Tuning Reference SA22-7592 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
MVS JCL Reference SA22-7597 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
MVS Planning APPC/MVS Management SA22-7599 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
MVS Planning Workload Management SA22-7602 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
MVS System Commands SA22-7627 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Security Server RACF Command Language Reference SA22-7687 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Security Server RACF Security Administrator's Guide SA22-7683 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
TSO/E Customization SA22-7783 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
TSO/E REXX Reference SA22-7790 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
UNIX System Services Command Reference SA22-7802 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
UNIX System Services Planning GA22-7800 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
UNIX System Services User's Guide SA22-7801 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Using REXX and z/OS UNIX System Services SA22-7806 z/OS 1.9 http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
Resource Definition Guide SC34-6430 CICSTS 3.1 http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html
Resource Definition Guide SC34-6815 CICSTS 3.2 http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html
Resource Definition Guide SC34-7000 CICSTS 4.1 https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp?topic=/com.ibm.cics.ts.home.doc/library/library_html.html
RACF Security Guide SC34-6454 CICSTS 3.1 http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html
RACF Security Guide SC34-6835 CICSTS 3.2 http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html
RACF Security Guide SC34-7003 CICSTS 4.1 https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp?topic=/com.ibm.cics.ts.home.doc/library/library_html.html
Language Reference SC27-1408 Enterprise COBOL for z/OS http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html

The following Web sites are referenced in this document:

Table 45. Referenced Web sites
Description Reference Web site
Developer for System z Information Center http://publib.boulder.ibm.com/infocenter/ratdevz/v7r6/index.jsp
Developer for System z Support http://www-306.ibm.com/software/awdtools/rdz/support/
Developer for System z Library http://www-306.ibm.com/software/awdtools/rdz/library/
Developer for System z home page http://www-306.ibm.com/software/awdtools/rdz/
Developer for System z enhancement request https://www.ibm.com/developerworks/support/rational/rfe/
z/OS internet library http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
CICSTS Information Center https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp
Download Apache Ant http://ant.apache.org/
Java keytool documentation http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html
CA support home page https://support.ca.com/

Informational publications

The following publications can be helpful in understanding setup issues for requisite host components:

Table 46. Informational publications
Publication title Order number Reference Reference Web site
ABCs of z/OS System Programming Volume 9 (z/OS UNIX) SG24-6989 Redbook http://www.redbooks.ibm.com/
TCPIP Implementation Volume 3: High Availability, Scalability, and Performance SG24-7534 Redbook http://www.redbooks.ibm.com/
TCP/IP Implementation Volume 4: Security and Policy-Based Networking SG24-7535 Redbook http://www.redbooks.ibm.com/

Glossary

A

Action ID
A numeric identifier for an action between 0 and 999
Application Server

  1. A program that handles all application operations between browser-based computers and an organization's back-end business applications or databases. There is a special class of Java-based appservers that conform to the J2EE standard. J2EE code can be easily ported between these appservers. They can support JSPs and servlets for dynamic Web content and EJBs for transactions and database access.
  2. The target of a request from a remote application. In the DB2 environment, the application server function is provided by the distributed data facility and is used to access DB2 data from remote applications.
  3. A server program in a distributed network that provides the execution environment for an application program.
  4. The target of a request from an application requester. The database management system (DBMS) at the application server site provides the requested data.
  5. Software that handles communication with the client requesting an asset and queries of the Content Manager.

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. This definition is from the Localization Industry Standards Association (LISA) Glossary.
Bidirectional Attribute
Text type, text orientation, numeric swapping, and symmetric swapping.
Build Request
A request from the client to perform a build transaction.
Build Transaction
A job started on MVS to perform builds after a build request has been received from the client.

C

Compile
  1. In Integrated Language Environment (ILE) languages, to translate source statements into modules that then can be bound into programs or service programs.
  2. To translate all or part of a program expressed in a high-level language into a computer program expressed in an intermediate language, an assembly language, or a machine language.
Container
  1. In CoOperative Development Environment/400, a system object that contains and organizes source files. An i5/OS® library or an MVS-partitioned data set are examples of a container.
  2. In J2EE, an entity that provides life-cycle management, security, deployment, and runtime services to components. (Sun) Each type of container (EJB, Web, JSP, servlet, applet, and application client) also provides component-specific services
  3. In Backup Recovery and Media Services, the physical object used to store and move media such as a box, a case, or a rack.
  4. In a virtual tape server (VTS), a receptacle in which one or more exported logical volumes (LVOLs) can be stored. A stacked volume containing one or more LVOLs and residing outside a VTS library is considered to be the container for those volumes.
  5. A physical storage location of the data. For example, a file, directory, or device.
  6. A column or row that is used to arrange the layout of a portlet or other container on a page.
  7. An element of the user interface that holds objects. In the folder manager, an object that can contain other folders or documents.

D

Database
A collection of interrelated or independent data items that are stored together to serve one or more applications.
Data Definition View
Contains a local representation of databases and their objects and provides features to manipulate these objects and export them to a remote database
Data Set
The major unit of data storage and retrieval, consisting of a collection of data in one of several prescribed arrangements and described by control information to which the system has access.
Debug
To detect, diagnose, and eliminate errors in programs.
Debugging Session
The debugging activities that occur between the time that a developer starts a debugger and the time that the developer exits from it.

E

Error Buffer
A portion of storage used to hold error output information temporarily.

F

G

Gateway
  1. A middleware component that bridges Internet and intranet environments during Web service invocations.
  2. Software that provides services between the endpoints and the rest of the Tivoli® environment.
  3. A component of a Voice over Internet Protocol that provides a bridge between VoIP and circuit-switched environments.
  4. A device or program used to connect networks or systems with different network architectures. The systems may have different characteristics, such as different communication protocols, different network architecture, or different security policies, in which case the gateway performs a translation role as well as a connection role.

H

I

Interactive System Productivity Facility (ISPF)
An IBM licensed program that serves as a full-screen editor and dialog manager. Used for writing application programs, it provides a means of generating standard screen panels and interactive dialogs between the application programmer and terminal user. ISPF consists of four major components: DM, PDF, SCLM, and C/S. The DM component is the Dialog Manager, which provides services to dialogs and end-users. The PDF component is the Program Development Facility, which provides services to assist the dialog or application developer. The SCLM component is the Software Configuration Library Manager, which provides services to application developers to manage their application development libraries. The C/S component is the Client/Server, which allows you to run ISPF on programmable workstation, to display the panels using the display function of your workstation operating system, and to integrate workstation tools and data with host tools and data.
Interpreter
A program that translates and runs each instruction of a high-level programming language before it translates and runs the next instruction.
Isomorphic
Each composed element (in other words, an element containing other elements) of the XML instance document starting from the root has one and only one corresponding COBOL group item whose nesting depth is identical to the nesting depth of its XML equivalent. Each non-composed element (in other words, an element that does not contain other elements) in the XML instance document starting from the top has one and only one corresponding COBOL elementary item whose nesting depth is identical to the nesting level of its XML equivalent and whose memory address at runtime can be uniquely identified.

J

K

L

Linkage Section
The section in the data division of an activated unit (a called program or an invoked method) that describes data items available from the activating unit (a program or a method). These data items can be referred to by both the activated unit and the activating unit.
Load Library
A library containing load modules.
Lock Action
Locks a member.

M

N

Navigator View
Provides a hierarchical view of the resources in the Workbench.
Non-Isomorphic
A simple mapping of COBOL items and XML elements belonging to XML documents and COBOL groups that are not identical in shape (non-isomorphic). Non-isomorphic mapping can also be created between non-isomorphic elements of isomorphic structures.

O

Output Console View
Displays the output of a process and allows you to provide keyboard input to a process.
Output View
Displays messages, parameters, and results that are related to the objects that you work with

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.

Q

R

RAM
Repository Access Manager
Remote File System
A file system residing on a separate server or operating system.
Remote System
Any other system in the network with which your system can communicate.
Remote Systems Perspective
Provides an interface for managing remote systems using conventions that are similar to ISPF.
Repository
  1. A storage area for data. Every repository has a name and an associated business item type. By default, the name will be the same as the name of the business item. For example, a repository for invoices will be called Invoices. There are two types of information repositories: local (specific to the process) and global (reusable).
  2. A VSAM data set on which the states of BTS processes are stored. When a process is not executing under the control of BTS, its state (and the states of its constituent activities) are preserved by being written to a repository data set. The states of all processes of a particular process-type (and of their activity instances) are stored on the same repository data set. Records for multiple process-types can be written to the same repository.
  3. A persistent storage area for source code and other application resources. In a team programming environment, a shared repository enables multiuser access to application resources.
  4. A collection of information about the queue managers that are members of a cluster. This information includes queue manager names, their locations, their channels, what queues they host, and so on.
Repository Instance
A project or component that exists in an SCM.
Repositories View
Displays the CVS repository locations that have been added to your Workbench.
Response File
  1. A file that contains a set of predefined answers to questions asked by a program and that is used instead of entering those values one at a time.
  2. An ASCII file that can be customized with the setup and configuration data that automates an installation. The setup and configuration data would have to be entered during an interactive install, but with a response file, the installation can proceed without any intervention.

S

Servers View
Displays a list of all your servers and the configurations that are associated with them.
Shell
A software interface between users and the operating system that interprets commands and user interactions and communicates them to the operating system. A computer may have several layers of shells for various levels of user interaction.
Shell Name
The name of the shell interface.
Shell Script
A file containing commands that can be interpreted by the shell. The user types the name of the script file at the shell command prompt to make the shell execute the script commands.
Sidedeck
A library that publishes the functions of a DLL program. The entry names and module names are stored in the library after the source code is compiled.
Silent Installation
An installation that does not send messages to the console but instead stores messages and errors in log files. Also, a silent installation can use response files for data input.
Silent Uninstallation
An uninstallation process that does not send messages to the console but instead stores messages and errors in log files after the uninstall command has been invoked.

T

Task List
A list of procedures that can be executed by a single flow of control.

U

URL
Uniform Resource Locator

V

W

X

Y

Z

Documentation notices for IBM Rational Developer for System z

© Copyright IBM Corporation - 2009

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
3-2-12, Roppongi, Minato-ku, Tokyo 106-8711 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 could 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.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

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:

Intellectual Property Dept. for Rational Software
IBM Corporation
3039 Cornwallis Road, PO Box 12195
Research Triangle Park, NC 27709
U.S.A.

I

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.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

Copyright license

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.

Trademark acknowledgments

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.shtml.

Rational are trademarks of International Business Machines Corporation and Rational Software Corporation, in the United States, other countries, or both.

Intel and Pentium are trademarks of Intel Corporation in the United States, or other countries, or both.

Microsoft, Windows, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Index

Special characters
A B C D E F G H I J K L M N O P Q R S T U V W X Z
Special characters A B C D E F G H I J K L M N O P Q R S T U V W X Z