Important: After you have installed the base version of the IBM OS/390 Foreign File System as instructed below, you must install the latest PTF, which is included on the VisualAge PL/I CD-ROM. See Installing updates for FFS for more information.

Configuring OS/390 for remote ECD: overview

When developers use VisualAge PL/I to edit, compile, or debug files that are on OS/390, communications between the workstation and OS/390 are through Transmission Control Protocol/Internet Protocol (TCP/IP). In addition, VisualAge PL/I relies on four servers:

The foreign file system server communicates between the workstation and the host through the HTTP protocol. The IBM HTTP Server (formerly Domino Go Webserver) runs under UNIX System Services (formerly Open Edition) in OS/390. The server must be installed under the hierarchical file system (HFS) of UNIX System Services and configured for the remote capability of VisualAge PL/I. This server communicates with the foreign file system server through the GoWebserver API (GWAPI).

Before developers can communicate with the host using TCP/IP, a system programmer must configure the host for remote edit-compile-debug. The general steps are shown in the checklist below.

Step For details, see: Done?
Make sure that the appropriate required software and service updates are installed:
  • TCP/IP
  • OS/390 Language Environment
  • IBM HTTP Server
  • Resource Access Control Facility (RACF) or equivalent
  • Enterprise PL/I for z/OS and OS/390 or VisualAge PL/I for OS/390 Full Function Offerings (with Debug Tool)
Installing the prerequisite OS/390 software  
Install the foreign file system server and job monitor server. Installing the foreign file system server and job monitor server  
Configure the IBM HTTP Server. Configuring the IBM HTTP Server  
Configure the software that comes with VisualAge PL/I for the host to support remote edit-compile-debug:
  • Foreign file system server
  • Job monitor server
Configuring the foreign file system server

Configuring the job monitor server

 
Install and configure the TSO commands server (optional) to support issuing TSO commands from the workstation. Installing and configuring the TSO commands server (optional)  
Configure Debug Tool for remote debugging under CICS. Configuring OS/390 for remote debugging under CICS  
Test the connections.    

RELATED REFERENCES
TCP/IP V3R2 for MVS: Customization and Administration, SC31-7134
TCP/IP V3R2 for MVS Bookshelf
IBM HTTP Server: Planning, Installing, and Using, SC31-8690

Installing the prerequisite OS/390 software

Before you configure communications for remote editing, compiling, and debugging using IBM VisualAge PL/I for Windows NT, Version 2.1.10, you must install the following software:

The program directory provided with any of these host products details the installation process using SMP/E RECEIVE, APPLY, and ACCEPT commands. It also gives up-to-date service information, including PTFs or APARs that you need to apply.

Because of a defect caused by DB2 UDB for OS/390 Version 6.1 and later, programmers cannot use mixed SBCS and DBCS data in the REMARKS column of an OS/390 DB2 stored procedure definition. To enable this use, you need to update the FOREIGNKEY column for the SYSIBM.SYSROUTINES table as follows:

UPDATE SYSIBM.SYSCOLUMNS SET FOREIGNKEY=' '
WHERE TBNAME = 'SYSROUTINES' and NAME='REMARKS';

RELATED TASKS
Configuring OS/390 for remote ECD: overview
IBM HTTP Server: Planning, Installing, and Using, SC31-8690
IBM HTTP Server Troubleshooting Guide
Domino Go Release 5.0 Webmaster's Guide, SC31-8691
OS/390: Planning for Installation, GC28-1726

Installing the foreign file system server and job monitor server

This material is intended for the system programmer responsible for installing and maintaining programs. It contains information concerning the material and procedures associated with the installation of the OS/390 IBM Foreign File System, which contains the foreign file system server and the job monitor server. You should read all of this material before installing the OS/390 Foreign File System and then keep it for future reference.

The material contains the following sections:

Before installing the OS/390 Foreign File System, read Preventive service planning. This section tells you how to find any updates to the information and procedures in this chapter.

Description of the the OS/390 Foreign File System components

The OS/390 Foreign File System has two major components:

The OS/390 Foreign File System and the associated clients are available with VisualAge PL/I V2.1.10.

OS/390 Foreign File System FMID

The OS/390 Foreign File System consists of the following FMID:

HFBN100

Program materials

An IBM program is identified by a program number and a feature number. The program number for VA PL/I V2.1.10 is 5639-D65.

Basic machine-readable materials are materials that are supplied under the base license and feature code, and are required for the use of the product. Optional machine-readable materials are orderable under separate feature codes, and are not required for the product to function.

Basic machine-readable material

The OS/390 Foreign File System is distributed on the VA PL/I V2.1.10 CD-ROM. The OS/390 Foreign File System is provided on the CD-ROM in a format that can be uploaded to the OS/390, expanded into SMP/E RELFILE format, then installed using SMP/E. See Installation instructions for more information about how to install the program.

The following table describes the OS/390 file content of the CD-ROM:

Directory Name Description
Hfbn100 FBN.IBM.HFBN100.SEQ5JCL Sample job to allocate sequential data sets on the OS/390 for the compressed RELFILEs and SMPMCS
Hfbn100 FBN.IBM.HFBN100.F1.BIN RELFILE in compressed form
Hfbn100 FBN.IBM.HFBN100.F2.BIN RELFILE in compressed form
Hfbn100 FBN.IBM.HFBN100.F3.BIN RELFILE in compressed form
Hfbn100 FBN.IBM.HFBN100.F4.BIN RELFILE in compressed form
Hfbn100 FBN.IBM.HFBN100.SMPMCS SMPMCS file
Optional machine-readable material

No optional machine-readable materials are provided for the OS/390 Foreign File System.

Program support

This section describes the IBM support available for the OS/390 Foreign File System.

Program services

Contact your IBM representative for specific information about available program services.

Preventive service planning

Before installing the OS/390 Foreign File System, you should review the current preventive service planning (PSP) information. Contact the IBM Support Center or use S/390 SoftwareXcel to obtain the current PSP bucket.

PSP buckets are identified by upgrades, which specify product levels, and subsets, which specify the FMIDs for a product level. The subset value for the OS/390 Foreign File System is HFBN100. Since the OS/390 Foreign File System is a shared component between VA PL/I and VA COBOL, you will check the IBM COBOL Web site for the upgrade value, as well as for additional support and preventive service information.

Statement of support procedures

Report any difficulties you have using this program to your IBM Support Center. If an APAR is required, the Support Center will provide the address to which any needed documentation can be sent.

The following table identifies the component IDs (COMPID) for the OS/390 Foreign File System:

FMID COMPID Component name RETAIN release
HFBN100 5639I4402 Foreign File System 1.0.0 100

Program and service level information

This section identifies the program and any relevant service levels of the OS/390 Foreign File System. The program level refers to the APAR fixes incorporated into the program. The service level refers to the PTFs integrated.

Program level information

No APARs have been incorporated into the OS/390 Foreign File System.

Service level information

No PTFs against this release of the OS/390 Foreign File System have been incorporated into the product.

Installation requirements and considerations

The following sections identify the system requirements for installing and activating the OS/390 Foreign File Systems. The following terminology is used:

In many cases, the same system can be used as both a driving system and a target system. However, you may want to set up a clone of your system to use as a target system by making a separate IPL-able copy of the running system. The clone should include copies of all system libraries that SMP/E updates, copies of the SMP/E CSI data sets that describe the system libraries, and your PARMLIB and PROCLIB.

Some cases where two systems should be used include the following:

Driving system requirements

This section describes the environment of the driving system required to install the OS/390 Foreign File System.

Machine requirements

The driving system can run in any hardware environment that supports the required software.

Programming requirements

The following table shows the software requirements for the driving system:

Program number Product name and minimum VRM/service level
Any one of the following:
5647-A01 OS/390 SMP/E Version 2 Release 5 with PTF UR51068
5647-A01 OS/390 SMP/E Version 2 Release 6 with PTF UR51068
5647-A01 OS/390 SMP/E Version 2 Release 7 or higher
Target system requirements

This section describes the environment of the target system required to install and use the OS/390 Foreign File System.

The OS/390 Foreign File System installs in the MVS (Z038) SREL.

Machine requirements

The target system can run in any hardware environment that supports the required software.

Programming requirements
Mandatory requisites

A mandatory requisite is defined as a product that is required without exception; this product either will not install or will not function unless this requisite is met. This includes products that are specified as REQs or PREs. The mandatory requisite for installing

Program number Product name and minimum VRM/service level
5647-A01 OS/390 Version 2 Release 5 or higher
Functional requisites

A functional requisite is defined as a product that is not required for the successful installation of this product or for the basic function of the product, but is needed at run time for a specific function of this product to work. This includes products that are specified as IF REQs.

See Installing the prerequisite OS/390 software for the list of functional requisites.

DASD storage requirements

OS/390 Foreign File System libraries can reside on any currently supported DASD.

The following table lists the total space required for each type of library:

Library type Total space required
Target 13 tracks
Distribution 31 tracks
HFS 18 tracks

For more information on the names and sizes of the required data sets, please refer to Allocate SMP/E target and distribution libraries and paths.

The following tables describe the target and distribution libraries and HFS paths required to install the OS/390 Foreign File System. The storage requirements of the OS/390 Foreign File System must be added to the storage required by other programs having data in the same library or path.

Note: The data in these tables should be used when you determine which libraries can be merged into common data sets. In addition, because some ALIAS names may not be unique, ensure that no naming conflicts will be introduced before you merge libraries.

The following table shows the storage requirements for the OS/390 Foreign File System target libraries:

Library
DDNAME
Member
type
Target
volume
Type Org RECFM LRECL No. of
3390 tracks
No. of
dir blocks
SFBNLOAD LMOD ANY U PDS U 0 7 2
SFBNSAMP Sample ANY U PDS FB 80 4 3
SFBNSAMV Sample ANY U PDS VB 80 2 2

The following table shows the HFS paths for the OS/390 Foreign File System:

DDNAME Path name
SFBNFBIN usr/lpp/ffsserver/bin
SFBNFLIB usr/lpp/ffsserver/lib
SFBNFSAM usr/lpp/ffsserver/samples
SFBNFWEB usr/lpp/ffsserver/WebServ

The following table shows the storage requirements forthe OS/390 Foreign File System distribution libraries:

Library
DDNAME
Type Org RECFM LRECL No. of
3390 tracks
No. of
dir blocks
AFBNMOD1 U PDS U 0 8 2
AFBNSAMP U PDS FB 80 6 3
AFBNSAMV U PDS VB 80 2 2
AFBNFFSV U PDS VB 255 15 2

Installation instructions

This section describes the installation method and the step-by-step procedures to install the OS/390 Foreign File System.

Please note the following:

Installing the OS/390 Foreign File Systems
SMP/E considerations

This release of the OS/390 Foreign File System is installed using the SMP/E RECEIVE, APPLY, and ACCEPT commands. The SMP/E dialogs may be used to accomplish the SMP/E installation steps.

SMP/E options subentry values

The recommended values for some SMP/E CSI subentries are shown in the following table:

Subentry Value Comment
DSSPACE 300,150,250 Space allocation for SMPTLIB data sets
PEMAX SMP/E default IBM recommends using the SMP/E default for PEMAX.

Use of values lower than these may result in failures in the installation process. DSSPACE is a subentry in the GLOBAL options entry. PEMAX is a subentry of the GENERAL entry in the GLOBAL options entry. Refer to the SMP/E manuals for instructions on updating the global zone.

SMP/E CALLLIBS processing

The OS/390 Foreign File System uses the CALLLIBS function provided in SMP/E to resolve external references during installation. When the OS/390 Foreign File System is installed, ensure that DDDEFs exist for the following libraries:

Note: The DDDEFs above are used only to resolve the link-edit for the OS/390 Foreign File System using CALLLIBS. These data sets are not updated during the installation of the OS/390 Foreign File System.

Overview of the installation steps

Here are the steps required to install the OS/390 Foreign File System:

  1. Upload SEQ5JCL from the CD-ROM.
  2. Upload the compressed RELFILEs and SMPMCS from the CD-ROM.
  3. Expand the RELFILEs.
  4. Allocate and initialize the SMP/E data sets (optional).
  5. Perform SMP/E RECEIVE.
  6. Allocate SMP/E target and distribution libraries and paths.
  7. Create DDDEF entries.
  8. Perform SMP/E APPLY.
  9. Perform SMP/E ACCEPT.
Upload SEQ5JCL from the CD-ROM

There is a sample job provided on the CD-ROM that will allocate sequential data sets on the OS/390 for the four compressed RELFILEs and SMPMCS contained on the CD-ROM. Do the following to upload it from the CD-ROM to the OS/390:

  1. Allocate a data set for it on the OS/390. You can do this by submitting the job below. Add a job card and modify the parameters to meet your site's requirements before submitting.
    //ALLOC1    EXEC   PGM=IEFBR14
    //*
    //FTPALLO  DD  DSN=hlq.IBM.HFBN100.SEQ5JCL,
    //         DISP=(NEW,CATLG,DELETE),
    //         DSORG=PS,
    //         RECFM=FB,
    //         LRECL=80,
    //         BLKSIZE=6160,
    //         SPACE=(TRK,(2,1)),
    //         UNIT=SYSALLDA
    //*        VOL=SER=&TVOL1
    
  2. Upload the file in binary format from the CD-ROM to the OS/390 data set. If the CD-ROM is attached to a Windows NT system, you can use FTP from a command prompt to upload the file. In the sample dialog shown below, commands or other information entered by the user are in bold, and the following values are assumed:
    User enters: Values
    mvsaddr TCP/IP address of the OS/390
    tsouid Your TSO user ID
    tsopw Your TSO password
    d: Your CD-ROM drive
    hlq High-level qualifier you used for the data set you allocated in the job above
    C:\>ftp mvsaddr
    Connected to mvsaddr.
    220-FTPD1 IBM FTP CS V2R8 at mvsaddr, 07:18:16 on 2000-05-11.
    220 Connection will close if idle for more than 60 minutes.
    
    User (mvsaddr:(none)): tsouid
    
    331 Send password please.
    Password: tsopw
    230 tsouid is logged on.  Working directory is "tsouid.".
    
    ftp> cd ..
    250 "" is the working directory name prefix.
    
    ftp> cd hlq
    250 "hlq." is the working directory name prefix.
    
    ftp> binary
    200 Representation type is Image
    
    ftp> put d:\hfbn100\ibm.hfbn100.seq5jcl ibm.hfbn100.seq5jcl
    200 Port request OK.
    125 Storing data set hlq.ibm.hfbn100.seq5jcl
    250 Transfer completed successfully.
    8400 bytes sent in 0.34 seconds (24.63 Kbytes/sec)
    
    ftp> quit
    221 Quit command received. Goodbye.
    
Upload the compressed RELFILEs and SMPMCS from the CD-ROM
  1. Edit and submit sample job SEQ5JCL to allocate data sets for these files on the OS/390. Consult the instructions in the sample job for more information.
  2. Upload the files in binary format from the CD-ROM to the OS/390 data set. If the CD-ROM is attached to a Windows NT system, you can use FTP from a command prompt to upload the files:
    C:\>ftp mvsaddr
    Connected to mvsaddr.
    220-FTPD1 IBM FTP CS V2R8 at mvsaddr, 07:18:16 on 2000-05-11.
    220 Connection will close if idle for more than 60 minutes.
    
    User (mvsaddr:(none)): tsouid
    
    331 Send password please.
    Password: tsopw
    230 tsouid is logged on.  Working directory is "tsouid.".
    
    ftp> cd ..
    250 "" is the working directory name prefix.
    
    ftp> cd hlq
    250 "hlq." is the working directory name prefix.
    
    ftp> binary
    200 Representation type is Image
    
    ftp> prompt
    Interactive mode Off.
    
    ftp> mput d:\hfbn100\ibm.hfbn100.f*
    200 Port request OK.
    125 Storing data set hlq.IBM.HFBN100.F1.BIN
    250 Transfer completed successfully.
    194960 bytes sent in 0.39 seconds (499.90 Kbytes/sec)
    200 Port request OK.
    125 Storing data set hlq.IBM.HFBN100.F2.BIN
    250 Transfer completed successfully.
    202720 bytes sent in 0.40 seconds (506.80 Kbytes/sec)
    200 Port request OK.
    125 Storing data set hlq.IBM.HFBN100.F3.BIN
    250 Transfer completed successfully.
    1280 bytes sent in 0.00 seconds (1280000.00 Kbytes/sec)
    200 Port request OK.
    125 Storing data set hlq.IBM.HFBN100.F4.BIN
    250 Transfer completed successfully.
    471200 bytes sent in 0.91 seconds (517.23 Kbytes/sec)
    
    ftp> put d:\hfbn100\ibm.hfbn100.smpmcs
    200 Port request OK.
    125 Storing data set hlq.IBM.HFBN100.SMPMCS
    250 Transfer completed successfully.
    3760 bytes sent in 0.00 seconds (3760000.00 Kbytes/sec)
    
    ftp> quit
    221 Quit command received. Goodbye.
    
Expand the RELFILEs

You can expand the RELFILEs by using the TSO receive command:

  receive inda('hlq.ibm.hfbn100.f1.bin')
  receive inda('hlq.ibm.hfbn100.f2.bin')
  receive inda('hlq.ibm.hfbn100.f3.bin')
  receive inda('hlq.ibm.hfbn100.f4.bin')
Allocate and initialize the SMP/E data sets (optional)

You can install the VA PL/I OS/390 components in the same SMP/E zone as OS/390 Version 2 Release 5 (or later) or in a different zone.

Perform SMP/E RECEIVE

The sample installation jobs to help you install the OS/390 Foreign File System are listed in the following table:

Job name Job type Description RELFILE
FBNIRECV RECEIVE Sample RECEIVE job IBM.HFBN100.F1
FBNIALLO ALLOCATE Sample job to allocate target and distribution libraries IBM.HFBN100.F1
FBNISMKD MKDIR Sample job to invoke the supplied FBNIMKDR EXEC to allocate HFS paths IBM.HFBN100.F1
FBNIDDDF DDDEF Sample job to define SMP/E DDDEFs IBM.HFBN100.F1
FBNIAPPL APPLY Sample APPLY job IBM.HFBN100.F1
FBNIACCP ACCEPT Sample ACCEPT job IBM.HFBN100.F1

Before you edit and submit these jobs, you may want to copy them to another data set, so that you have the original to refer to.

Edit and submit sample job FBNIRECV to perform the SMP/E RECEIVE for the OS/390 Foreign File System. Consult the instructions in the sample job for more information.

Expected return codes and messages: You will get a return code of 0 if the jobs run correctly.

Allocate SMP/E target and distribution libraries and paths

Edit and submit sample job FBNIALLO to allocate the SMP/E target and distribution libraries for the OS/390 Foreign File System. Consult the instructions in the sample job for more information.

Expected return codes and messages: You will get a return code of 0 if the jobs run correctly.

Edit and submit sample job FBNISMKD to allocate the HFS paths for the OS/390 Foreign File System. Consult the instructions in the sample job for more information.

If you plan to create a new HFS for this product, you should consider updating the BPXPRMxx PARMLIB member to mount the new HFS at IPL time. This may be helpful if an IPL occurs before the installation is complete.

Expected return codes and messages: You will get a return code of 0 if the jobs run correctly.

Create DDDEF Entries

Edit and submit sample job FBNIDDDF to create DDDEF entries for the SMP/E target and distribution libraries for the OS/390 Foreign File System. Consult the instructions in the sample job for more information.

Expected return codes and messages: You will get a return code of 0 if the jobs run correctly. You may receive the following message for the first CHANGE command in the DEFPATH step: 'GIM2650W THE PATH SUBENTRY WAS NOT CHANGED.' This message is expected and can be ignored. If you receive this message, a return code of 4 is expected for the DEFPATH step.

Perform SMP/E APPLY

Edit and submit sample job FBNIAPPL to perform an SMP/E APPLY CHECK for the OS/390 Foreign File System. Consult the instructions in the sample job for more information.

To receive the full benefit of the SMP/E Causer SYSMOD Summary Report, do not bypass the following on the APPLY CHECK: PRE, ID, REQ, and IFREQ. This is because the SMP/E root cause analysis identifies the cause only of ERRORS and not of WARNINGS (SYSMODs that are bypassed are treated as warnings, not errors, by SMP/E).

After you have taken any actions indicated by the APPLY CHECK, remove the CHECK operand and run the job again to perform the APPLY.

Note: The GROUPEXTEND operand indicates that SMP/E apply all requisite SYSMODs. The requisite SYSMODs might be applicable to other functions.

Expected return codes and messages: You will get a return code of 0 if the jobs run correctly.

Perform SMP/E ACCEPT

Before you perform the SMP/E ACCEPT, you may want to do the configuration documented in Configuring the foreign file system server. This includes a procedure for verifying the install.

Edit and submit sample job FBNIACCP to perform an SMP/E ACCEPT CHECK for the OS/390 Foreign File System. Consult the instructions in the sample job for more information.

To receive the full benefit of the SMP/E Causer SYSMOD Summary Report, do not bypass the following on the ACCEPT CHECK: PRE, ID, REQ, and IFREQ. This is because the SMP/E root cause analysis identifies the cause only of ERRORS and not of WARNINGS (SYSMODs that are bypassed are treated as warnings, not errors, by SMP/E).

Before using SMP/E to load new distribution libraries, it is recommended that you set the ACCJCLIN indicator in the distribution zone. This will cause entries produced from JCLIN to be saved in the distribution zone whenever a SYSMOD containing inline JCLIN is accepted. For more information on the ACCJCLIN indicator, see the description of inline JCLIN in the SMP/E manuals.

After you have taken any actions indicated by the ACCEPT CHECK, remove the CHECK operand and run the job again to perform the ACCEPT.

Note: The GROUPEXTEND operand indicates that SMP/E apply all requisite SYSMODs. The requisite SYSMODs might be applicable to other functions.

Expected return codes and messages: You will get a return code of 0 if the jobs run correctly.

If PTFs containing replacement modules are being accepted with SMP/E, SMP/E ACCEPT processing will link-edit or bind the modules into the distribution libraries. During this processing, the Linkage Editor or Binder may issue messages documenting unresolved external references, resulting in a return code of 4 from the ACCEPT step. These messages can be ignored, because the distribution libraries are not executable and the unresolved external references will not affect the executable system libraries.

Notes: the OS/390 Foreign File System install logic
SMP/E modification control statements

The SMP/E modification control statements (SMPMCS) for the OS/390 Foreign File System are contained in the SMPMCS file uploaded from the distribution CD. The SMPMCS for each FMID in the product will be loaded to the SMPPTS data set, with a member name matching the FMID, when you receive the FMID with SMP/E RECEIVE. You can browse or print these members using TSO/E, ISPF, or IEBGENER (or IEBPTPCH).

SMP/E JCLIN

The JCLIN for the OS/390 Foreign File System is contained in the RELFILEs uploaded from the distribution CD. These files will be loaded to disk by SMP/E when you receive the product with  SMP/E RECEIVE. You can browse or print these files using TSO/E, ISPF, or IEBGENER (or IEBPTPCH).

The files containing JCLIN are:

FMID HFBN100: hlq.IBM.HFBN100.F1(HFBN100)

Note: The high-level qualifier (hlq) is the qualifier specified as the DSPREFIX in the SMP/E OPTIONS.

Configuring the IBM HTTP Server

You will be setting up the server to run in nonsecure mode. Details are available in the IBM HTTP Server documentation. (We use IBM HTTP Server to refer to all the server versions, but you might be using Domino Go Webserver if you have OS/390 Version 2 Release 5 or 6.) Your installation may have additional requirements such as workload management and proxy caching, but the OS/390 Foreign File System does not need these.

You can configure the IBM HTTP Server to your specifications by setting permissions, configuring language, customizing the server environment, and so on. You must do this configuring from the OS/390 UNIX shell using the Web administration user ID and group, by either of these methods:

Each method of configuring changes the statements (called directives) in the configuration file. Restart the server after you make changes to ensure that the changes take effect.

The following steps are based on the HTTP Server directions for installing it the first time (as opposed to migrating from a previous version of the server):

  1. Create the IMWEB OS/390 UNIX System Services group ID and the WEBADM user ID. You will use these to configure the server.
  2. Create the WEBSRV OS/390 UNIX System Services user ID. This user ID will run the server. Give this user ID permission to BPX.SUPERUSER and BPS.SERVER.
  3. Turn on program control, by using code such as:

    RDEFINE PROGRAM * ADDMEM('SYS1.SCEERUN'//NOPADCHK) UACC(READ)
    RDEFINE PROGRAM * ADDMEM('CBC.SCLBDLL'//NOPADCHK) UACC(READ)
    RDEFINE PROGRAM * ADDMEM('SYS1.LINKLIB') UACC(READ)
    SETROPTS WHEN(PROGRAM) REFRESH

    In this example, * is all programs in the data set or a specified program in the specified data set.
    Indicate that the server and Language Environment LOADLIBs are trusted programs.

  4. Make TCP/IP configuration adjustments. By default, both the HTTP Server and the OS/390 Foreign File System use port 80. You need not activate the simple network management protocol (SNMP) for the OS/390 Foreign File System.
  5. Copy and customize the JCL for starting the server (IMWPROC). If you changed any of the default names, you need to make similar changes in this JCL.
  6. Configure the installed files by using the configuration directives. If you installed the server in a different path, for example, than /usr/lpp/internet/, substitute your install path.

You can start the server using the start-up procedure IMWEBSRV. Make sure the procedure is a member in a PROCLIB data set. Enter the following command from the OS/390 operator console:

S IMWEBSRV

You can also start the proc when TCP/IP is started by adding START IMWEBSRV to the TCP/IP profile. Or you can use the httpd command, which is also documented in Appendix B of the IBM HTTP Server planning manual.

Example: JCL for starting the IBM HTTP Server

RELATED TASKS
Installing the prerequisite OS/390 software
IBM HTTP Server: Planning, Installing, and Using, SC31-8690
IBM HTTP Server Troubleshooting Guide
Domino Go Release 5.0 Webmaster's Guide, SC31-8691
Configuring OS/390 for remote ECD: overview

RELATED REFERENCES
HTTP directives for the OS/390 Foreign File System

HTTP directives for the OS/390 Foreign File System

You need to configure the following directives for the IBM HTTP Server to operate with the OS/390 Foreign File System. You can probably use the default settings for the other directives. However, review all the directives shown in the server documentation to make sure that the defaults are appropriate for your environment.

Type: Tuning

The MaxPersistRequest directive specifies the maximum number of requests that the server will allow on a persistent connection. VisualAge PL/I requires a value of 5 or greater. Specify the MaxPersistRequest directive as follows:

MaxPersistRequest   5

Type: GWAPI application processing

You need to enable the Go Webserver API (GWAPI) services used by VisualAge PL/I and provide the paths for the VisualAge PL/I server routines. The file /ffsserver/samples/fbnfconf contains sample configuration information for the foreign file system:

Enable FFS_WOPEN /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_GET /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_GETFILE     /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_GETFILEINFO /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_DIR /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_DELETE /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_RENAME /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_RMDIR /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_ALLOCATE /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_CONNECT /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
Enable FFS_STCMDSRV /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr
ServerInit /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvrInit TRACE_ERRORS
ServerTerm /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvrTerm
Service /FFSDS* /usr/lpp/ffsserver/lib/fbnfmain.dll:ffssrvr*
Pass /FBN-PUB/* /usr/lpp/ffsserver/WebServ/*

If you did not install into the default path (usr/lpp/ffsserver), you need to change the paths accordingly.

Prepend these directives to the Web server configuration file

Type: Directories

The settings for these directives control the kind of information presented in directory listings. The OS/390 Foreign File System requires the following settings:

DirAccess on DirShowBrackets on
DirReadme top DirShowCase on
DirShowIcons on DirShowHidden off
DirShowDate on DirShowBytes off
DirShowSize on DirShowMaxDescrLength 25
DirShowDescription on DirShowMinLength 15

RELATED TASKS
Configuring the IBM HTTP Server
IBM HTTP Server: Planning, Installing, and Using, SC31-8690
Domino Go Webmaster's Guide, SC31-8691

Example: JCL for starting the IBM HTTP Server

If you changed any of the default names while configuring the IBM HTTP Server, you need to make similar changes in this JCL.

//IMWPROC PROC LEPARM=,ICSPARM=
//*********************************************************************
//* PARM='LE runtime opts/ICS parms'
//*
//* LEPARM ==> LE runtime opts
//* LEPARM='ENVAR("_CEE_ENVFILE=/etc/httpd.envvars.tmp")'
//*
//* ICSPARM ==> Internet Connection Server parameters
//* # Standalone HTTPD
//* ICSPARM='-p 8080
//* # WLM Queue Manager
//* ICSPARM='-SN WEBSN1 -p 8080
//* # WLM ApplEnv Queue Server
//* ICSPARM='-SN WEBSN1 -AE WEBHTML'
//*
//* Internet Connection Server Parameters:
//* -SN # WLM - subsystem name
//* -AE # WLM - Application Envirnonment
//*
//* -fscp nnn # File system codepage - EBCDIC
//* -netcp nnn # net code page - ASCII
//*
//* -gc_only # clean cache & exit (garbage collect)
//*
//* -normalmode
//* -p nnnn # use port nnn (default 80)
//* -sslmode
//* -sslport nnnn # use port nnn (default 443)
//* -nosec # no security
//*
//* -nosmf # no smf processing on
//* -smf # smf processing on
//*
//* -r /etc/httpd.conf # use rule file xxxx
//* -restart
//* -v # trace to stderr
//* -vv # trace all to stderr
//* -vc # cache trace to stderr
//*
//* -version # show version and exit
//*
//* xxxxxxx # ServerRoot xxxxxxx; Pass /*
//*
//*********************************************************************
//WEBSRV EXEC PGM=IMWHTTPD,REGION=0K,TIME=NOLIMIT,
// PARM=('&LEPARM/&ICSPARM')
//*********************************************************************
//SYSIN DD DUMMY
//OUTDSC OUTPUT DEST=HOLD
//SYSPRINT DD SYSOUT=*,OUTPUT=(*.OUTDSC)
//SYSERR DD SYSOUT=*,OUTPUT=(*.OUTDSC)
//STDOUT DD SYSOUT=*,OUTPUT=(*.OUTDSC)
//STDERR DD SYSOUT=*,OUTPUT=(*.OUTDSC)
//SYSOUT DD SYSOUT=*,OUTPUT=(*.OUTDSC)
//CEEDUMP DD SYSOUT=*,OUTPUT=(*.OUTDSC)

RELATED TASKS
Configuring the IBM HTTP Server

Configuring the foreign file system server

To install the code for the foreign file system server, do the following steps:

  1. Modify the Web server file /etc/httpd.envvars to point to the directories where the executables for the foreign file system server reside. To do this, append the paths as follows:
    Append to this variable (in httpd.envvars file): Path where the following files were installed: Default value
    LIBPATH variable fbnfmain.dll and fbnfdir.dll /usr/lpp/ffsserver/lib
    PATH variable fbnflock and fbnfscmd /usr/lpp/ffsserver/bin
  2. Add the environment variable FFSPATH to the httpd.envvars file, setting it to the path where fbnflock was installed. The default value is /usr/lpp/ffsserver/bin.
  3. If your TCP/IP stack on the OS/390 does not have the default name TCPIP, you must identify the stack by putting the following line into httpd.envvars:
    _BPXK_SETIBMOPT_TRANSPORT=tcpipstackname

    Here tcpipstackname is the name of your TCP/IP stack. See UNIX System Services Planning for a description of the _BPXK_SETIBMOPT_TRANSPORT environment variable.

  4. Set the file permissions for UNIX System Services to rwx r_x r_x by issuing the following commands:
    chmod +rx fbnfmain.dll
    chmod +rx fbnfdir.dll
    chmod +rx fbnflock
    chmod +rx fbnfscmd
  5. To mark the files as Program Controlled, issue the following commands:.
    extattr +p fbnfmain.dll
    extattr +p fbnfdir.dll
    extattr +p fbnflock
  6. The foreign file system server by default opens port 15000 for direct conversation with the workstation. If this port number cannot be used in your installation, add the environment variable FFS_START_PORT to the httpd.envvars file, setting it to a number to start looking for an available port.
  7. The foreign file system server uses both the AF_UNIX and AF_INET socket domains. To support this use, make sure that both domains are identified in the BPXPRMxx parmlib member using FILESYSTYPE and NETWORK statements. For example:
    FILESYSTYPE TYPE(UDS) ENTRYPOINT(BPXTUINT)
    NETWORK DOMAINNAME(AF_UNIX)
       DOMAINNUMBER(1)
       MAXSOCKETS(1024)
       TYPE(UDS)
    FILESYSTYPE TYPE(INET) ENTRYPOINT(BPXTIINT)
    NETWORK DOMAINNAME(AF_INET)
       DOMAINNUMBER(2)
       MAXSOCKETS(1024)
       TYPE(INET)

    In the example above, the MAXSOCKETS value has been increased from the default of 64 to 1024 for both the AF_UNIX and AF_INET domains. This is recommended. In particular, the foreign file system server makes extensive use of AF_UNIX domain sockets to improve performance.

    For more information about these statements and the BPXPRMxx parmlib member in general, see UNIX System Services Planning.

You can verify that the foreign file system server has been installed correctly without testing it through VisualAge PL/I. From a browser on the workstation, enter the following address:

http://systemname:webserverport/FFSDS/

Here systemname is the TCP/IP host name or address of the OS/390 system, and webserverport is the port number for the IBM HTTP Server (the default is 80). FFSDS must be uppercase, and the final slash (/) must be used. You should see the home page for the foreign file system server.

RELATED TASKS
Installing the prerequisite OS/390 software
Configuring OS/390 for remote ECD: overview

RELATED REFERENCES
UNIX System Services Planning, SC28-1890 (about the _BPXK_SETIBMOPT_TRANSPORT environment variable and BPXPRMxx parmlib member)

Configuring the job monitor server

Using the earlier steps for installing the OS/390 Foreign File System, you installed the following data sets from the CD to your system:

Load module SFBNLOAD(FBNJMON)
Configuration file SFBNSAMV(FBNJCNFG)
JCL file SFBNSAMP(FBNJJCL)

Use the following steps to configure the job monitor server on the host:

  1. Accept the default port (6715), or change it in the configuration file as shown in the following sample:
    AUTHMETHOD=RACF
    CODEPAGE=UTF-8
    HOST_CODEPAGE=IBM-1047
    JES=JES2
    JESNAME=JES2
    LISTEN_QUEUE_LENGTH=5
    MAX_DAEMONS=10
    MAX_DATASETS=32
    MAX_THREADS=200
    SERV_PORT=6715
    TIMEOUT_INTERVAL=1200
    TIMEOUT=3600
    TZ=PST5PDT

    Both the client and the server must be configured with the same port number. If you change the server port number, the developers must also change the client port number by using the MVS connections manager.

  2. Accept the default host codepage (IBM-1047), or change it in the configuration file. The workstation codepage is set to UTF-8 and should not be changed.
  3. Use the JES parameter in the configuration file to indicate whether you use JES2 or JES3.
  4. Modify the JCL for starting the job monitor server to ensure that the data set names match the installation names, specify the system for execution, and fit your installation.
  5. Submit the JCL to start the job monitor. You can use the netstat command to check whether the job monitor is listening to the configured port.

In order to allow users to execute operations via the job monitor, they must be given access authority to the OPERCMDS class. This can be done conditionally, so that the users' access is only in effect when he or she is using the job monitor. To use this conditional access checking, you must have the CONSOLE class active and the JMON console defined in the CONSOLE class.

For example, you would issue the following RACF commands:

SETROPTS CLASSACT(CONSOLE)
RDEFINE CONSOLE JMON UACC(READ)
Then, to give conditional access (e.g. to permit users to issue JES2 commands only while running under the job monitor):
RDEFINE OPERCMDS JES2.** UACC(NONE)
PERMIT CLASS(OPERCMDS) JES2.** ID(userid or groupid) ACCESS(CONTROL)
WHEN(CONSOLE(JMON))

RELATED TASKS
Installing the prerequisite OS/390 software
Configuring OS/390 for remote ECD: overview

Installing and configuring the TSO commands server (optional)

The TSO commands server uses an APPC/MVS transaction to execute TSO commands. The FFS server starts the APPC transaction (FBNFSERV), which 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 it communicates with FBNFSERV through TCP/IP.

Note: With the version of Foreign File Server (FFS) delivered with VisualAge PL/I for Windows V2.1.10 there is no corresponding Host PL/I APAR to apply. The function of the previous PL/I parts, IBMFTPAD and IBMFSERV, is now performed by FFS parts, FBNFTPAD and FBNFSERV, which are now delivered with the FFS product and it's current service.

Each workstation can have an active connection to each host at the same time.

The following steps are in preparation for configuring the server on the host. You (the system programmer or APPC administrator) may already have done the first and third steps:

  1. Install, configure, and start TCP/IP on your OS/390 system.
  2. Verify access through TCP/IP by using the TSO command HOMETEST. TCP/IP must be able to respond to a GETHOSTBYNAME request. Therefore, a domain name server must exist and know the name of the MVS TCP/IP stack that has access to it, or the domain name must be defined to TCP/IP directly.

The system programmer or APPC administrator needs to do the following steps to configure the command facility:

  1. Start APPC and the APPC transaction scheduler (ASCH) subsystem, which handles incoming requests for local transaction programs.
  2. Define the APPC transaction that will act as a command server for VisualAge PL/I. You can use the FBNFTPAD sample JCL to define this transaction.
  3. Define the scheduling information for the APPC/MVS transaction scheduler by using the ASCHPMxx member of SYS1.PARMLIB. Include a definition of the class to be used by the transaction program FBNFSERV (in FBNFTPAD). For example:
    CLASSADD
      CLASSNAME(DEFAULT)
      MAX(20)
      MIN(1)
      MSGLIMIT(5000)
    
    OPTIONS
    DEFAULT(DEFAULT)
    
    TPDEFAULT
      REGION(2M)
      TIME(5)
      MSGLEVEL(1,1)
      OUTCLASS(9)       
  4. Control the dispatching priority of the FBNFSERV transaction program by using parameters for the systems resource manager (SRM) to associate FBNFSERV with a domain and performance group. Because FBNFSERV issues TSO commands, it should be assigned to a TSO performance group.
  5. Define a default OMVS segment for the system or for each user who needs to use remote edit-compile-debug.
  6. Make the following parts available on the host system:

If you cannot use the command facility, there are two main areas where problems can arise: connecting to MVS and starting the APPC server transaction.

If you do not see the messages about setting up APPC, check the system log for RACF messages or other messages related to the command that was issued or the user ID that issued it. Common causes of problems include:

If you see the messages about setting up APPC but do not see the message confirming that setup succeeded, the APPC server transaction was probably unable to start. If the error log (userid.FNBFSERV.&TPDATE.&TPTIME.LOG) for the conversation exists, check it. Some of the likely causes of problems are:

Example: JCL for defining the APPC transaction

RELATED TASKS
Installing the prerequisite OS/390 software
Configuring OS/390 for remote ECD: overview

Example: JCL for defining the APPC transaction

For the TSO commands server, the job card and some of the JCL in FBNFTPAD need to be modified to meet the requirements of your site. The user ID for the FBNFTPAD job must be authorized to APPC before you run the job.

 1 //FBNFTPAD JOB (XX,YY),CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1)
 2 //*
 3 //TPADD    EXEC PGM=ATBSDFMU
 4 //SYSPRINT DD SYSOUT=*
 5 //SYSSDLIB DD DSN=SYS1.APPCTP,DISP=SHR
 6 //SYSSDOUT DD SYSOUT=*
 7 //SYSIN    DD DATA,DLM='QT'
 8      TPADD
 9        TPNAME(FBNFSERV)                                                 (1)
10        ACTIVE(YES)
11        TPSCHED_DELIMITER(DLM1)
12        KEEP_MESSAGE_LOG(ERROR)
13        MESSAGE_DATA_SET(&SYSUID.FBNFSERV.&TPDATE.&TPTIME.LOG)
14        DATASET_STATUS(MOD)
15        CLASS(DEFAULT)                                                   (2)
16        JCL_DELIMITER(DLM2)
17 //FBNFSERV  JOB                                                         (3)
18 //*
19 //*********************************************************************
20 //* To enable the VA PL/I TSO Commands feature to display results
21 //* of only native TSO commands, use this:
22 //*********************************************************************
23 //IKJACCNT  EXEC PGM=IKJEFT01,DYNAMNBR=50,PARM='%FBNFSERV TIMEOUT=60'   (4)
24 //SYSPROC   DD DISP=SHR,DSN=HFBN100.SFBNSAMP                            (5)
25 //*********************************************************************
26 //* To enable the VA PL/I TSO Commands feature to display the results
27 //* of ISPEXEC commands as well as native TSO commands, use this:
28 //*********************************************************************
29 //*IKJACCNT  EXEC PGM=IKJEFT01,DYNAMNBR=50,                             (6)
30 //*        PARM='ISPSTART CMD(%FBNFSERV TIMEOUT=60)'
31 //*SYSPROC   DD DISP=SHR,DSN=HFBN100.SFBNSAMP
32 //*          DD DISP=SHR,DSN=SYS1.ISP.SISPCLIB
33 //*ISPPLIB   DD DISP=SHR,DSN=SYS1.ISP.SISPPENU
34 //*ISPMLIB   DD DISP=SHR,DSN=SYS1.ISP.SISPMENU
35 //*ISPTLIB   DD DISP=SHR,DSN=SYS1.ISP.SISPTENU
36 //*ISPSLIB   DD DISP=SHR,DSN=SYS1.ISP.SISPSENU
37 //*          DD DISP=SHR,DSN=SYS1.ISP.SISPSLIB
38 //*ISPPROF   DD DISP=(NEW,DELETE,DELETE),DSN=&&PROF,
39 //*             SPACE=(TRK,(1,1,5)),LRECL=80,RECFM=FB
40 //*********************************************************************
41 //* The rest of this JCL is common
42 //*********************************************************************
43 //SYSPRINT  DD SYSOUT=*
44 //* SYSTCPD   DD DSN=SYS1.TCPIP.DATA,DISP=SHR                           (7)
45 //* SYSTSPRT  DD DSN=&SYSUID..FBNFSERV.OUTPUT,DISP=SHR
46 //SYSTSPRT  DD SYSOUT=*                                                 (8)
47 //SYSTSIN   DD DUMMY
48 DLM2
49 DLM1
50 QT
  1. The transaction name in FBNFTPAD must match the transaction name in FBNFSCMD. If you change the transaction name in FBNFTPAD, you must also change it in FBNFSCMD, but changing FBNFSCMD is not recommended.
  2. Define the transaction class as a class that has enough initiators to allow one for each user of remote edit-compile-debug in VisualAge PL/I. Here the transaction class is named DEFAULT; you probably need to change this to the appropriate transaction class.
  3. Update the job card as needed for items such as output classes.
  4. Adjust the timeout value to a positive whole number of minutes. By default, the transaction (FBNFSERV) is set to time out after 60 minutes of inactivity. If a user on the workstation tries to issue a TSO command after the server has timed out, there will be a delay of a few seconds while the server transaction is restarted.
  5. Allocate SYSPROC to the SFBNSAMP data set, which is where FBNFINIT and FBNFSERV reside.
  6. If you wish to run non-interactive ISPEXEC commands, you may comment or remove the previous IKJACCNT and SYSPROC lines and uncomment the lines in this section. Notes 4 & 5 above are also applicable to the IKJACCNT and SYSPROC lines here. Make sure the ISPxxxx DD statements reference the correct ISPF data sets.
  7. SYSTCPD is needed only when your installation uses a nondefault ID for TCPIP. If you use a different stack name, then you need to activate this line and point it to the DSN=hlq.TCPIP.DATA, which specifies the user ID of the active TCPIP stack.
  8. The output of SYSTSPRT is normally discarded. However, if there are problems, the output can be diverted to a data set (named in line 23) for analysis.

RELATED TASKS
Installing and configuring the TSO commands server (optional)

Configuring OS/390 for remote debugging under CICS

Two Debug Tool partitioned data sets are required for the CICS setup described below:

This section describes how to set up Debug Tool for use with CICS.

For a developer to use TCP/IP sessions to carry the communications for remote debugging of CICS applications, a systems administrator needs to take the following actions:

  1. Update the CICS system definition (CSD).
    1. Merge the supplied Debug Tool definitions into your existing job for maintaining the CSD. The statements for defining Debug Tool are in the member EQACCSD, which is in the sample library SEQASAMP.
    2. Make sure that the CSD group that is used during CICS startup includes the CSD group that is associated with the Debug Tool library routines. The group name for the Debug Tool routines is EQA in the sample EQACCSD.
  2. Update the CICS destination control table (DCT).
    1. Merge the required Debug Tool definitions into your existing job for maintaining the DCT. The statements for defining Debug Tool are in the member EQACDCT, which is in the sample library SEQASAMP.
    2. Make sure that EQACDCT contains definitions to create DCT entries for the transient data queues that Debug Tool uses. They are defined as extra partition data queues. Do not add DD statements to the CICS JCL startup deck for these queues. If you have CICS Transaction Server, you can omit the EQACDCT updates and uncomment the transient data defines at the end of EQACSD prior to running it. For information on the DFHDCT macro and on defining queues and associated buffers, see CICS/ESA Resource Definition Guide.
  3. Update the CICS startup job.
    1. Make sure that all of the Debug Tool modules that are defined in EQACCSD (as well as modules for language libraries, such as IBM OS/390 Language Environment, and any user modules that may be called during the debugging session) are in libraries that CICS can access. You can make the libraries accessible by including them in the concatenation for the DFHRPL DD in the CICS startup JCL. For an example of a CICS startup job, see CICS/ESA Operations Guide.
    2. Put the SEQAMOD library in the DFHRPL concatenation.
  4. Update the CICS authorized library.
    1. Make sure that the Debug Tool module EQA00DYN resides in one of the authorized libraries that CICS can access. This access can be through authorized libraries in the STEPLIB concatenation, through a JOBLIB, or through an OS/390 LINKLST data set.
    2. Depending on the method you choose, you might need to copy EQA00DYN from SEQAMOD to one of the authorized libraries.
  5. Ensure that Debug Tool users in CICS are authorized to execute the transaction CDT#.
  6. Unless you already activated TCP/IP in the CICS region, activate it including setting up, configuring, and starting CICS TCP/IP.

    For a detailed explanation on activating TCP/IP in the CICS region, see CICS TCP/IP Socket Interface Guide and Reference.

RELATED TASKS
Installing the prerequisite OS/390 software
Configuring OS/390 for remote ECD: overview

RELATED REFERENCES
CICS TCP/IP Socket Interface Guide and Reference, SC31-7131
CICS/ESA Resource Definition Guide, SC33-1166
CICS/ESA Operations Guide, SC33-0668