Fileshare

Fileshare Server Messages

Chapter 19: Fileshare Tutorial

This tutorial guides you through some of the major features of Fileshare. It does not cover all features.

19.1 Overview

This tutorial covers all environments. The labels on the left-hand side of the page identify any entries specific to an environment.

The topics covered are:

Getting started with Fileshare
Fileshare is easy to set up and use. You do not need to change program source code to benefit from improved network performance. This section shows you:
- How to get Fileshare running quickly
- How to Animate a Fileshare program
- How to stop Fileshare
Changing the Fileshare Client configuration file
The Fileshare Client configuration file enables you to configure how you want Fileshare Client application programs to operate. This section demonstrates how you can alter Fileshare behavior via the configuration file.
Implementing Fileshare recovery
You can configure Fileshare to write all the changes to your data files to a separate log file. Then if the system fails, you can retrieve lost data by applying the recovery log to your most recent backup. This section shows you how to implement Fileshare recovery.
Using transaction processing
With transaction processing enabled, your application updates your data files only when all the changes are complete. When you want to secure your changes, your application issues a COMMIT; when you want to cancel the changes your application issues a ROLLBACK. This section shows you how to implement transaction processing.

Note: For DOS, OS/2, and Windows environments, this tutorial uses sample programs that are copied to your system during installation. If you did not install these programs when you installed this system, run Setup again now to install them.

19.2 Getting Started with Fileshare

Fileshare reduces network traffic by moving low-level file I/O from client workstations to the Fileshare Servers. The only traffic on the network is the request and the data.

For example, consider a COBOL program trying to access files on a remote file server. On a conventional network, the Callable File Handler (ExtFH), manages all file handling requests.

A single COBOL file handling request such as a WRITE or REWRITE generates several low-level requests to the operating system. Each low-level request made by the Callable File Handler is sent across the network to the File Server.

When a second user tries to access the same data, ExtFH sends additional requests to make sure no two users are contending for the same data. The more users on the system, the more contention you get.

Contrast that with the way Fileshare works. Instead of ExtFH handling the file handling requests, they are handled by the File Handling Redirector (FHRedir). FHRedir gets a single file handling request, packages the single request and passes it across the network to Fileshare. For each I/O request, only one request goes across the network.

All the low-level requests are done on the remote machine.

In addition, only one copy of the file handler is running. This enables Fileshare to store information about the different users accessing the files through Fileshare. Since Fileshare has exclusive use of the files, shared files are handled more quickly and more efficiently.

19.2.1 Starting Your Network

Fileshare uses the Common Communications Interface (CCI) to communicate between the Fileshare Client and the Fileshare Server. CCI provides several different protocols. The protocol you use depends on the operating system the Fileshare Client and the Fileshare Server are running on and the type of network you are using.

Fileshare supports a default protocol for each operating system. Therefore, you don't have to explicitly configure the communication protocol for Fileshare unless you must use a CCI protocol other than the default. If you don't specify a CCI protocol, the following default protocols are used:

Operating System	CCI Protocol	COBOL Product
DOS	CCINETB	16-bit
OS/2	CCINETB	16-bit and 32-bit
Windows	CCINETB	16-bit
Windows 95	CCITCP	32-bit
Windows NT	CCITCP	32-bit
UNIX	CCITCP	32-bit
NetWare	CCIIPX	32-bit

In the examples below, we assume the default protocol is active.

To see how to start these and other communications protocols under different environments, refer to your Programmer's Guide to Communications.

19.2.1.1 Using CCITCP

If you are using the CCITCP protocol you must be running a ccitcp2 registration process on one of the machines on your network. To do this, enter the following on the command line:

Windows 95 and Windows NT:

ccitcp2

UNIX:

$COBDIR/ccitcp2

On each machine from which you will be accessing this ccitcp2 registration process, you need to set the CCITCP2 environment variable to the TCP/IP host name of the machine on which ccitcp2 is running as follows:

Windows 95 and Windows NT:

set ccitcp2=hostname

UNIX:

CCITCP2=hostname
export CCITCP2

If the CCITCP2 environment variable is not set, the CCITCP module assumes that the ccitcp2 process is running on the local machine.

For the examples in this tutorial, you can start ccitcp2 on the machine on which the Fileshare Server is run. This means that you do not have to set the CCITCP2 environment variable on this machine. However, on any other machine on which you are going to run the client demonstration programs, you need to set CCITCP2 to the TCP/IP host name of the machine where ccitcp2 (and the Fileshare Server) is running.

See your Programmer's Guide to Communications for more information.

19.2.2 Running a Fileshare Program

We use the demonstration program, stockioa.cbl, to illustrate how to set up and use Fileshare.

DOS, Windows and OS/2:
On DOS, Windows and OS/2, stockioa.cbl is in the demo\mudemo subdirectory of the COBOL system directory structure.

UNIX:
On UNIX, stockioa.cbl is available in the $COBDIR/demo directory.

stockioa is one of several programs that illustrate how to use COBOL in a multiple user environment. Any of the other programs also could be used in this tutorial.

19.2.2.1 Running Your Program Without Fileshare

To show how easy it is to convert to using Fileshare, we first run the program without Fileshare and then make the necessary changes to run the program with Fileshare.

To run the program without Fileshare:

Copy the sample program stockioa.cbl into a directory on your machine where you want to run the program.
Compile stockioa.cbl.
DOS, Windows and OS/2:
```
cobol stockioa int() nognt;
```
UNIX:
```
cob -i stockioa.cbl
```
This creates the stockioa.int file.
Run the program. This creates the files in the directory where the stockioa program is run. This directory could be on a server with the files being shared between a number of users.
DOS:
```
xm run stockioa
```
Windows:
```
runw stockioa
```
Windows NT, Windows 95 and OS/2:
```
run stockioa
```
UNIX:
```
cobrun stockioa
```
stockioa provides you with several options for writing to and reading from an index file.
Enter some representative values for the fields. Then enter 4 in the Input Choice field to write the record to a file.
Exit the program by entering 7 in the Input Choice field.
The program asks you:
```
Do you wish to restart (Y/N) [ ]
```
If you respond Y, the program restarts and you can enter new information or view what you just entered.

If you respond N, the program ends.

19.2.2.2 Running Your Program with Fileshare

Now let's convert your application to use Fileshare.

With Fileshare, the workstation where the application (in this case stockioa.cbl) is run is called the Fileshare Client.

The data files accessed by the Fileshare Client are under the control of the Fileshare Server.

The Fileshare Server can be on a different workstation on the network or, if the operating system supports multiple sessions, in a different session on the same workstation.

In order for the program stockioa.cbl to use Fileshare, you need to do the following:

In the Fileshare Client directory create the file, fhredir.cfg, containing the following entries:
DOS, Windows and OS/2:
```
/s serverone
```
UNIX:
```
-s serverone
```
The /s option (-s for UNIX) identifies the Fileshare Server that the Fileshare Client should contact to process the I/O requests. In this case it is called serverone.

NetWare:
If your server is on the NetWare operating system the Fileshare Client configuration file should contain:
```
/s serverone
/cm cciipx
/ma xxxxx.yy /s serverone
```
The /cm parameter specifies that the CCIIPX communications protocol is to be used.

The /ma parameter is required by CCIIPX to define the exact network and node address of the NetWare server that the Fileshare NLM is running on. This address can be determined by executing the NetWare requester command SLIST or NLIST SERVER on a networked workstation.

The output from SLIST or NLIST SERVER takes the form:
```
Known NetWare
File Servers        Network         Node Address Status
--------------      --------        -------------------
NETWARE-SERV1       [ 60194]        [       80]
```
For example, "NETWARE-SERV1" is the name of the server that the Fileshare NLM is running on.

Example
```
/ma 60194.80 /s serverone
```
where serverone is the server name you specified when starting the Fileshare NLM on the NetWare server "NETWARE-SERV1".
Compile the sample program with the CALLFH directive so all I/O requests are processed by the FHRedir (File Handler Redirector) module. This module passes the I/O request to the Fileshare Server.
DOS, Windows and OS/2:
```
cobol stockioa int() nognt callfh"fhredir";
```
UNIX:
```
cob -i stockioa.cbl -C CALLFH=FHREDIR
```
In the Fileshare Server directory, create the files fs.cfg containing the following entry:
DOS, Windows, OS/2 and NetWare:
```
/s serverone
```
UNIX:
```
-s serverone
```
The Fileshare Server now needs to be started with one of the following commands:
DOS:
```
xm fs 
```
Windows:
```
fsw 
```
Windows NT, Windows 95, OS/2 and UNIX:
```
fs
```
NetWare:
```
load fs
```
The /s option (-s for UNIX) names the Fileshare Server.

If Fileshare starts successfully, you should see a message like:
```
Fileshare Version 2 Revision xxxx
FS101-I s serverone - parameter has been accepted

FS084-I Fileshare Server is starting. (Revision xxxx)
FS132-I The Fileshare Server running with the following
      communications protocol(s):
      CCINETB
FS085-I Fileshare Server is active.
```
If you don't see this message, check to make sure:
- your network services are correctly installed and running
- another server with the same name doesn't exist
When Fileshare is active, press the F2 key to enable the trace function. You should see the message:
```
FS160-I Fileshare trace activated.
```
Return to the stockioa.cbl program and run it using the following command:
DOS:
```
xm run stockioa
```
Windows:
```
runw stockioa
```
Windows NT, Windows 95 and OS/2:
```
run stockioa
```
UNIX:
```
cobrun stockioa
```

The stockioa.cbl program (Fileshare Client) is now accessing the files using the Fileshare Server. The operations being performed should be visible on the Fileshare Server trace.

Thus, you can gain the significant advantages of Fileshare in a multi-user environment just by re-compiling your program.

19.2.3 Animating a Fileshare Program

You can animate a Fileshare program as easily as a normal COBOL file handling program. To animate a Fileshare program:

Compile the sample program as before. If you are running on DOS, Windows, or OS/2, you must also use the ANIM directive:
DOS, Windows and OS/2:
```
cobol stockioa int() nognt anim callfh"fhredir";
```
UNIX:
```
cob -ia stockioa.cbl -C CALLFH=FHREDIR
```
If the Fileshare Server is not running, start it by creating an fs.cfg file as outlined in the section Running Your Program with Fileshare and entering:
DOS:
```
xm fs
```
Windows:
```
fsw
```
Windows NT, Windows 95, OS/2 and UNIX:
```
fs
```
NetWare:
```
load fs
```
When Fileshare is active, press the F2 key to enable the trace function.
On the Fileshare Client, the configuration file fhredir.cfg, created in the last section should contain the following entry:
DOS, Windows and OS/2:
```
/s serverone
```
UNIX:
```
-s serverone
```
From the Fileshare Client, animate the program.
DOS, Windows and OS/2:
```
animate stockioa
```
UNIX:
```
anim stockioa
```

Again, you didn't have to change your application.

19.2.4 Stopping Fileshare

The Fileshare Server runs as an active process. Therefore, you must stop it when you no longer need it. This section shows you how to stop Fileshare.

On the Fileshare Server session, press the Esc key. Fileshare displays the prompt:
```
FS097-I Are you sure you wish to close down Fileshare Server ? (Y/N)
```
Enter Y to confirm that you want Fileshare to terminate. Any other entry causes the Fileshare Server to continue.

19.3 Changing the Fileshare Client Configuration File

Fileshare has many advanced features that improve performance and help you maintain the integrity of your files and prevent loss of data.

The Fileshare Client configuration file lets you configure how you want FHRedir to operate. It also ensures that you always start FHRedir on the Fileshare Client machine with the same settings. This file lets you:

Specify the Fileshare Servers you want to access
Specify a communications protocol for each Fileshare Server you want to access
Redirect the requests to a named Fileshare Server or to the local disk

We use the demonstration program wr2test.cbl to illustrate how to change the FHRedir configuration file to get different effects.

DOS, Windows and OS/2:
On DOS, Windows, Windows NT, Windows 95 and OS/2, this program is in the demo subdirectory of the COBOL system directory structure.

UNIX:
On UNIX, the program is available in the $COBDIR/demo/fs directory.

The program writes 20 records to two different files, fileone.dat and filetwo.dat.

We use the same environment as we used in the previous section.

If the Fileshare Server is not running, start it by creating an fs.cfg file as outlined in the section Running Your Program with Fileshare and entering:
DOS:
```
xm fs
```
Windows:
```
fsw
```
Windows NT, Windows 95, OS/2 and UNIX:
```
fs
```
NetWare:
```
load fs
```
When Fileshare is active, press the F2 key to enable the trace function.
On the Fileshare Client, the configuration file fhredir.cfg, created in the last section should contain the following entry:
DOS, Windows and OS/2:
```
/s serverone
```
UNIX:
```
-s serverone
```
On the Fileshare Client, compile wr2test.cbl:
DOS, Windows and OS/2:
```
cobol wr2test int() nognt;
```
UNIX:
```
cob -i wr2test.cbl
```
This generates the wr2test.int file.

Notice the Compiler directive CALLFH"FHREDIR" is set in the program. You do not have to include it in the compilation statement.
Run the program.
DOS, Windows and OS/2:
```
run wr2test
```
UNIX:
```
cobrun wr2test
```
wr2test creates both files, fileone.dat and filetwo.dat, on the Fileshare Server.
On the Fileshare Client, change the configuration file fhredir.cfg, to:
DOS, Windows and OS/2:
```
/s serverone
/f filetwo.dat
```
UNIX:
```
-s serverone
-f filetwo.dat
```
This configuration file causes the program to create filetwo.dat on the local Fileshare Client. fileone.dat is again created on the Fileshare Server. You do not have to recompile the application.
Run the program again
DOS, Windows and OS/2:
```
run wr2test
```
UNIX:
```
cobrun wr2test
```

filetwo.dat is written to your local machine and fileone.dat is again written to the server.

19.4 Implementing Fileshare Recovery

A database reference file lists all the files under Fileshare's control, together with any information describing how you want the files treated. One of the uses of a database reference file is to track all changes to specified files in a recovery log file.

In the event of a system failure, you can recover all your lost data by applying the recovery log to the most recent backup. This section illustrates how to set up and use the recovery features.

If Fileshare is running on the Fileshare Server, stop it by pressing the Esc key and entering Y at the prompt.
Delete fileone.dat and filetwo.dat and the corresponding .idx files from the Fileshare Server machine. Also delete the filetwo.dat and the corresponding .idx file from the Fileshare Client machine.
On the Fileshare Server, create a database reference file by entering:
DOS:
```
xm fs /d dbase1.ref /l server1 /f fileone.dat
```
Windows:
```
fsw /d dbase1.ref /l server1 /f fileone.dat
```
Windows NT, Windows 95 and OS/2:
```
fs /d dbase1.ref /l server1 /f fileone.dat
```
UNIX:
```
fs -d dbase1.ref -l server1 -f fileone.dat
```
NetWare:
```
load fs /d dbase1.ref /l server1 /f fileone.dat
```
This statement:
- creates the database reference file dbase1.ref
- specifies the recovery log server1
- activates logging for fileone.dat
Add the entry:
DOS, Windows and OS/2:
```
/d dbase1.ref
```
UNIX:
```
-d dbase1.ref
```
to the Fileshare Server Configuration file fs.cfg that you created in the previous section.
Start the Fileshare Server:
DOS:
```
xm fs 
```
Windows:
```
fsw 
```
Windows NT, Windows 95, OS/2 and UNIX:
```
fs
```
NetWare:
```
load fs
```
On the Fileshare Client, ensure that you still have the same fhredir.cfg file from the previous example and run the wr2test program:
DOS, Windows and OS/2:
```
run wr2test
```
UNIX:
```
cobrun wr2test
```
On the Fileshare Server, stop Fileshare by pressing Esc and entering Y at the prompt.
It should have created fileone.dat and the log file server1.l01.
Simulate a loss of data on the Fileshare Server by deleting fileone.dat and its corresponding .idx file.
All the information about the records written to that file is stored in the log file. Now you can restore the file using Fileshare recovery.
From the Fileshare Server enter:
DOS:
```
xm fs /r dbase1.ref
```
Windows:
```
fsw /r dbase1.ref
```
Windows NT, Windows 95 and OS/2:
```
fs /r dbase1.ref
```
UNIX:
```
fs -r dbase1.ref
```
NetWare:
```
load fs /r dbase1.ref
```
The file fileone.dat should be recreated successfully.

19.5 Using Transaction Processing

Fileshare transaction processing enables you to change your files only when you are sure the information is complete. When you want to secure the changes, you issue a COMMIT; when you want to cancel the changes, you issue a ROLLBACK.

We use the demonstration program tptest.cbl to illustrate transaction processing.

Ensure that you still have the fhredir.cfg and fs.cfg files that you used in the previous examples.

DOS, Windows and OS/2:
On DOS, Windows, Windows 95, Windows NT and OS/2, this program is in the demo subdirectory of the COBOL system directory structure.

UNIX:
On UNIX, this program is available in the $COBDIR/demo/fs directory.

On the Fileshare Server, delete the fileone files.
Start Fileshare by entering:
DOS:
```
xm fs
```
Windows:
```
fsw 
```
Windows NT, Windows 95, OS/2 and UNIX:
```
fs
```
NetWare:
```
load fs
```
On the Fileshare Client, compile tptest.cbl:
DOS, Windows and OS/2:
```
cobol tptest int() nognt;
```
UNIX:
```
cob -i tptest.cbl
```
tptest has the CALLFH(FHREDIR) directive coded in the program. Transaction processing is switched on by having the WITH ROLLBACK clause in the LOCK MODE statement.

The program writes 10 records in a transaction and issues a COMMIT statement. It writes 10 more records, but then issues a ROLLBACK statement. The resulting file, fileone.dat on the Fileshare Server, should contain only the first 10 records written.
Run the program:
DOS, Windows and OS/2:
```
run tptest
```
UNIX:
```
cobrun tptest
```

Fileshare

Fileshare Server Messages