Installing PTF IP22257 for the IBM Foreign File System

VisualAge COBOL 3.0.3 requires IBM Foreign File System PTF IP22257 when using Remote Edit-Compile-Debug.  This PTF supersedes IP22114 and IP22230.

If you have already installed and configured the Foreign File System base product, you need to install only PTF IP22257.

If you are a new user of VisualAge COBOL Version 3, first follow the instructions in INST390.HTM on the VisualAge COBOL CD-ROM to install and configure the base product (but you may ignore instructions to install PTF IP22114 or IP22230). Then install PTF IP22257, as described in this document.

PTF IP22257 provides several enhancements and fixes. In particular:

The general steps for installing and configuring this PTF are shown in the checklist below.
 
Step For details, see: Done?
For the new JES3 support, install the JES3 PTF for OW36022 and ++APAR for OW45210.    
Install the PTF. Installing PTF IP22257  
Update the IBM HTTP Server configuration. Updating the IBM HTTP Server configuration  
Update the foreign file system server configuration. Updating the foreign file system server configuration  
Update the job monitor server configuration. Updating the job monitor server configuration  

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 PTF IP22257

This material is intended for the system programmer responsible for installing and maintaining programs. It contains information about the material and procedures associated with the installation of PTF IP22257 in support of VisualAge COBOL V3.0.3. You should read all of this material before installing the PTF and then keep it for future reference.

The PTF is shipped as file HFBN100\IP22257\IBM.HFBN100.IP22257.

Overview of the installation steps

Here are the steps required to install PTF IP22257:
  1. Allocate a data set for the PTF.
  2. Upload the PTF from your workstation.
  3. Perform SMP/E RECEIVE and APPLY.

Allocate a data set for the PTF

A sequential data set must be allocated on the OS/390 for the PTF that you will upload from your workstation.. 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.IP22257,
//         DISP=(NEW,CATLG,DELETE),
//         DSORG=PS,
//         RECFM=FB,
//         LRECL=80,
//         BLKSIZE=6160,
//         SPACE=(TRK,(4,2)),
//         UNIT=SYSALLDA
//*        VOL=SER=&TVOL1

Upload the PTF from your Workstation

Upload the file in binary format from your workstation to the OS/390 data set. On a Windows 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 system
tsouid Your TSO user ID
tsopw Your TSO password
d: Your drive containing the PTF files
hlq High-level qualifier that you used for the data set that you allocated in the job above 
C:\>ftp mvsaddr
Connected to mvsaddr.
220-FTPD1 IBM FTP CS V2R8 at mvsaddr, 04:43:52 on 2000-09-12.
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\ip22257\ibm.hfbn100.ip22257 ibm.hfbn100.ip22257
200 Port request OK.
125 Storing data set hlq.ibm.hfbn100.ip22257
250 Transfer completed successfully.
1000000 bytes sent in 1.92 seconds (529.71 Kbytes/sec)

ftp> quit
221 Quit command received. Goodbye.

Perform SMP/E RECEIVE and APPLY

RECEIVE and APPLY the PTF as usual.  Below is an example control card for applying the PTF: 
//SMPCNTL  DD  *
    SET BDY(TARGLIB).
    APPLY SELECT(HFBN100)
    CHECK
    GROUPEXTEND
    FORFMID(HFBN100)
    COMPRESS(ALL) REDO
    BYPASS(HOLDSYS,HOLDUSER,
    HOLDCLASS(UCLREL,ERREL)).
Some of the post-install steps, done for the original installation, must be redone for the executables. An SMP/E ++HOLD will indicate this when you apply the PTF.  Follow the instructions in the remaining sections of this document to ensure that these steps are done.  Then you will need to resubmit the control card without the CHECK to complete the installation..

If the APPLY fails with the message:

MVS PDS OR PDSE WITH DDNAME SYSUT1 WAS SPECIFIED FOR EITHER INPUT OR OUTPUT. A MEMBER NAME IS REQUIRED.

then check your APPLY JCL and SMP/E DDEFs to see whether you have SYSUT1 defined as a PDS or PDSE. SMP/E must transform some of the files shipped inline with this PTF before they are applied. This transformation uses SYSUT1 as the output file, then SMP/E APPLY uses SYSUT1 as the input file. SMP/E requires SYSUT1 - 4 to be defined as sequential.

Updating the IBM HTTP Server Configuration

You will be updating the IBM HTTP Server configuration, primarily to enable new Go Webserver API (GWAPI) services used by the foreign file system server to improve performance. You must do this updating 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.

RELATED REFERENCES
HTTP directives for VisualAge COBOL

HTTP directives for VisualAge COBOL

You need to configure the following directives for the IBM HTTP Server to operate with VisualAge COBOL. 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 COBOL 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 COBOL and provide the paths for the VisualAge COBOL server routines. The file /ffsserver/samples/fbnfconf (listed below), contains sample configuration information for the foreign file system. New directives are in bold. If you did not install into the default path (usr/lpp/ffsserver), you need to change the paths accordingly. 
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
Enable  FFS_CLEANTMP    /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/*
Prepend these directives to the Web server configuration file, which by default is httpd.conf.

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

Updating the foreign file system server configuration

To update the configuration of the foreign file system server, do the following steps:
  1. Check that the Web server file /etc/httpd.envvars points to the directories where the executables for the foreign file system server reside. Specifically:

    2.  
    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

    It is no longer necessary to set the FFSPATH variable.
     

  2. Set the file permissions for UNIX System Services to rwx r_x r_x by issuing the following commands:
    3. chmod +rx fbnfmain.dll
chmod +rx fbnfdir.dll
chmod +rx fbnflock
chmod +rx fbnfscmd
  3. To mark the files as Program Controlled, issue the following commands:.
    4. extattr +p fbnfmain.dll
extattr +p fbnfdir.dll
extattr +p fbnflock
  4. Check that the load module (FBNJMON) is in an APF authorized library.

    5.  
  5. 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:
    6. 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 COBOL. 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 REFERENCES
UNIX System Services Planning, SC28-1890 (about the BPXPRMxx parmlib member)

Updating the job monitor server configuration

If you use JES3:
  1. Be sure that you have installed the JES3 PTF for OW36022 and ++APAR for OW45210.
  2. Specify that you are using JES3 in the job monitor server configuration file SFBNSAMV(FBNJCNFG):
    3. AUTHMETHOD=RACF
CODEPAGE=UTF-8
HOST_CODEPAGE=IBM-1047
__JCL=YES
JES=JES3
JESNAME=JES3
LISTEN_QUEUE_LENGTH=5
MAX_DAEMONS=10
MAX_DATASETS=32
MAX_LINECOUNT=15000
MAX_THREADS=200
SERV_PORT=6715
TIMEOUT_INTERVAL=1200
TIMEOUT=3600
TZ=PST5PDT
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.