Before using this document, read the general information under Notices.
This edition applies to IBM Rational Developer for System z Version 7.1 (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:
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.
This book 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 servers on your z/OS(R) host system.
From here on, the following names are used in this manual:
For IBM WebSphere Developer for System z, IBM WebSphere Developer for zSeries and WebSphere Studio Enterprise Developer, use the configuration information found in the Host Configuration Guide and Program Directories for those releases.
This book is intended for system programmers installing and configuring IBM Rational Developer for System z Version 7.1 on their z/OS host system. To use this book, you need to be familiar with the z/OS UNIX(R) and MVS(TM) host systems.
For each of the following functions, install the required FMIDs. For installation information about the various FMIDs, please refer to the corresponding program directory for the FMID you are installing.
If you require this IBM Rational Developer for System z function | You must install these FMIDs | And you will find installation and configuration information here |
---|---|---|
|
HHOP710, HSD3310* |
optional
|
|
HCMA710, HHOP710** |
optional
|
|
HSD3310 |
|
(*) Developer for System z requires a connection to the TSO Commands service on z/OS. This connection is provided by one of the following:
(**) CARMA requires a host based interface. HHOP710 provides this function, or you may use a custom built, host based, interface and omit installing HHOP710
The following SCLMDT customization steps must be performed, which are described in the SCLM Developer Toolkit Installation and Customization Guide (SC23-8504):
For detailed instructions on the SMP/E installation for each of the FMIDs, refer to the appropriate program directory, as listed in Table 1.
Developer for System z has a list of prerequisite software that must be installed and operational before the product 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 IBM Rational Developer for System z Host Planning Guide (GI11-8296-00) to get a list of prerequisites and corequisites for your version of Developer for System z.
Consult your MVS system programmer, security administrator and TCP/IP administrator to check if the requisite products and software are installed, tested, and working.
The following SCLMDT customization steps must be performed, which are described in the SCLM Developer Toolkit Installation and Customization Guide (SC23-8504):
You can test your TCP/IP configuration with the TSO command HOMETEST. Refer to "TSO Commands" in the Communications Server: IP System Administrator's Commands (SC31-8781) for more information on this command.
Example output of the HOMETEST command:
Running IBM MVS TCP/IP CS V1R7 TCP/IP Configuration Tester The FTP configuration parameter file used will be "SYS1.TCPPARMS(FTPDATA)" TCP Host Name is: CDFMVS08 Using Name Server to Resolve CDFMVS08 The following IP addresses correspond to TCP Host Name: CDFMVS08 9.42.112.75 The following IP addresses are the HOME IP addresses defined in PROFILE.TCPIP: 9.42.112.75 127.0.0.1 All IP addresses for CDFMVS08 are in the HOME list! Hometest was successful - all Tests Passed!
The user ID of a Developer for System z user must have (at least) the following attributes:
Example (command LISTUSER userid NORACF OMVS):
USER=userid OMVS INFORMATION ---------------- UID= 0000003200 HOME= /u/userid PROGRAM= /bin/sh CPUTIMEMAX= NONE ASSIZEMAX= NONE FILEPROCMAX= NONE PROCUSERMAX= NONE THREADSMAX= NONE MMAPAREAMAX= NONE
Example (command LISTGRP group NORACF OMVS):
GROUP group OMVS INFORMATION ---------------- GID= 0000003243
The following host services, and thus their ports, must be available for the client to connect to. All other ports used by Developer for System z have host-only traffic. This means that, for Developer for System z, only the listed ports must be defined to your firewall protecting the host.
INETD is a z/OS UNIX server process that is required for setting up Developer for System z client-host connections. 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.
See Appendix D. Setting up INETD for more information on INETD permissions.
Remote Systems Explorer (RSE) is the Developer for System z component that provides core services like connecting the client to the host.
The configuration of Developer for System z requires more than the typical system programmer permissions, so minimal assistance from others is to be expected. The following list highlights the most important areas:
Developer for System z and Common Access Repository Manager (CARMA) support 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 for customization, then this file must replace its counterpart in the lists below.
This section highlights installation and configuration changes from previous releases of the product.
/usr/lpp/wd4z/rse/lib/setup.env.zseries
Before installing Developer for System z version 7.1, if you are a previous user of Developer for System z, it is recommended that you save the related customized files. Read Appendix A. Running multiple instances of Developer for System z before starting the customization if you plan on running multiple instances of Developer for System z.
Table 2 and Table 3 give an overview of files that may have been customized for Developer for System z and CARMA version 6.0.1 and higher. Table 4 lists customizations to data sets, prerequisite and corequisite products and software that occur during a Developer for System z and CARMA version 6.0.1 (and higher) installation.
Member | Default location v6.0.1 | Default location v7.0/v7.1 | Purpose |
---|---|---|---|
FEJJCNFG |
hlq.SFEJSAMP (hlq = FEJ) |
hlq.SFEKSAMP (hlq = FEK) |
Configuration file for JES Job Monitor |
FEJJJCL |
hlq.SFEJSAMP (hlq = FEJ) |
hlq.SFEKSAMP (hlq = FEK) |
JCL for JES Job Monitor |
FEJTSO |
hlq.SFEJSAMP (hlq = FEJ) |
hlq.SFEKSAMP (hlq = FEK) |
JCL for TSO submits |
FEKAPPCC | doesn't exist |
hlq.SFEKSAMP (hlq = FEK) |
JCL to create an APPC transaction |
FEKAPPCL | doesn't exist |
hlq.SFEKSAMP (hlq = FEK) |
JCL to display an APPC transaction |
FEKAPPCX | doesn't exist |
hlq.SFEKSAMP (hlq = FEK) |
JCL to delete an APPC transaction |
FEKFRTAD |
hlq.SFEKSAMP (hlq = FEK) |
(new member name FEKAPPCC) | JCL to create an APPC transaction |
FEKFRDIS |
hlq.SFEKSAMP (hlq = FEK) |
(new member name FEKAPPCL) | JCL to display an APPC transaction |
FEKFRDEL |
hlq.SFEKSAMP (hlq =FEK) |
(new member name FEKAPPLX) | JCL to delete an APPC transaction |
ELAXF* |
hlq.SCCUSAMP (hlq = CCU) |
hlq.SFEKSAMP (hlq = FEK) |
JCL for remote project builds, etc. |
ELAXMSAM |
hlq.SCCUSAMP (hlq = CCU) |
hlq.SFEKSAMP (hlq = FEK) |
JCL procedure of the WLM address space for the PL/I and COBOL Stored Procedure Builder |
ELAXMJCL |
hlq.SCCUSAMP (hlq = CCU) |
hlq.SFEKSAMP (hlq = FEK) |
JCL for defining the PL/I and COBOL Stored Procedure Builder to DB2 |
ADNVSAM | doesn't exist |
hlq.SFEKSAMP (hlq = FEK) |
JCL for defining the ADM CRD repository |
ADNPCCSD | doesn't exist
|
hlq.SFEKSAMP (hlq = FEK) |
JCL for activating the CRD server in the primary CICS region |
ADNCMSGH | doesn't exist |
hlq.SFEKSAMP (hlq = FEK) (doesn't exist in version 7.0) |
JCL for compiling the Pipeline Message Handler |
ADNTMSGH | doesn't exist |
hlq.SFEKSAMP (hlq = FEK) |
Sample source code for the Pipeline Message Handler |
ADNARCSD | doesn't exist |
hlq.SFEKSAMP (hlq = FEK) |
JCL for activating the CRD server in non-primary CICS regions |
CRASUBMT |
hlq.SCRACLST (hlq = CRA) |
hlq.SCRACLST (help = CRA) |
CLIST to submit JCL for a CARMA server |
CRAMREPR |
hlq.SCRASAM (hlq = CRA) |
hlq.SCRASAMP (new member name in version 7.1 CRA$VMSG)(hlq = CRA) |
JCL to create the CARMA message VSAM |
CRAREPR |
hlq.SCRASAM (hlq = CRA) |
hlq.SCRASAMP (new member name in version 7.1 CRA$VDEF)(hlq = CRA) |
JCL to create the CARMA configuration VSAM |
CRASREPR |
hlq.SCRASAM (hlq = CRA) |
hlq.SCRASAMP (new member name in version 7.1 CRA$VSTR)(hlq = CRA) |
JCL to create the CARMA custom information VSAM |
CRALREPR |
hlq.SCRASAM (hlq = CRA) |
hlq.SCRASAMP (new member name in version 7.1 CRA#VSLM)(hlq = CRA) |
JCL to create the SCLM RAM's message VSAM |
CRASALX |
hlq.SCRASAM (hlq = CRA) |
hlq.SCRASAMP (new member name in version 7.1 CRA#ASLM)(hlq = CRA) |
JCL to create the SCLM RAM's data sets |
CRATREPR |
hlq.SCRASAM (hlq = CRA) |
hlq.SCRASAMP (new member name in version 7.1 CRA#VPDS)(hlq = CRA) |
JCL to create the PDS RAM's message VSAM |
File | Default location v6.0.1 | Default location version 7.0/version 7.1 | Purpose |
---|---|---|---|
rsed.envvars | /usr/lpp/wd4z/rse/lib/ | /usr/lpp/wd4z/rse/lib/ | RSE configuration file |
rsecomm.properties | /usr/lpp/wd4z/rse/lib/ | /usr/lpp/wd4z/rse/lib/ | RSE trace configuration file |
ssl.properties | /usr/lpp/wd4z/rse/lib/ | /usr/lpp/wd4z/rse/lib/ | RSE SSL configuration file |
setup.env.zseries | /usr/lpp/wd4z/rse/lib/ | (no longer customized) | Export RSE environment variables |
projectcfg.properties | (doesn't exist) | /usr/lpp/wd4z/rse/lib/ | Host projects configuration file |
FMIEXT.properties | (doesn't exist) | /usr/lpp/wd4z/rse/lib/ (doesn't exist in version 7.0) | File Manager configuration file |
CRASRV.properties | /usr/lpp/wd4z/rse/lib/ | /usr/lpp/wd4z/rse/lib/ | CARMA configuration file |
rexxsub | /usr/lpp/wd4z/rse/lib/ | (no longer customized) | CARMA z/OS UNIX REXX to execute MVS CRASUBMT CLIST |
Member/File | Default location | Required customization |
---|---|---|
BPXPRMxx | SYS1.PARMLIB | Set MAXASSIZE to 2147483647 or larger |
PROGxx | SYS1.PARMLIB | APF authorize hlq.SFEKLOAD |
ASCHPMxx | SYS1.PARMLIB | Define an APPC transaction class for the TSO Commands service |
services | /etc/ | Define RSE daemon |
inetd.conf | /etc/ | Define RSE daemon |
ISPF.conf | /etc/SCLMDT/CONFIG/ | Define location of the TSO Commands Server |
/ | APPC | Define an APPC transaction for the TSO Commands service |
/ | WLM | Associate APPC transaction program with a TSO performance group |
/ | WLM | Assign an application environment for the DB2 stored procedure |
Before installing the 7.1 version, if you are a previous user of WebSphere Developer for System z (FMID: HHOP700), it is recommended that you save the related customization as described in Backing up previously configured files.
All references to hlq in this chapter 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.
The LINKLIST requirement can be bypassed by adding a STEPLIB statement to rsed.envvars, see Customize rsed.envvars, the configuration file for RSE.
MAXASSIZE defines the address space (process) region size. Set MAXASSIZE in SYS1.PARMLIB(BPXPRMxx) to 2147483647 or larger.
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=2147483647
Refer to Address Space size for more information on other locations where address space sizes can be set or limited.
In order for JES Job Monitor to access JES spool files, the hlq.SFEKLOAD load library must be APF authorized.
APF authorizations are defined in SYS1.PARMLIB(PROGxx), if your site followed IBM recommendations. Refer to MVS Initialization and Tuning Reference (SC28-1752) for more information on defining APF authorizations.
For testing purposes, APF authorizations can also be given dynamically. These will last until the next IPL of the system. The console command needed will look like this:
SETPROG APF,ADD,DSN=hlq.SFEKLOAD,SMS
Refer to MVS System Commands (GC28-1781) for more information on the SETPROG command.
JES Job Monitor is the Developer for System z component that handles all JES connectivity. A configuration file is used to customize certain aspects to meet your site standards.
The sample configuration file is located in:
hlq.SFEKSAMP(FEJJCNFG)
The file consists of a set of environment variable definitions. Comment lines start with the pound sign (#). The sample configuration file is listed in Figure 1.
SERV_PORT=6715 CODEPAGE=UTF-8 HOST_CODEPAGE=IBM-1047 TZ=EST5EDT #LIMIT_VIEW=USERID LISTEN_QUEUE_LENGTH=5 MAX_DATASETS=32 MAX_THREADS=200 TIMEOUT_INTERVAL=1200 TIMEOUT=3600 AUTHMETHOD=RACF
The following definitions are required:
The following definitions are optional. If omitted, default values will be used as specified below:
JES Job Monitor is the Developer for System z component that handles all JES connectivity. To do this, a server must be active on the system (either as user job or STC). Follow the JCL customization steps located in hlq.SFEKSAMP(FEJJJCL) to create the JES Job Monitor server according to your site standards.
If you need to turn on JES Job Monitor tracing for diagnostic purposes, add "-TV" to the PARM line. Tracing will cause performance degradations and should only be done under the direction of the IBM support center.
//JMONITOR EXEC PGM=FEJJMON,TIME=1440,REGION=0M, // PARM=('POSIX(ON),ENVAR("_CEE_ENVFILE=DD:ENVIRON")/ -TV')
Tracing can also be controlled by console commands. Assuming that JMON is the job name used, then the first console command listed below will activate tracing and the second one will deactivate it.
1. F JMON,APPL=-TV 2. F JMON,APPL=-TN
JES Job Monitor can run as a user job or started task (STC). The following tasks need to be implemented to define JMON as an STC:
//JMON PROC HLQ=FEK, // PRM= //* //* WD/Z JES JOB MONITOR //* //JMONITOR EXEC PGM=FEJJMON,TIME=1440,REGION=0M, // PARM=('POSIX(ON),ENVAR("_CEE_ENVFILE=DD:ENVIRON")/&PRM') //STEPLIB DD DISP=SHR,DSN=&HLQ..SFEKLOAD //ENVIRON DD DISP=SHR,DSN=&HLQ..SFEKSAMP(FEJJCNFG) //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSIN DD DUMMY //*SYSTCPD DD DISP=SHR,DSN=SYS1.TCPIP.DATA
For easy reference it is recommended that the member name matches the procedure name (JMON in the sample above).
Use the following sample command to create such a user ID, where userid is the user ID in question, groupid is its default group and uid is the UNIX ID.
ADDUSER userid DFLTGRP(groupid) NOPASSWORD OMVS(UID(uid) HOME(/tmp) PROGRAM(/bin/sh))
a. SETROPTS GENERIC(STARTED) b. RDEFINE STARTED ** STDATA(USER(=MEMBER)) c. SETROPTS CLASSACT(STARTED) d. SETROPTS RACLIST(STARTED)
To add JES Job Monitor as an STC, following RACF commands are needed, where jmon is the name of the JCL member and userid is the user ID whose authorities are to be used.
a. RDEFINE STARTED jmon.* STDATA(USER(userid)) b. SETROPTS RACLIST(STARTED) REFRESH
Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on started tasks and security.
The system operator can issue following commands on the console (where JMON is the JES Job Monitor STC name):
a. Start JMON b. stoP JMON c. Display A,JMON
If you have the proper authority, you can give these commands from within SDSF, but then the commands must be preceded by a slash ('/'). Refer to MVS System Commands (SA22-7627) for more information on console commands.
The user ID assigned to the JES Job Monitor server needs READ access to the Developer for System z load library, hlq.SFEKLOAD.
Start the user job or STC defined in the steps above. If the job ends with return code 66, then hlq.SFEKLOAD is not APF authorized.
In order to allow users to execute operations via the JES Job Monitor, they must be given access authority to the OPERCMDS class. This can be done conditionally, so the users' access rights are only in effect when they are using the JES Job Monitor. To use this conditional access checking, you must have the CONSOLE class active and a console defined named JMON (JMON is the only valid name).
For example, your security administrator would issue the following RACF commands:
1. SETROPTS CLASSACT(CONSOLE) 2. RDEFINE CONSOLE JMON UACC(READ) 3. SETROPTS RACLIST(CONSOLE) REFRESH
Use the following RACF commands to permit users to issue JES2 commands only through the JES Job Monitor, where id is the user ID or group ID of Developer for System z users:
1. RDEFINE OPERCMDS JES2.** UACC(NONE) 2. PERMIT JES2.** CLASS(OPERCMDS) ID(id) ACCESS(CONTROL) WHEN(CONSOLE(JMON)) 3. SETROPTS RACLIST(OPERCMDS) REFRESH 4. SETROPTS GENERIC(OPERCMDS) REFRESH
JES Job Monitor does not provide Developer for System z users full access to the JES spool. Only the commands listed in Table 5 are available. The commands are issued by selecting the appropriate option in the client menu structure (no command prompt). The scope of the commands is further limited by techniques described below.
Command | JES2 | JES3 |
---|---|---|
Hold | $Hjobid | *F,J=jobid,H |
Release | $Ajobid | *F,J=jobid,R |
Cancel | $Cjobid | *F,J=jobid,C |
Purge | $Cjobid,P | *F,J=jobid,C |
Without being authorized for these console commands, users will still be able to submit jobs and read job output, if they are given access authorization to spool files.
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 they need access to a wider range of jobs, but not all, use the standard spool file protection features of your security product, like the JESSPOOL class in RACF.
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 v1.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.
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 and COBOL, PL/I, Assembler and C/C++ programs.
These procedures allow installations to apply their own standards. This will also ensure that developers use the same procedures with the same compiler options and compiler levels.
SMP/E installs these sample JCL procedures into hlq.SFEKSAMP. If you plan to use these procedures you must:
The sample procedures to be copied and customized are listed in Table 6.
If the ELAXF* procedures cannot be copied into a system procedure library, copy them into a private library and ask the Developer for System z users to add a JCLLIB card (right after the JOB card) to the job properties on the client. Do not customize the sample JCL in the installation data set since maintenance might replace these members and undo your customizations.
//MYJOB JOB <job parameters> //PROCS JCLLIB ORDER=(hlq.SFEKSAMP)
The names of the procedures and the names of the steps in the procedures match the default properties that are shipped with the client. If you decide to change the name of the procedure or the name of a step in a procedure, the corresponding properties file on the client should also be updated. We recommend that you do not change the procedure and step names.
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. |
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. |
ELAXFUOP | Sample procedure for generating the UOPT step when building programs that run in CICS or IMS subsystems. |
Defining the APPC transaction has become optional in version 7.1. By default, Developer for System z now uses SCLM Developer Toolkit to provide the TSO Commands service. The configuration of this is done in rsed.envvars, which is described in Customize rsed.envvars, the configuration file for RSE.
// PARM='ISPSTART CMD(%FEKFRSRV TIMEOUT=60) NEWAPPL(ISR) NESTMACS'
The TSO Commands service is implemented as an APPC transaction program, FEKFRSRV and must be active for Developer for System z connections to succeed between the host and the client. FEKFRSRV acts as a host server to execute TSO commands that are issued from the workstation through TCP/IP. APPC is not required on the workstation because the workstation communicates with FEKFRSRV through TCP/IP. Each workstation can have an active connection to multiple hosts at the same time.
/* REXX -- APPC administration using ISPF panels */ address ISPEXEC "LIBDEF ISPMLIB DATASET ID('ICQ.ICQMLIB') STACK" "LIBDEF ISPPLIB DATASET ID('ICQ.ICQPLIB') STACK" "LIBDEF ISPSLIB DATASET ID('ICQ.ICQSLIB') STACK" "LIBDEF ISPTLIB DATASET ID('ICQ.ICQTLIB') STACK" address TSO "ALTLIB ACT APPLICATION(CLIST)", "DSN('ICQ.ICQCCLIB') UNCOND QUIET" "SELECT CMD(%ICQASRM0) NEWAPPL(ICQ) PASSLIB" address TSO "ALTLIB DEACT APPLICATION(CLIST) QUIET" "LIBDEF ISPMLIB" "LIBDEF ISPPLIB" "LIBDEF ISPSLIB" "LIBDEF ISPTLIB" exit
Expertise | Required information:
|
Value |
---|---|---|
APPC | Data set name of TPDATA
|
|
APPC | Transaction name to be used (may not exist)
|
|
APPC | APPC transaction class to be used
|
|
WLM/SRM | TSO performance group and domain
|
|
RACF | Every Developer for System z user has access to an OMVS segment
(this is required)
|
|
RACF | Every Developer for System z user must have READ access to hlq.SFEKPROC(FEKFRSRV)
|
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.
The system programmer or APPC administrator needs to complete the following steps to configure the command facility:
CLASSADD CLASSNAME(A) MAX(20) MIN(1) MSGLIMIT(200)
The following customization is needed to incorporate the sample DB2 stored procedure (PL/I and COBOL Stored Procedure Builder) into your system. You will need assistance of a WLM administrator and a DB2 administrator to complete these tasks.
After the SMP/E apply, the sample library hlq.SFEKSAMP and procedure library hlq.SFEKPROC contains the DB2 stored procedure members listed in Table 8.
Member | Purpose |
---|---|
hlq.SFEKSAMP(ELAXMJCL) | Sample JCL for defining the PL/I and COBOL Stored Procedure Builder to DB2. |
hlq.SFEKSAMP(ELAXMSAM) | Sample JCL procedure of the WLM address space for the PL/I and COBOL Stored Procedure Builder. |
hlq.SFEKPROC(ELAXMREX) | REXX code for the PL/I and COBOL Stored Procedure Builder. |
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:
You will need assistance of your CICS administrator to perform following tasks:
EST bidirectional transformations are performed in the CICS Service Flow Runtime (SFR) environment by the FEJBDTRX module. The FEJBDTRX module is called when bidirectional conversions are needed in EST-generated code (when mapping is generated between fields in messages that have different bidirectional attributes.)
If autoinstall is set to autoINactive, define the program FEJBDTRX to CICS using the CEDA command, for example:
CEDA DEF PROG(FEJBDTRX) LANG(LE) G(xxx)
Additionally, EST-generated code can support bidi transformation in environments other than CICS SFR (for example, 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, hlq.SFEKLOAD.
The Application Deployment Manager (ADM) provides a common deployment approach and deployment API for all Developer for System z components.
In addition, ADM provides a CICS Resource Definition (CRD) client and (host based) server, which provide the following functions:
Developer for System z supplies three transactions that are used by the CRD server when defining and inquiring CICS resources. Sample COBOL source code is provided to allow site specific customizations.
Refer to IBM Rational Developer for System z Application Deployment Manger User's Guide (SC31-6972) for more information on ADM.
The following customization steps are required to activate the CRD server.
Before installing the 7.1 version, if you are a previous user of the CRD server, it is recommended that you save the related customization as described in Backing up previously configured files.
Copy the members to be customized from the installation directory to a personal library and customize these copies to avoid overwriting them when applying maintenance:
optional (Pipeline Message Handler)
optional (CSD update for non-primary regions)
Customize and submit job ADNVSAM to allocate and initialize the CRD server repository VSAM file. Refer to the documentation within ADNVSAM for customization instructions.
It is advised to 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, and that multiple address spaces will be writing to the VSAM, which must be set up correctly to handle this.
The CRD server must be defined to the primary connection region. This is the region that will process Web Service requests from Developer for System z.
CEDA INSTALL GROUP(ADNPCRGP)
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 pipeline configuration file and must therefore be placed into the CICS RPL concatenation. ADNTMSGH is also used to set the transaction ID to ADMD, ADMR, or ADMI depending on the requested operation. You may wish to customize ADNTMSGH to use different transaction ID's.
Using the default:
Customizing ADNTMSGH:
The CRD server can also be used with one or more non-primary connection regions, which are usually Application Owning Regions (AOR).
CEDA INSTALL GROUP(ADNARRGP)
Before installing the 7.1 version, if you are a previous user of WebSphere Developer for System z (FMID: HHOP700), it is recommended that you save the related customization described in Backing up previously configured files.
If you are unfamiliar with z/OS UNIX, it is advised to ask assistance from an experienced z/OS UNIX or other UNIX administrator to perform the tasks listed in this chapter.
The z/OS UNIX commands needed to perform the listed tasks are described briefly for your convenience. Unless noted otherwise, refer to UNIX System Services Command Reference (SA22-7802) for more information on these commands.
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.
MVS provides the possibility to edit z/OS UNIX files using ISPF through the OEDIT command. This command can be used both in TSO and OMVS.
Most z/OS UNIX files have the write permission restricted to the owner of the file. This restriction can by bypassed in multiple ways.
This is not recommended for "human" user IDs since there are no z/OS UNIX related restrictions.
Allows the user to become UID 0 through the su command. This is the recommended setup.
Allows user to read/write any file, and to read or search any directory. CONTROL (or higher) access to this security profile adds writing to any directory to the list of permissions
.Refer to UNIX System Services Planning (GA22-7800) to learn more about z/OS UNIX security.
All /usr/lpp/wd4z/ path statements in this chapter refer to the path used during installation of Developer for System z. The default is /usr/lpp/wd4z/, but this might not apply to your site.
You can test your TCP/IP configuration with the TSO command HOMETEST. Communications Server: IP System Administrator's Commands (SC31-8781) for more information on this command.
You may find the following publications helpful on understanding z/OS UNIX:
It is recommended that you copy the /usr/lpp/wd4z/rse/lib/rsed.envvars file to a new directory (like /etc/wd4z/) and customize the copy to avoid overwriting your customization when applying maintenance. However, when you do this, you must also copy the following files from the installation directory (default /usr/lpp/wd4z/rse/lib/) to the new location:
The files listed in Table 8 must be copied also if you plan on using the optional features that they are part of:
file | function |
---|---|
projectcfg.properties | Host based projects
See (Optional) Customize projectcfg.properties, host projects configuration |
FMIEXT.properties | File Manager integration
See (Optional) Customize FMIEXT.properties, File Manager integration |
CRASRV.properties | CARMA
See (Optional) Activating IBM Common Access Repository Manager (CARMA) |
The following sample commands,
create a directory named /etc/rd4z and copy rsed.envvars from the current directory to /etc/rd4z. Repeat the copy command for the remaining files.
The result of the copy can be verified with the command ls /etc/wd4z, which should give an output similar to this ($ is the z/OS UNIX prompt):
$ ls /etc/wd4z /etc/wd4z rsecomm.properties server.zseries ssl.properties rsed.envvars setup.env.zseries
1. mkdir /usr/lpp/wd4z/rse/lib/cust 2. ln -s /usr/lpp/wd4z/rse/lib/cust /etc/wd4z
All Developer for System z client connection methods use the variables set in the rsed.envvars file, which is located by default in the installation directory, /usr/lpp/wd4z/rse/lib/, but could be copied to another directory in the previous step. The sample file provided has the statements listed in Figure 4, where comment lines start with a pound sign (#).
#============================================================= # (1) required customizations JAVA_HOME=/usr/lpp/java/J1.4 RSE_HOME=/usr/lpp/wd4z TZ=EST5EDT LANG=C PATH=/bin:/usr/sbin:. _RSE_CLASS_OPTS="" _RSE_JAVAOPTS="" #_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DTSO_SERVER=APPC" #============================================================= # (2) required customizations if SCLMDT is used _CMDSERV_BASE_HOME=/usr/lpp/SCLMDT _CMDSERV_BASE_LOAD=BWB.SBWBLOAD _CMDSERV_CONF_HOME=/etc/SCLMDT _CMDSERV_WORK_HOME=/var/SCLMDT STEPLIB=NONE #STEPLIB=$_CMDSERV_BASE_LOAD _RSE_CMDSERV_OPTS="" #============================================================= # (3) optional customizations #_RSE_PORTRANGE=8108-8118 #_FEKFLOCK_USERID_=user_id #_FEKFLOCK_JOBNAME_=job_name #_FEKFSCMD_TP_NAME_=tp_name #_FEKFSCMD_PARTNER_LU_=lu_name #============================================================= # (4) do not change unless directed by IBM support center RSE_LIB=$RSE_HOME/rse/lib ICU_LIB=$RSE_HOME/icuc/lib _CEE_RUNOPTS="ALL31(ON) HEAP(32M,32K,ANYWHERE,KEEP,,) TRAP(ON)" _CEE_DMPTARG=$HOME/.eclipse/RSE/$RSE_USER_ID _BPX_SHAREAS=YES _BPX_SPAWN_SCRIPT=YES PATH=$JAVA_HOME/bin:$RSE_LIB:$_CMDSERV_BASE_HOME/bin:$PATH LIBPATH=$JAVA_HOME/bin:$JAVA_HOME/bin/classic:$ICU_LIB:$RSE_LIB:. CLASSPATH=$RSE_LIB:$RSE_LIB/dstore_core.jar:$RSE_LIB/clientserver.jar CLASSPATH=$CLASSPATH:$RSE_LIB/dstore_extra_server.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-1.4.3.jar:$RSE_LIB/cdtparser.jar CLASSPATH=$CLASSPATH:$RSE_LIB/wdzBidi.jar:$RSE_LIB/fmiExtensions.jar CLASSPATH=.:$CLASSPATH _RSE_CMDSERV_OPTS="&SESSION=SPAWN$_RSE_CMDSERV_OPTS" _RSE_JAVAOPTS="$_RSE_JAVAOPTS -DSCLMDT_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 -Dcom.ibm.cacheLocalHost=true" _RSE_JAVAOPTS="$_RSE_JAVAOPTS -showversion" _RSE_JAVAOPTS="$_RSE_JAVAOPTS -Duser.home=$HOME" _RSE_JAVAOPTS="$_RSE_JAVAOPTS -Dclient.username=$RSE_USER_ID" _RSE_JAVAOPTS="$_RSE_JAVAOPTS $_RSE_CLASS_OPTS" _RSE_SERVER_CLASS=com.ibm.etools.systems.dstore.core.server.Server _RSE_SERVER_TIMEOUT=120000 #============================================================= # (5) additional environment variables
The following definitions are required:
Developer for System z uses SCLM Developer Toolkit by default for the TSO Commands service. APPC is used when the following _RSE_JAVAOPTS option is uncommented:
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -DTSO_SERVER=APPC"
The following definitions are required if SCLM Developer Toolkit is used, either for the TSO Commands service or when the SCLMDT plug-in is installed in the Developer for System z client.
Developer for System z uses the LINKLIST by default to access the SCLM Developer Toolkit load library. STEPLIB is used when the following STEPLIB directive is uncommented:
STEPLIB=$_CMDSERV_BASE_LOAD
The following definitions are optional. If omitted, default values will be used.
The following definitions are required, and should not be changed unless directed by the IBM support center.
STEPLIB=CEE.SCEERUN:CEE.SCEERUN2:CBC.SCLBDLL
STEPLIB=$STEPLIB:CEE.SCEERUN:CEE.SCEERUN2:CBC.SCLBDLL
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 or REXEC/SSH ports.
To help understand the port usage, a brief description of RSE's connection process follows:
To specify the port range, for the client to communicate with z/OS, uncomment and change the following line in rsed.envvars:
#_RSE_PORTRANGE=8108-8118
The format of PORTRANGE is: _RSE_PORTRANGE=min-max (max is non-inclusive; e.g. _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:
With the different _RSE_*OPTS directives, rsed.envvars provides the possibility to give extra parameters to Java when it starts the RSE server.
The sample options included in rsed.envvars can be activated by uncommenting them.
Developer for System z relies on the INETD service to start the Remote Systems Explorer (RSE) Server when a client requests a connection. INETD is a standard z/OS UNIX daemon, who manages other daemons that do the actual work (in this case, starting the RSE server). The configuration of INETD is not a part of Developer for System z customization, but valuable information can be found in Appendix D. Setting up INETD.
Developer for System z supports multiple ways to start the RSE server.
You need to customize at least one way, depending on how your users plan to operate.
You can verify that INETD is active with the ps -e command (given by an authorized user). The output must contain a reference to INETD, for example (# is the z/OS UNIX prompt):
# ps -e PID TTY TIME CMD 7 ? 0:00 /usr/sbin/inetd
rse 4035/tcp #Developer for System z RSE
The port used must match the port defined on the client, which is set during the creation of a new z/OS connection.
rse stream tcp nowait OMVSKERN /usr/lpp/wd4z/rse/lib/fekfrsed rsed -d /usr/lpp/wd4z/rse/lib -t 60
Everything after this INETD argument are server arguments, starting with the server name.
rse stream tcp nowait OMVSKERN /usr/lpp/wd4z/rse/lib/fekfrsed rsed -d /etc/wd4z
The following definitions are optional. If omitted, default values will be used.
a. # ps -e | grep inetd 50331687 ? 0:00 /usr/sbin/inetd b. # kill 50331687 c. # _BPX_JOBNAME='INETD' /usr/sbin/inetd d. # netstat | grep 4035 INETD4 00000B6A 0.0.0.0..4035 0.0.0.0..0 Listen
ICH408I USER(IBMUSER ) GROUP(SYS1 ) NAME(IBMUSER ) BPX.DAEMON CL(FACILITY) INSUFFICIENT ACCESS AUTHORITY ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )
There is no Developer for System z specific setup for using the INETD REXEC (or SSH) Command Server. However, the client needs to know 2 values to start a RSE connection through REXEC/SSH:
By default this is the installation directory (/usr/lpp/wd4z/rse/lib/). However, server.zseries is one of the files that must be copied also if rsed.envvars is copied to a different directory, like /etc/wd4z/.
A common port used by REXEC is 512. A quick way to check this is the NETSTAT command, as shown in the following sample ($ is the z/OS UNIX prompt):
$ netstat | grep 512 INETD4 0000002E 0.0.0.0..512 0.0.0.0..0 Listen
To verify this, you can check /etc/inetd.conf and /etc/services to find the port number used.
exec stream tcp nowait OMVSKERN /usr/sbin/orexecd rexecd -LV
exec 512/tcp #REXEC Command Server
The same principle applies to SSH. Its common port is 22, and the server name is sshd.
This step is only required when using SCLM Developer Toolkit for the TSO Commands service (this is the default). It is not required when using APPC for the TSO Commands service.
SCLM Developer Toolkit requires the definitions in ISPF.conf to create a valid environment to run ISPF services. The TSO Commands service must be added to this ISPF environment.
ISPF.conf is created during the SCLM Developer Toolkit customization, which is described in SCLM Developer Toolkit Installation and Customization Guide (SC23-8504). The default location is /etc/SCLMDT/CONFIG, but this might not apply to your site.
Add the following lines to ISPF.conf, where hlq equals the high level qualifier used to install Developer for System z (default FEK).
********************************************** * Developer for System z - TSO Commands server ********************************************** sysexec=hlq.SFEKPROC
The result should look like the sample in Figure 5.
sysproc=ISP.SISPCLIB ispmlib=ISP.SISPMENU isptlib=ISP.SISPTENU ispplib=ISP.SISPPENU ispslib=ISP.SISPSLIB ispllib=BWB.SBWBLOAD ********************************************** * Developer for System z - TSO Commands server ********************************************** sysexec=FEK.SFEKPROC
The Developer for System z installation provides several Installation Verification Programs (IVP) for the RSE server. The IVP scripts are located in the installation directory, default /usr/lpp/wd4z/rse/lib/.
All sample commands in this section expect that the RSE environment variables are set. This way, the IVP scripts are available through the PATH statement and the location of rsed.envvars is known. Use the pwd and cd commands to verify and change your current directory to the directory with the customized rsed.envvars. The setup.env.zseries shell script can then be used to set the RSE environment variables, like in the following sample ($ is the z/OS UNIX prompt):
$ pwd /etc $ cd /etc/wd4z $ . ./setup.env.zseries
The . ./setup.env.zseries shell script, which resides in the same directory as rsed.envvars, exports the environment variables so that other processes can use them. The first "." (dot) in . ./setup.env.zseries 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.
/usr/lpp/wd4z/rse/lib/fekfivpr 512 USERID
$ echo $STEPLIB none $ STEPLIB=TCPIP.SEZALOAD
or
$ echo $STEPLIB SOME.STEPLIB.DATASET $ STEPLIB=$STEPLIB:TCPIP.SEZALOAD
For information on diagnosing RSE connection problems, see Appendix B. Troubleshooting configuration problems or the technotes on the Developer for System z Support Page http://www-306.ibm.com/software/awdtools/devzseries/support/.
The JES Job Monitor, REXEC, SSH and RSE daemon port availability can be verified by issuing the netstat command. The result should show the ports used by these services, like in the following sample ($ is the z/OS UNIX prompt):
$ netstat MVS TCP/IP NETSTAT CS V1R7 TCPIP Name: TCPIP 13:57:36 User Id Conn Local Socket Foreign Socket State ------- ---- ------------ -------------- ----- INETD4 00000030 0.0.0.0..22 0.0.0.0..0 Listen INETD4 00000030 0.0.0.0..512 0.0.0.0..0 Listen INETD4 00000030 0.0.0.0..4035 0.0.0.0..0 Listen JMON 00000030 0.0.0.0..6715 0.0.0.0..0 Listen
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 in the following sample ($ is the z/OS UNIX prompt):
$ fekfivpr 512 USERID Enter password: $ EZYRC01I Calling function rexec_af with the following: EZYRC02I Host: CDFMVS08, user USERID, cmd cd /etc/wd4z;export RSE_USER_ID=USERI D;./server.zseries -ivp, port 512 EZYRC19I Data socket = 4, Control socket = 6. expect to see time out messages after a successful IVP test 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 Server Started Successfully 1272 Server running on: CDFMVS08
$ java.net.SocketTimeoutException: Accept timed out at java.net.PlainSocketImpl.socketAccept(Native Method) at java.net.PlainSocketImpl.accept(PlainSocketImpl.java:384) at java.net.ServerSocket.implAccept(ServerSocket.java:471) at java.net.ServerSocket.accept(ServerSocket.java:442) at com.ibm.etools.systems.dstore.core.server.ConnectionEstablisher. ...
This IVP test can be skipped if the previous test outlined in, REXEC connection, completed successfully.
Verify the shell script used by the REXEC and SSH connection by executing the following command:
fekfivps
The command should return a timeout warning, the Java version and the RSE server message, like in the following sample ($ is the z/OS UNIX prompt):
$ fekfivps $ java version "1.5.0" expect to see time out messages after a successful IVP test 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 Server Started Successfully 1751 Server running on: CDFMVS08$
$ java.net.SocketTimeoutException: Accept timed out at java.net.PlainSocketImpl.socketAccept(Native Method) at java.net.PlainSocketImpl.accept(PlainSocketImpl.java:384) at java.net.ServerSocket.implAccept(ServerSocket.java:471) at java.net.ServerSocket.accept(ServerSocket.java:442) at com.ibm.etools.systems.dstore.core.server.ConnectionEstablisher. ...
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 in this sample ($ is the z/OS UNIX prompt):
$ fekfivpd 4035 USERID Password: SSL is disabled connected 8108 570655399 Success
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 in the following sample ($ is the z/OS UNIX prompt):
$ fekfivpj 6715 Waiting for JES Job Monitor response... ACKNOWLEDGE01v03 Success
This IVP test is only needed if you use SCLM Developer Toolkit, either for the TSO Commands service or client plug-in.
Verify the connection to the TSO Commands server using SCLM Developer by executing the following command.
fekfivpc
The command should return the result of SCLM Developer Toolkit related checks (variables, HFS modules, REXX runtime, starting and stopping TSO/ISPF session), like in the following sample ($ is the z/OS UNIX prompt):
$ fekfivpc ------------------------------------------------------------- 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/wd4z/rse/lib:/usr/lpp/SCLM DT/bin:/bin:/usr/sbin:. STEPLIB = BWB.SBWBLOAD _CMDSERV_BASE_HOME = /usr/lpp/SCLMDT _CMDSERV_CONF_HOME = /etc/SCLMDT _CMDSERV_WORK_HOME = /var/SCLMDT ------------------------------------------------------------- *** CHECK : HFS MODULES Checking install Directory : /usr/lpp/SCLMDT Checking for BWB modules in /bin directory 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 -------------------------------------------------------------
fekfivpc has several optional, non-positional, parameters:
Do not execute this procedure if you have not set up APPC for the TSO Commands service.
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 in the following sample ($ is the z/OS UNIX prompt):
$ fekfivpa USERID Enter password: 20070607 13:57:18.584060 /usr/lpp/wd4z/rse/lib/fekfscmd: version=Oct 2003 20070607 13:57:18.584326 Input parms: 1.2.3.4 * NOTRACE USERID ******** 20070607 13:57:18.585132 TP_name set via envvar: FEKFRSRV 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
For information on diagnosing RSE connection problems, see Appendix B. Troubleshooting configuration problems or the technotes on the Developer for System z Support Page http://www-306.ibm.com/software/awdtools/devzseries/support/.
All Developer for System z client connection methods use the Secure Socket Layer (SSL) variables set in the ssl.properties file, which is located by default in the installation directory, /usr/lpp/wd4z/rse/lib/. However, ssl.properties is one of the files that must be copied also if rsed.envvars is copied to a different directory, like /etc/wd4z/. The sample file provided has the statements listed in Figure 6 , where comment lines start with a pound sign (#).
# Specify this property as true to enable SSL enable_ssl=false ################################### # Daemon Properties # The key database file and password need to be specified for # daemon to use. # The key label need to be specified if not default key. #daemon_keydb_file= #daemon_keydb_password= #daemon_key_label= ################################### # Server Properties # The keystore file and password need to be specified for the # server to use. #server_keystore_file= #server_keystore_password=
The daemon and server properties only need to be set if you enable SSL. Refer to Appendix E. Setting up SSL for more information on SSL setup.
All Developer for System z client connection methods use the variables set in the rsecomm.properties file, which is located by default in the installation directory, /usr/lpp/wd4z/rse/lib/. However, rsecomm.properties is one of the files that must be copied also if rsed.envvars is copied to a different directory, like /etc/wd4z/. The sample file provided has the statements, listed in Figure 7, where comment lines start with a pound sign (#).
# 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 # 3 - Log error, warning, info and debug messages debug_level=1 # Log location # Log_To_StdOut # Log_To_File log_location=Log_To_File
When selecting log_location=Log_To_File (the default), the logging is written to home/.eclipse/RSE/USERID/rsecomm.log, where home is the home path defined in the user's OMVS segment (or the default OMVS segment if the user does not have and OMVS segment) and USERID is the logon user ID (uppercase).
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 by default in the installation directory, /usr/lpp/wd4z/rse/lib/. However, projectcfg.properties is one of the files that must be copied also if rsed.envvars is copied to a different directory, like /etc/wd4z/.
The sample file provided has the statements listed in Figure 8, where comment lines start with a pound sign (#).
# # 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/wd4z/projects
The only variable to be changed is PROJECT-HOME. Its value, default /var/wd4z/projects, is the base directory for the project definitions.
For more information on host based projects, see the white paper Host Based Projects in WebSphere Developer for System z version 7.0 in the Developer for System z internet library, http://www-306.ibm.com/software/awdtools/devzseries/library/
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/edit of MVS data sets (including VSAM KSDS and ESDS) is supported.
Note that IBM File Manager for z/OS product must be ordered, installed and configured separately. Refer to IBM Rational Developer for System z Host Planning Guide (GI11-8296-00) 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.
The File Manager definitions needed by Developer for System z are stored in FMIEXT.properties, which is located by default in the installation directory, /usr/lpp/wd4z/rse/lib/. However, FMIEXT.properties is one of the files that must be copied also if rsed.envvars is copied to a different directory, like /etc/wd4z/.
The sample file provided has the statements listed in Figure 9, where comment lines start with a pound sign (#).
# File Manager Integration (FMI) Extension properties # startup.script=/usr/lpp/wd4z/rse/lib/fmiSub startup.port=1957 startup.range=100 startup.fmload=FMN.SFMNMOD1 startup.jobcard1=//JOBCARD JOB <job parameters> startup.jobcard2=//* startup.jobcard3=//* startup.sysout=*
Common Access Repository Manager (CARMA) (FMID: HCMA710) is a productivity aid for developers who are creating APIs for Software Configuration Managers (SCM). In turn, these API's can be used by applications (for example, Developer for System z) to access the SCMs.
Before installing the 7.1 version, if you are a previous user of CARMA, it is recommended that you save the related customization as described in Backing up previously configured files.
After installation, you must configure CARMA by following these steps:
Refer to Table 1 for a list of manuals that provide more information on CARMA and how to use it.
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
Error Logging
. Refer to Location of log files for more information on log file locations.
All references to hlq in this section refer to the high level qualifier used during installation of CARMA. The installation default is CRA, but this might not apply to your site.
Follow these steps to configure your MVS host:
If you are unfamiliar with z/OS UNIX, it is advised to ask assistance from an experienced z/OS UNIX or other UNIX administrator to perform the tasks listed in this section.
The z/OS UNIX commands needed to perform the listed tasks are described briefly for your convenience. Unless noted otherwise, refer to UNIX System Services Command Reference (SA22-7802) for more information on these commands.
All /usr/lpp/wd4z/ path statements in this chapter refer to the path used during installation of Developer for System z, not CARMA. The default is /usr/lpp/wd4z/, but this might not apply to your site.
Follow these steps to configure the z/OS UNIX CARMA components, which are installed during the IBM Rational Developer for System z installation (FMID: HHOP710):
cp /usr/lpp/wd4z/rse/lib/CRASRV.properties /etc/wd4z
# CARMA configuration option # port.start=5227 port.range=100 startup.script.name=/usr/lpp/wd4z/rse/lib/rexxsub clist.dsname='hlq.SCRACLST(CRASUBMT)'
Repository Access Managers (RAMs) are user-written API's to interface with z/OS Software Configuration Managers (SCMs). Follow the instructions in the sections below for the sample RAMs you want to activate.
Refer to the IBM Rational Developer for System z Common Access Repository Manager Developer's Guide (SC23-7660-00) for more information on the sample RAMs and sample source code provided.
IBM Software Configuration and Library Manager (SCLM) (FMID: HSD3310) 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, which is shipped together with Developer for System z, is an Eclipse based plug-in 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.
Refer to Table 1 for a list of manuals that provide more information on SCLM Developers Toolkit and how to use it.
Users of the Developer for System z client must know the result of certain host customizations, like TCP/IP port numbers, for the client to work properly. Use the checklist in Table 10 to gather the information needed.
Customization | Value |
---|---|
JES Job Monitor server port number (default 6715):
See SERV_PORT in Customize FEJJCNFG, the JES Job Monitor configuration file . |
|
Location of the ELAXF* procedures if they
are not in a system procedure library:
See note on JCLLIB in Customize ELAXF*, remote build procedures. |
|
Procedure and/or step names of the ELAXF* procedures
if they were changed:
See note on changing them in Customize ELAXF*, remote build procedures. |
|
DB2 stored procedure name (default ELAXMSAM):
See information on DB2 stored procedures in Appendix A. Running multiple instances of Developer for System z. |
|
Location of the DB2 stored procedure if it is not in a system
procedure library:
See (Optional) Customize ELAXM*, DB2 stored procedure members. |
|
Use DAEMON, REXEC or SSH connection method for RSE: | |
RSE daemon TCP/IP port number (default 4035): | |
Path to the server.zseries shell script for REXEC/SSH (default /usr/lpp/wd4z/rse/lib, advised /etc/wd4z): | |
REXEC or SSH port number (default 512 or 22, respectively):
See INETD REXEC (or SSH) set up. Note:
Remote (host based) actions for z/OS UNIX subprojects require that REXEC or
SSH is active on the host. |
|
Location of the CRA#ASLM JCL for CARMA SCLM
RAM data set allocations:
See note on CRA#ASLM in Activating the SCLM RAM. |
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.
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 ECSA (Extended Common Storage Area). 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. The RSE server starts several processes, and each client connection has a private RSE server. Because of this, the numbers can go up quickly.
Developer for System z has a default of STEPLIB=NONE coded in rsed.envvars, as described in Customize rsed.envvars, the configuration file for RSE. 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.
If you do use the STEPLIB directive, you must verify the content of rsed.envvars to see if your STEPLIB statement is the first one or not.
STEPLIB=NONE STEPLIB=first.steplib.dataset:second.steplib.dataset
STEPLIB=NONE STEPLIB=$STEPLIB:first.steplib.dataset:second.steplib.dataset
Certain system libraries and load modules are heavily used by z/OS UNIX and application development activities. Improving access to these, like adding them to the Link Pack Area (LPA) can improve your system performance. Refer to MVS Initialization and Tuning Reference (SC28-1752) for more information on changing the SYS1.PARMLIB members described below.
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. It is advised to 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.
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.
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 Customize rsed.envvars, the configuration file for RSE. 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.
On systems where application development is the primary activity, performance may also benefit if you put the linkage editor into dynamic LPA, by adding these 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.
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.
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 SDK and Runtime Environment User Guide to learn more about class sharing.
To enable class sharing for the RSE server, uncomment the following directive in rsed.envvars, as described in (Optional) Defining extra Java startup parameters with _RSE_*OPTS. 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).
_RSE_CLASS_OPTS=-Xshareclasses:name=RSE,groupAccess,nonFatal #_RSE_CLASS_OPTS="$_RSE_CLASS_OPTS -Xscmx6m
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.
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 the SDK and Runtime Environment User Guide to learn more about extra security options using a Java SecurityManager.
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 the MVS Initialization and Tuning Reference (SC28-1752) and UNIX System Services Planning (GA22-7800). The most significant BPXPRMxx parameters that affect the operation of shared classes are:
These settings affect the amount of shared memory pages available to the JVM. The shared page size for a 31-bit z/OS UNIX system service is fixed at 4 KB. Shared classes try to create a 16 MB cache by default. Therefore set IPCSHMMPAGES greater than 4096.
If you set a cache size using -Xscmx, the JVM will round up the value to the nearest megabyte. You must take this into account when setting IPCSHMMPAGES on your system.
These settings affect the amount of semaphores available to UNIX processes. Shared classes use IPC semaphores to communicate between the JVMs.
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.
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 the 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.
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 the Diagnostics Guide (SC34-6358) 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 (Optional) Defining extra Java startup parameters with _RSE_*OPTS.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xms128m -Xmx128m"
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 below.
Refer to MVS Planning: Workload Management (SA22-7602) for more information on this subject.
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 like 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 2 (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.
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.
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/ports to avoid overlapping the current setup.
In the SSL sample mentioned above, the current RSE server customizations can be cloned, after which the cloned ssl.properties can be updated. The MVS customizations (JES Job Monitor etc.) can be shared between the SSL and non-SSL instances. This would result in the following actions:
When code changes are involved (maintenance, technical previews, new release), or your changes are fairly complex, it is advised to 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 below.
//SYSIN DD * CREATE PROCEDURE SYSPROC.ELAXMRXX ( IN FUNCTION_REQUEST VARCHAR(20) CCSID EBCDIC ... , OUT RETURN_VALUE VARCHAR(255) CCSID EBCDIC ) PARAMETER STYLE GENERAL RESULT SETS 1 LANGUAGE REXX EXTERNAL NAME ELAXMRXX COLLID DSNREXCS WLM ENVIRONMENT ELAXMWDZ PROGRAM TYPE MAIN MODIFIES SQL DATA STAY RESIDENT NO COMMIT ON RETURN NO ASUTIME NO LIMIT SECURITY USER; COMMENT ON PROCEDURE SYSPROC.ELAXMRXX IS 'PLI & COBOL PROCEDURE PROCESSOR (ELAXMRXX), INTERFACE LEVEL 0.01'; GRANT EXECUTE ON PROCEDURE SYSPROC.ELAXMRXX TO PUBLIC; //
This appendix is provided to assist you with some common problems that you may encounter during your configuration of Developer for System z.
More information is available through the Support section of the Developer for System z website (http://www-306.ibm.com/software/awdtools/devzseries/support/) where you can find technotes that bring you the latest information from our support team.
In the Library section of the website you can also find the latest version of the Developer for System z documentation, including whitepapers.
Valuable information can also be found in the z/OS internet library, available at http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/
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. 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:
Most log files are located in home/.eclipse/RSE/USERID/, where home is the home path defined in the user's OMVS segment (or the default OMVS segment if the user does not have and OMVS segment) and USERID is the logon user ID (uppercase).
/tmp/ holds log files created before the user ID has been verified.
Logging of normal operations. The default value in the sample JCL hlq.SFEKSAMP(FEJJJCL) is SYSOUT=*.
Trace logging. The default value in the sample JCL hlq.SFEKSAMP(FEJJJCL) is SYSOUT=*. Tracing is activated with the -TV parameter, see Customize the JES Job Monitor startup JCL for more details.
When the APPC administration utility adds and modifies a transaction program (TP) profile, it checks the TP profile and its JCL for syntax errors. Output from this phase consists of TP profile syntax error messages, utility processing messages, and JCL conversion statements. Logging for messages from this phase is controlled by the SYSPRINT DD statement for the ATBSDFMU utility. The default value in sample JCL hlq.SFEKSAMP(FEKAPPCC) is SYSOUT=*. See MVS Planning: APPC/MVS Management (SA22-7599) for more details.
When a TP executes, the TP runtime messages, such as allocation and termination messages, go to a log named by the MESSAGE_DATA_SET keyword in its TP profile. The default value in sample JCL hlq.SFEKSAMP(FEKAPPCC) is &SYSUID.FEKFRSRV.&TPDATE.&TPTIME.LOG See MVS Planning: APPC/MVS Management (SA22-7599) for more details.
There are several log files created by the components related to RSE, most of them located in home/.eclipse/RSE/USERID/, where home is the home path defined in the user's OMVS segment (or the default OMVS segment if the user does not have and OMVS segment) and USERID is the logon user ID (uppercase).
The amount of data written to ffs*.log, lock.log and rsecomm.log is controlled by setting debug_level in rsecomm.properties. See (Optional) Customize rsecomm.properties, RSE trace configuration for more details.
This file contains a log of the daemon before login.
Output of the fekfivpc -file command (SCLM Developer Toolkit related IVP test), where home is the home path defined in the user's OMVS segment (or the default OMVS segment if the user does not have and OMVS segment) and USERID is the logon user ID (uppercase).
Refer to TSO Commands service connection (using SCLMDT) for more details.
Fault Analyzer integration logging, where home is the home path defined in the user's OMVS segment (or the default OMVS segment if the user does not have and OMVS segment) and USERID is the logon user ID (uppercase).
When opening a connection with File Manager, a server job will be started, with the user's user ID as owner. Its name is FEKport, where port is the TCP/IP port used.
The SYSPRINT of the server job holds the FMI server logging.
Communication logging of FMI, where home is the home path defined in the user's OMVS segment (or the default OMVS segment if the user does not have and OMVS segment) and USERID is the logon user ID (uppercase).
The amount of data written to this file is controlled by setting debug_level in rsecomm.properties. See (Optional) Customize rsecomm.properties, RSE trace configuration for more details.
When opening a connection with CARMA, hlq.SCRACLST(SCRASUBMT) will start a server job (with the user's user ID as owner) named CRAport, where port is the TCP/IP port used.
If DD statement CARMALOG is specified in hlq.SCRACLST(SCRASUBMT), CARMA logging is redirected to this DD statement in the server job, otherwise it goes to SYSPRINT.
The amount of logging is controlled by setting Trace Level on the client. See (Optional) Activating IBM Common Access Repository Manager (CARMA) for more details on setting Trace Level.
The SYSPRINT of the server job holds the CARMA logging, if DD statement CARMALOG is not defined.
Communication logging of CARMA, where home is the home path defined in the user's OMVS segment (or the default OMVS segment if the user does not have and OMVS segment) and USERID is the logon user ID (uppercase).
The amount of data written to this file is controlled by setting debug_level in rsecomm.properties. See (Optional) Customize rsecomm.properties, RSE trace configuration for more details.
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.
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 the MVS JCL Reference (SA22-7597) and the Language Environment Debugging Guide (GA22-7560) for more information on these DD statements.
In z/OS UNIX, 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.
The types of dump that can be produced are:
The dump is written to a sequential MVS data set, using a default name of the form &userid.JVM.TDUMP.&jobname.D&date.T&time, 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.
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.
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.
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 the Java Diagnostic Guide (SC34-6358) for more information on JVM dumps, and the Language Environment Debugging Guide (GA22-7560) for LE specific information
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.
Remote Systems Explorer (RSE) is the Developer for System z component that provides core services like connecting the client to the host. It must run program controlled in order to perform tasks like switching to the user ID of the client.
The program control bit is set during SMP/E install where needed.
This result can be verified with the ls -lE fekf* command, which gives an output like the following sample ($ is the z/OS UNIX prompt):
$ ls -lE /usr/lpp/wd4z/rse/lib/fekf* -rwxr-xr-x -ps- 2 user group 94208 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfdir.dll -rwxr-xr-x -ps- 2 user group 143360 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfdivp -rwxr-xr-x --s- 2 user group 480 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfivpa -rwxr-xr-x --s- 2 user group 342 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfivpc -rwxr-xr-x --s- 2 user group 445 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfivpd -rwxr-xr-x --s- 2 user group 1491 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfivpj -rwxr-xr-x --s- 2 user group 883 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfivpr -rwxr-xr-x --s- 2 user group 307 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfivps -rwxr-xr-x -ps- 2 user group 139264 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekflock -rwxr-xr-x -ps- 2 user group 196608 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfrsed -rwxr-xr-x --s- 2 user group 42443 Jun 12 16:21 /usr/lpp/wd4z/rse/lib/fekfscmd
Issue the following commands if the program control bit needs to be set manually, assuming that the default install directory (/usr/lpp/wd4z/rse/lib/) is used:
1. cd /usr/lpp/wd4z/rse/lib 2. extattr +p fekfdir.dll fekfivp fekflock fekfrsed
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.
MVS TCP/IP NETSTAT CS V1R7 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 INETD4 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
Another limitation that can exist is reserved TCP/IP ports. There are 2 common places to reserve TCP/IP ports:
This is the data set referred to by the PROFILE DD statement of the TCP/IP started task, often named SYS1.TCPPARMS(TCPPROF)
Refer to Communications Server: IP Configuration Guide (SC31-8775) for more information on these statements.
These reserved ports can be listed with the NETSTAT PORTL command (TSO or z/OS UNIX), which creates an output like in the example below:
MVS TCP/IP NETSTAT CS V1R7 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.
The RSE server, which is a Java UNIX process, requires a large region size to perform its functions. Therefore it is important to set large storage limits for OMVS address spaces.
An RSE server is started by INETD when a client connects to the RSE daemon port or when the client issues the startup script using REXEC/SSH. This is done using INETD's storage limits, so these must be set large enough.
Set MAXASSIZE in SYS1.PARMLIB(BPXPRMxx), which defines the default OMVS address space (process) region size, to 2147483647 or larger.
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):
Check ASSIZEMAX in the client'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):
Make sure you're 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):
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.
//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)
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'
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
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) Define an 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 won't accept any connections.
The following list is a selection of technotes currently available on the support website (http://www-306.ibm.com/software/awdtools/devzseries/support/). Please refer to the support website for additional information:
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.
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 (like 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.
Reading and writing a 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(200) TYPE(UDS)
When using dynamic VIPA (Virtual IP address) across multiple TCPIP stacks, sysplex-wide coordination of assignment of ephemeral ports is required so that the 4-tuple (combination of source and destination IP addresses and ports) for each connection remains unique. This can be done by adding the optional SYSPLEXPORTS parameter to the first VIPADISTRIBUTE statement, as described in the IP Configuration Guide (SC31-8775).
When you use this technique, ensure that the EZBEPORT coupling facility structure (containing sysplex port assignment information) has been defined. Refer to the SNA Network Implementation Guide (SC31-8777) for information on how to do this.
If you are still experiencing difficulty after reading this manual and checking the support website (http://www-306.ibm.com/software/awdtools/devzseries/support/), and assistance is required from IBM support, please gather the following information and open a problem record with IBM:
The following information is useful for solving connection problems
If you use SCLM Developer Toolkit for the TSO Commands service (default method)
If you use APPC for the TSO Commands service
Provide all information that seams relevant for functional problems, like
This appendix is provided to assist you with some common problems that you may encounter when setting up TCP/IP, or during checking and/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.
Developer for System z is dependant 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 TSO command HOMETEST. Refer to Communications Server: IP System Administrator's Commands (SC31-8781) for more information on the HOMETEST command.
Example output of the HOMETEST command:
Running IBM MVS TCP/IP CS V1R7 TCP/IP Configuration Tester The FTP configuration parameter file used will be "SYS1.TCPPARMS(FTPDATA)" TCP Host Name is: CDFMVS08 Using Name Server to Resolve CDFMVS08 The following IP addresses correspond to TCP Host Name: CDFMVS08 9.42.112.75 The following IP addresses are the HOME IP addresses defined in PROFILE.TCPIP: 9.42.112.75 127.0.0.1 All IP addresses for CDFMVS08 are in the HOME list! Hometest was successful - all Tests Passed!
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.
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.
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.
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 as follows:
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.
The value of the environment variable is used. This search will fail if the file does not exist or is allocated exclusively elsewhere.
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.
userid is the user ID that is associated with the current security environment (address space or task/thread).
jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.
If defined, the resolver DEFAULTTCPIPDATA setup statement value is used (see also Understanding resolvers).
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 as follows. The search order ends at the first file found:
userid is the user ID that is associated with the current security environment (address space or task/thread).
jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.
hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.
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 as follows. The search ends at the first file found:
The value of the environment variable is the name of the HOSTS.SITEINFO information file created by the TSO MAKESITE command.
The value of the environment variable is the name of the HOSTS.ADDRINFO information file created by the TSO MAKESITE command.
userid is the user ID that is associated with the current security environment (address space or task/thread).
jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.
hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.
As stated before, Developer for System z is dependant 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.
In the example below we will focus on some configuration tasks for TCP/IP and Resolver. Note that this does not cover a complete set up of TCP/IP or Resolver, it just highlights some key aspects that might be applicable to your site.
//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=*
; 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
//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
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.
# 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, it is advised to keep the TCP/IP and Resolver configuration files in sync with each other.
File type description | APIs affected | Candidate files |
---|---|---|
Base resolver configuration files | All APIs |
|
Translate tables | All APIs |
|
Local host tables |
endhostent endnetent getaddrinfo gethostbyaddr gethostbyname gethostent GetHostNumber GetHostResol GetHostString getnameinfo getnetbyaddr getnetbyname getnetent IsLocalHost Resolve sethostent setnetent |
IPv4
IPv6
|
This appendix is provided to assist you with some common problems that you may encounter when setting up INETD, or during checking and/or modifying an existing setup.
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 (like 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.
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
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 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 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.
INETD uses ETC.SERVICES to map port numbers and protocols to the services it must support. It can be either a 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 4 positional fields, corresponding to the form:
service_name port_number/protocol aliases
The search order used to access ETC.SERVICES in z/OS UNIX is as follows. The search ends at the first file found:
userid is the user ID that is used to start INETD
.hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.
The search order used to access ETC.SERVICES in native MVS is as follows. The search ends at the first data set found:
The data set allocated to DD statement SERVICES is used.
userid is the user ID that is used to start INETD
.jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.
hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.
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, it is advised to 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:
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.
The z/OS UNIX implementation of INETD is located by default in /usr/sbin/inetd and supports 2 optional, non-positional, startup parameters:
/usr/sbin/inetd [-d] [inetd.conf]
It is advised to 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.
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
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 send 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
The BPXBATCH startup method works both for STC's 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 Figure 11 is a sample procedure to start INETD (the KILL step removes an active INETD process, if any):
//INETD PROC PRM= //* //KILL EXEC PGM=BPXBATCH, // PARM='SH ps -e | grep inetd | cut -c 1-10 | xargs -n 1 kill' //* //INETD EXEC PGM=BPXBATCH,TIME=NOLIMIT,REGION=0M, // PARM='PGM /usr/sbin/inetd &PRM' //STDERR DD PATH='/tmp/bpxbatch.start.inetd.stderr', // PATHOPTS=(OWRONLY,OCREAT,OTRUNC), // PATHMODE=SIRWXU //* STDIN, STDOUT and STDENV are defaulted to /dev/null //* INETD daemon output can be controlled by syslogd settings //*
// PARM='PGM /usr/sbin/inetd //''SYS1.TCPPARMS(INETCONF)'' &PRM'
When started from within a shell session, INETD uses the z/OS UNIX search 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):
1. # ps -e | grep inetd 7 ? 0:00 /usr/sbin/inetd 2. # kill 7 3. # _BPX_JOBNAME='INETD' /usr/sbin/inetd
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 like 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 a 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.
This is not recommended for "human" user IDs since there are no z/OS UNIX related restrictions.
Allows the user can become UID 0 through the su command. This is the recommended setup.
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 is dependant upon INETD for setting up the client-host connection. It also imposes extra requirements on top of the INETD setup described above.
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.
The RSE daemon that is started by INETD when a client connects to port 4035 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 RSE daemon (in inetd.conf) requires the following permissions:
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.
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. Secure Sockets Layer (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 the 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 connection that will use SSL. Both REXEC and the daemon connection method will be set up for SSL. We will also create our own security certificates to be used by the different parts of the RSE connection. All this will be done in the following steps:
Throughout this appendix, a uniform naming convention is used:
Most 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.
In this step a new instance of the RSE server and RSE daemon is created to run parallel with the existing one(s). This way, SSL testing will not hinder normal operations. As advised in Saving the rsed.envvars configuration file in another directory, the sample commands below expect the configuration files to be in /etc/wd4z/
$ cd /etc/wd4z $ mkdir ssl $ cp * ssl cp: FSUM6254 "ssl" is a directory (not copied) $ ls ssl rsecomm.properties server.zseries ssl.properties rsed.envvars setup.env.zseries $ cd ssl $ su # oedit /etc/services rsessl 4047/tcp #Developer for System z RSE using SSL
add rsessl service, using port 4047
# oedit /etc/inetd.conf rsessl stream tcp nowait OMVSKERN /usr/lpp/wd4z/rse/lib/fekfrsed rsed -d /etc/wd4z/ssl
add rsessl daemon, using configuration directory /etc/wd4z/ssl
# ps -e | grep inetd 7 ? 0:00 /usr/sbin/inetd # kill 7 # _BPX_JOBNAME='INETD' /usr/sbin/inetd # exit $ netstat | grep 4047 INETD4 00016619 0.0.0.0..4047 0.0.0.0..0 Listen
The commands listed above create a subdirectory called ssl and populate it with the mandatory configuration files. No configuration changes need to be made (yet). We can share the installation directory and MVS components since they are not SSL specific. However, a new daemon (rsessl) must be defined that uses the new configuration files. Port 4047 is assigned to the new daemon.
Refer to Activating Developer for System z z/OS UNIX components for more information on the actions shown above.
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.
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 security software (e.g. RACF). The RSE server (which is started by the daemon or REXEC) is a Java SSL application, and uses a key store file created by keytool. Currently, RACF has no out-of-the-box support for Java SSL.
Thus to connect via REXEC, all we need is the key store file:
To connect via the daemon, we need both the key store and the key database file:
Refer to the 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). keytool documentation is available at http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html.
"keytool -genkey" Generates a key pair (a public key and associated private key). It then wraps the public key into an X.509 v1 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 (new) key store file.
All information can be passed as a parameter, but due to command line length limitations some interactivity is required.
$ keytool -genkey -alias wd4zrse -validity 3650 -keystore wd4zssl.jks -storepass rsessl -keypass rsessl What is your first and last name? [Unknown]: wd4z rse ssl What is the name of your organizational unit? [Unknown]: wd4z 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=wd4z rse ssl, OU=wd4z, O=IBM, L=Raleigh, ST=NC, C=US correct? (type "yes" or "no") [no]: yes $ ls rsecomm.properties server.zseries ssl.properties rsed.envvars setup.env.zseries wd4zssl.jks
The self-signed certificate created above is valid for about 10 years (not counting leap days). It is stored in /etc/wd4z/ssl/wd4zssl.jks using alias wd4zrse. 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:
$ keytool -list -alias wd4zrse -keystore wd4zssl.jks -storepass rsessl -v Alias name: wd4zrse Creation date: May 24, 2007 Entry type: keyEntry Certificate chain length: 1 Certificate 1¨: Owner: CN=wd4z rse ssl, OU=wd4z, O=IBM, L=Raleigh, ST=NC, C=US Issuer: CN=wd4z rse ssl, OU=wd4z, 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
As mentioned before, the daemon is a System SSL application that uses a key database. This can be either a physical file created by gskkyman or a RACF key ring. RACF key rings are the preferred method for managing private keys and certificates for System SSL.
Do not execute this step if you use gskkyman for System SSL.
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 the 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(omvskern) PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(omvskern) SETROPTS RACLIST(FACILITY) REFRESH RACDCERT ID(omvskern) GENCERT SUBJECTSDN(CN('wd4z rse ssl') + OU('wd4z') O('IBM') L('Raleigh') SP('NC') C('US')) + NOTAFTER(DATE(2017-05-21)) WITHLABEL('wd4zrse') KEYUSAGE(HANDSHAKE) RACDCERT ID(omvskern) ADDRING(wd4zssl.racf) RACDCERT ID(omvskern) CONNECT(LABEL('wd4zrse') RING(wd4zssl.racf) + DEFAULT USAGE(PERSONAL))
The sample above starts by creating the necessary profiles and permitting user ID OMVSKERN access to key rings. The user ID used must match the user ID coded in /etc/inetd.conf for the SSL RSE daemon. The next step is creating a new, self-signed, certificate with label wd4zrse. No password is needed. This certificate is then added to a newly created key ring (wd4zssl.racf). Just as with the certificate, no password is needed for the key ring. The lifespan of the certificate matches the one created with keytool.
The result can be verified with the list option:
RACDCERT ID(omvskern) LIST Digital certificate information for user OMVSKERN: Label: wd4zrse 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=wd4z rse ssl.OU=wd4z.O=IBM.L=Raleigh.SP=NC.C=US< Subject's Name: >CN=wd4z rse ssl.OU=wd4z.O=IBM.L=Raleigh.SP=NC.C=US< Private Key Type: Non-ICSF Private Key Size: 1024 Ring Associations: Ring Owner: OMVSKERN Ring: >wd4zssl.racf<
Do not execute this step if you use RACF for System SSL.
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.
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
$ gskkyman Database Menu 1 - Create new database 2 - Open database 3 - Change database password 4 - Change database record length 5 - Delete database 6 - Create key parameter file 0 - Exit program Enter option number: 1 Enter key database name (press ENTER to return to menu): wd4zssl.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/wd4z/ssl/wd4zssl.kdb created. Press ENTER to continue. Key Management Menu Database: /etc/wd4z/ssl/wd4zssl.kdb 1 - Manage keys and certificates 2 - Manage certificates 3 - Manage certificate requests 4 - Create new certificate request 5 - Receive requested certificate or a renewal certificate 6 - Create a self-signed certificate 7 - Import a certificate 8 - Import a certificate and a private key 9 - Show the default key 10 - Store database password 11 - Show database record length 0 - Exit program Enter option number (press ENTER to return to previous menu): 6 Certificate Type 1 - CA certificate with 1024-bit RSA key 2 - CA certificate with 2048-bit RSA key 3 - CA certificate with 4096-bit RSA key 4 - CA certificate with 1024-bit DSA key 5 - User or server certificate with 1024-bit RSA key 6 - User or server certificate with 2048-bit RSA key 7 - User or server certificate with 4096-bit RSA key 8 - User or server certificate with 1024-bit DSA key Select certificate type (press ENTER to return to menu): 5 Enter label (press ENTER to return to menu): wd4zrse Enter subject name for certificate Common name (required): wd4z rse ssl Organizational unit (optional): wd4z 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 Database: /etc/wd4z/ssl/wd4zssl.kdb 1 - Manage keys and certificates 2 - Manage certificates 3 - Manage certificate requests 4 - Create new certificate request 5 - Receive requested certificate or a renewal certificate 6 - Create a self-signed certificate 7 - Import a certificate 8 - Import a certificate and a private key 9 - Show the default key 10 - Store database password 11 - Show database record length 0 - Exit program Enter option number (press ENTER to return to previous menu): 0 $ ls -l total 152 -rwxr-xr-x 1 IBMUSER SYS1 333 May 24 13:52 rsecomm.properties -rwxr-xr-x 1 IBMUSER SYS1 6067 May 24 13:52 rsed.envvars -rwxr-xr-x 1 IBMUSER SYS1 332 May 24 13:52 server.zseries -rwxr-xr-x 1 IBMUSER SYS1 645 May 24 13:52 setup.env.zseries -rwxr-xr-x 1 IBMUSER SYS1 638 May 24 13:52 ssl.properties -rw-r--r-- 1 IBMUSER SYS1 1224 May 24 14:17 wd4zssl.jks -rw------- 1 IBMUSER SYS1 35080 May 24 14:24 wd4zssl.kdb -rw------- 1 IBMUSER SYS1 80 May 24 14:24 wd4zssl.rdb $ chmod 644 wd4zssl.kdb $ chmod 644 wd4zssl.rdb $ ls -l total 152 -rwxr-xr-x 1 IBMUSER SYS1 333 May 24 13:52 rsecomm.properties -rwxr-xr-x 1 IBMUSER SYS1 6067 May 24 13:52 rsed.envvars -rwxr-xr-x 1 IBMUSER SYS1 332 May 24 13:52 server.zseries -rwxr-xr-x 1 IBMUSER SYS1 645 May 24 13:52 setup.env.zseries -rwxr-xr-x 1 IBMUSER SYS1 638 May 24 13:52 ssl.properties -rw-r--r-- 1 IBMUSER SYS1 1224 May 24 14:17 wd4zssl.jks -rw-r--r-- 1 IBMUSER SYS1 35080 May 24 14:24 wd4zssl.kdb -rw-r--r-- 1 IBMUSER SYS1 80 May 24 14:24 wd4zssl.rdb
The sample above starts by creating a key database called wd4zssl.kdb with password rsessl. Once the database exists, it is populated by creating a new, self-signed, certificate stored under label wd4zrse and with the same password (rsessl) as the one used for the key database (this is a 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. 640 (owner has read/write, owner's group has read) or 644 (owner has read/write, everyone has read) are usable masks for the chmod command.
The result can be verified by selecting the Show certificate information option in the Manage keys and certificates submenu:
$ gskkyman Database Menu 1 - Create new database 2 - Open database 3 - Change database password 4 - Change database record length 5 - Delete database 6 - Create key parameter file 0 - Exit program Enter option number: 2 Enter key database name (press ENTER to return to menu): wd4zssl.kdb Enter database password (press ENTER to return to menu): rsessl Key Management Menu Database: /etc/wd4z/ssl/wd4zssl.kdb 1 - Manage keys and certificates 2 - Manage certificates 3 - Manage certificate requests 4 - Create new certificate request 5 - Receive requested certificate or a renewal certificate 6 - Create a self-signed certificate 7 - Import a certificate 8 - Import a certificate and a private key 9 - Show the default key 10 - Store database password 11 - Show database record length 0 - Exit program Enter option number (press ENTER to return to previous menu): 1 Key and Certificate List Database: /etc/wd4z/ssl/wd4zssl.kdb 1 - wd4zrse 0 - Return to selection menu Enter label number (ENTER to return to selection menu, p for previous list): 1 Key and Certificate Menu Label: wd4zrse 1 - Show certificate information 2 - Show key information 3 - Set key as default 4 - Set certificate trust status 5 - Copy certificate and key to another database 6 - Export certificate to a file 7 - Export certificate and key to a file 8 - Delete certificate and key 9 - Change label 10 - Create a signed certificate and key 11 - Create a certificate renewal request 0 - Exit program Enter option number (press ENTER to return to previous menu): 1 Certificate Information Label: wd4zrse Record ID: 14 Issuer Record ID: 14 Trusted: Yes Version: 3 Serial number: 45356379000ac997 Issuer name: wd4z rse ssl wd4z IBM Raleigh NC US Subject name: wd4z rse ssl wd4z 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 Label: wd4zrse 1 - Show certificate information 2 - Show key information 3 - Set key as default 4 - Set certificate trust status 5 - Copy certificate and key to another database 6 - Export certificate to a file 7 - Export certificate and key to a file 8 - Delete certificate and key 9 - Change label 10 - Create a signed certificate and key 11 - Create a certificate renewal request 0 - Exit program Enter option number (press ENTER to return to previous menu): 0
Now that the certificates are in place, RSE can start using SSL. Depending on the definitions chosen in the steps above, different values must be provided in ssl.properties.
$ oedit ssl.properties
The SSL host setup is now complete and can 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, using following characteristics:
STEPLIB=SYS1.SIEALNKE
STEPLIB=$STEPLIB:SYS1.SIEALNKE
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 it will prompt the user asking if this certificate can be trusted.
By clicking the Finish button the user can accept this certificate as trusted, after which the connection initialization continues.
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:
If SSL communication fails, the client will return an error message. More information is available in the different log files (home/.eclipse/RSE/USERID/* and /tmp/rsedaemon.log), as described in RSE logging.
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 and/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.
APPC/MVS stores its configuration data in 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 sample job listed in figure 14 is a concatenation of sample members SYS1.SAMPLIB(ATBTPVSM) and SYS1.SAMPLIB(ATBSIVSM), and can be used to define the 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)) //*
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, like 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:
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.
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 the Communications Server bookshelf (F1A1BK61 for z/OS 1.7) for more information on configuring VTAM.
To enable and support the flow of conversations between systems, sites must define LUs (Logical Units) 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.
Figure 16 is a sample SYS1.PARMLIB(APPCPMxx) member that can be used for the TSO Commands service.
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:
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 Customize rsed.envvars, the configuration file for RSE for more information on rsed.envvars.
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 remote edit-compile-debug.
The TSO Commands service also needs the default specifications to be specified in the OPTIONS and TPDEFAULT sections.
Figure 17 is a sample SYS1.PARMLIB(ASCHPMxx) member that can be used for the TSO Commands service.
CLASSADD CLASSNAME(A) MAX(20) MIN(1) MSGLIMIT(200) OPTIONS DEFAULT(A) TPDEFAULT REGION(2M) TIME(5) MSGLEVEL(1,1) OUTCLASS(X)
The configuration changes documented in the steps above can now be activated. This can be done in various ways, depending on the circumstances:
Add these commands to SYS1.PARMLIB(COMMNDxx) to start them at system startup.
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.
Once APPC/MVS is active, the Developer for System z TSO Commands service can be defined, as described in (Optional) Define an APPC transaction for the TSO Commands service.
The documented way to define the APPC transaction is by customizing and submitting hlq.SFEKSAMP(FEKAPPCC), where hlq equals the high level qualifier used during the installation of Developer for System z (default FEK).
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/
// PARM='ISPSTART CMD(%FEKFRSRV TIMEOUT=60) NEWAPPL(ISR) NESTMACS'
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
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:
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 measurement 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 illustrates 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. 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 IBM's application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:
(C) (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. (C) Copyright IBM Corp. _enter the year or years_. All rights reserved.
The following terms are trademarks or registered trademarks of International Business Machines 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.
Microsoft(R), Windows(R), Windows NT(R), and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, or other countries, or both.
UNIX is a registered trademark of The Open Group.
Other company, product, and service names, which may be denoted by a double asterisk(**), may be trademarks or service marks of others.