Installing PTF IP22589 for the IBM Foreign File System (FFS)

IBM Foreign File System PTF IP22589 supersedes all previous PTFs for FFS.

If you have already installed and configured the foreign file system base product, you need to install only PTF IP22589.

If you are a new user of the foreign file system server, first follow the instructions in Installing and Configuring OS/390 Components for Remote ECD, inst390.pdf, to install and configure the base product. Then install PTF IP22589, as described in this section.

PTF IP22589 provides several enhancements and fixes. In particular:

Previously, when a user incorrectly attempted to read or write to a RECFM=U data set, FFS kept the data set allocated. This problem is now fixed.
Previously, the FFS server sometimes terminated when it read a large file. This problem is now fixed.
Previously, Job Monitor issued OC4 abends when you tried to look at the spool data sets of a currently running job. This problem is now fixed.
Even though the documentation for the Job Monitor server says not to change the workstation code page value from UTF-8, the UTF-8 code page might not correctly reflect incoming ASCII text that contains NLS characters above x'7F', such as the British pound sterling. In that case, change the value CODEPAGE=UTF-8 to something like CODEPAGE=IBM-1252 in the Job Monitor configuration file.
Job Monitor restricts the use of CANCEL, HOLD, PURGE, and RELEASE to jobs for which you are the owner. This restriction was previously undocumented.
The general steps for installing and configuring this PTF are shown in the checklist below.

Step	For details, see:	Done?
Install the PTF.	Installing PTF IP22589
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

Installing PTF IP22589

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 IP22589 in support of VisualAge COBOL or VisualAge PL/I. 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\IP22589\IBM.HFBN100.IP22589.

Overview of the installation steps

Here are the steps required to install PTF IP22589:

Allocate a data set for the PTF.
Upload the PTF from your workstation.
Perform SMP/E RECEIVE and APPLY.

Allocate a data set for the PTF

A sequential data set must be allocated on the OS/390 system 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.IP22589,
//         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 2002-03-15.
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\IP22589\ibm.hfbn100.IP22589 ibm.hfbn100.IP22589
200 Port request OK.
125 Storing data set hlq.ibm.hfbn100.ip22727
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 postinstall 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 DDDEFs 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:

Edit a copy of the configuration file (named httpd.conf by default).
Use the Configuration and Administration forms (a combination of CGI programs and HTML forms).

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.

HTTP directives for the foreign file system

You need to configure the following directives for the IBM HTTP Server to operate with the IBM 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. The foreign file system 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 the IBM Foreign File System and provide the paths for the foreign file system 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
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.

Updating the foreign file system server configuration

To update the configuration of the foreign file system server, do the following steps:

Check that the Web server file /etc/httpd.envvars points to the directories where the executables for the foreign file system server reside. Specifically:

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.

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
```
To mark the files as Program Controlled, issue the following commands:
```
extattr +p fbnfmain.dll
extattr +p fbnfdir.dll
extattr +p fbnflock
```
Check that the load module (FBNJMON) is in an APF authorized library.

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

Updating the job monitor server configuration

If you use JES3, specify that you are using JES3 in the job monitor server configuration file SFBNSAMV(FBNJCNFG):

AUTHMETHOD=RACF
CODEPAGE=UTF-8
HOST_CODEPAGE=IBM-1047
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.