Callable Sort Module (Extsm) Fileshare Tutorial

# Chapter 18: Fileshare

Fileshare Version 2 is a client/server system designed to provide more efficient processing of data files that are accessed concurrently, across a network, by a large number of users.

In addition, Fileshare Version 2 offers features that are not available with the base COBOL file handler including transaction processing and rollforward recovery logging.

Fileshare Version 2 runs on DOS (16-bit), Windows (16-bit), Windows 95 (32-bit), Windows NT (32-bit), OS/2 (16-bit and 32-bit), UNIX (32-bit), and on Novell NetWare (32-bit) as a NetWare Loadable Module (NLM). The efficiency of some of the more advanced features (such as rollforward recovery logging) is operating-system dependent.

This chapter describes how to use Fileshare Version 2 on DOS, Windows, Windows 95, Windows NT, OS/2 and UNIX. The labels on the left-hand side of the page identify any entries that are specific to a particular environment. See the chapter Fileshare on Novell NetWare for details on the Fileshare NLM.

For brevity, throughout the remainder of this manual, Fileshare Version 2 is referred to as Fileshare.

## 18.1 Overview

Fileshare is best suited to applications that share data files, concurrently, between many users, across a network. It supports all of the functionality provided by the base COBOL file handling system and provides several additional features:

• Reduced network traffic

• Transaction processing

• Rollforward recovery logging

• Logon and file open security checks

The ability of any one application to take advantage of these features depends on:

• The way the application processes the shared data files

• The type of data files the application shares

• The operating system on which the Fileshare Server is running

• The communications protocol being used between the Fileshare Client and the Fileshare Server

You do not need to make any program source code changes to use the basic Fileshare system. Source code changes are only needed to take advantage of some of the advanced features provided by Fileshare.

### 18.1.1 How Fileshare Works

Using the base COBOL file handling system, a typical COBOL I/O request to a shared data file causes the file handler to make several accesses to that data file across the network. See Figure 18-1.

Figure 18-1: Conventional network

With Fileshare, a program that needs to access a data file has its request processed by the File Handling Redirector (FHRedir) module. The FHRedir module sends the request over the network to a Fileshare Server that performs the low-level I/O operations and then passes the result of the I/O operation, including the file status, back to FHRedir. FHRedir returns the result to the program. See Figure 18-2.

A Fileshare System is made up of:

 Fileshare Clients A Fileshare Client comprises a user program, making data file I/O requests, via the FHRedir module. FHRedir redirects the I/O requests to a Fileshare Server. Fileshare Servers A Fileshare Server runs on the same machine as the data files that you want to access. The Fileshare Server accepts requests across the network from the Fileshare Client, processes them by calling a local copy of the Callable File Handler (ExtFH) and then returns the result to the Fileshare Client.

Figure 18-2: Fileshare network

Notes:

• The Fileshare Server and the Fileshare Client can be running on the same physical machine. For example, with a multi-tasking operating system such as OS/2, the Fileshare Client can run in one session and the Fileshare Server can run in another session. Using this method, you can develop Fileshare applications without requiring access to a network. You should be aware, however, that performance improvements will not be observed, as no network is being used.

• You can also run the Fileshare Server in the same session as the Fileshare Client using the single user mode of operation. This enables you to take advantage of the advanced Fileshare features such as transaction processing without the need for a network or a multi-tasking operating system. For more information on the single user mode of operation, see the section Single User Mode.

Since a single Fileshare Server processes all the requests from several Fileshare Clients, it can use a single copy of the Callable File Handler, regardless of how many users are accessing the Fileshare Server. This has several advantages:

• The Fileshare Server can open the data files exclusively making full use of both its own cache and the operating system's cache.

• The Fileshare Server does not need to obtain semaphores on the data file. Normally semaphores are needed to control concurrent access to shared data files.

• The Fileshare Server can process record locks internally without the need to make calls to the operating system.

## 18.2 Standard Fileshare Operation

This section describes what you need to do at the Fileshare Client and Fileshare Server machines to enable a standard COBOL program to use Fileshare. Once you have read this section, you should be able to configure any COBOL program to use Fileshare. A Fileshare tutorial is provided in the chapter Fileshare Tutorial. You are encouraged to try this tutorial after you have read this section.

### 18.2.1 Standard Fileshare Operation - Fileshare Client

At the Fileshare Client machine, you need to do two things to enable your COBOL program to use Fileshare:

• Force your program to pass data file I/O requests to the File Handling Redirector module (FHRedir), thus creating a Fileshare Client.

• Configure your Fileshare Client, specifying the name of the Fileshare Server to connect to and the communications protocol to use when connecting.

#### 18.2.1.1 Using FHRedir

If your program uses COBOL I/O syntax, you must compile your program with the CALLFH"FHREDIR" directive so that FHRedir processes any I/O requests that your program makes.

If your program uses the Callable File Handler Interface, you need to change the program so that it calls "FHREDIR" and not "EXTFH". (The call interface to the FHRedir module is exactly the same as the call interface to ExtFH.) For a description of the ExtFH interface, see the chapter Callable File Handler.

Example

call "FHREDIR" using operation-code, fcd

Having performed either of these steps (recompiling the program with CALLFH"FHREDIR" or calling FHRedir instead of ExtFH), you have created a Fileshare Client but your program works in exactly the same way as it did before because FHRedir simply forwards I/O requests to a local copy of the Callable File Handler.

To use Fileshare, you need to configure your Fileshare Client to redirect the requests to a Fileshare Server.

#### 18.2.1.2 Configuring Your Fileshare Client

The Fileshare Client configuration file is an ordinary text file that you can create using any text editor. By default, it is called fhredir.cfg The Fileshare Client searches for this file in the current working directory of your application and then along the path specified by the COBDIR environment variable. Alternatively, you can specify the location of the Fileshare Client configuration file using the FHREDIR environment variable.

Example

DOS, Windows and OS/2:

set FHREDIR=c:\client.cfg

This example tells the Fileshare Client to use the configuration file client.cfg in the root directory on drive c:.

UNIX:

FHREDIR=/client.cfg
export FHREDIR

This example tells the Fileshare Client to use the configuration file client.cfg in the root directory.

Configuring the Fileshare Client enables you to specify how you want to treat your data files, that is, as either:

• Local data files, located on the machine where the Fileshare Client is running. To access local data files, the Fileshare Client uses a local copy of the Callable File Handler. This is the default.

• Remote data files, located on the machine where the Fileshare Server is running. To access remote files, I/O operations are redirected to the appropriate Fileshare Server by the File Handling Redirector module (FHRedir).

In order to successfully redirect I/O operations, FHRedir needs to know:

• Which Fileshare Server to communicate with

• Which communications protocol to use when contacting the server
##### 18.2.1.2.1 Specifying Which Fileshare Server to Use

Each Fileshare Server on the network is identified by a unique name, assigned when the Fileshare Server is started. The Fileshare Client uses this name to specify which Fileshare Server to use.

There are two ways to specify the Fileshare Server name:

• As part of the filename in your program

• In a Fileshare Client configuration file

Specifying the Fileshare Server as part of the filename in your program requires changes to your code while using a configuration file does not.

These methods are listed below in the order of priority the Fileshare Client uses when processing requests to a particular data file.

##### As a Filename

Specifying the server as a filename in your program overrides any configuration file settings.

DOS, Windows and OS/2:

 select account-file
assign to "$$server1\c:\accounts\main.dat" This SELECT statement tells FHRedir to direct requests for this data file to the Fileshare Server named server1. The data file is main.dat in the directory accounts on drive c: on the Fileshare Server machine. FHRedir passes the characters appearing after the text string $$server1\ to the Fileshare Server as the name of the file.

UNIX:

 select account-file
assign to "$$server1//accounts/main.dat" This statement tells FHRedir to direct requests for this data file to the Fileshare Server named server1. The data file named main.dat is in the directory accounts. (FHRedir passes the characters appearing after the text string $$server1/ to the Fileshare Server as the name of the file.)

##### In a Configuration File

To specify a default Fileshare Server, use the /s option in the Fileshare Client configuration file. For example:

DOS, Windows and OS/2:

/s server2


UNIX:

-s server2

This configuration file entry tells the Fileshare Client to use the default Fileshare Server named server2. FHRedir redirects all file I/O to this server unless:

• You specifically define a file as a local file. (See the section Fileshare Client Configuration).

• You specify that a file is on a different Fileshare Server, using the Fileshare Client configuration file. (See the section Fileshare Client Configuration).

• You specify a Fileshare Server as part of the filename in your program.

Notes:

• The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names.

• Filenames appearing in the configuration file are case sensitive.

• The filename in the configuration file must appear exactly as it will appear to the Fileshare Client on the first OPEN request.

##### 18.2.1.2.2 Specifying Which Communications Protocol to Use

A Fileshare Client communicates with a Fileshare Server using the Common Communications Interface (CCI). Full details of CCI are given in your Programmer's Guide to Communications.

CCI provides several different communications protocols. The protocol you use depends on the operating system the Fileshare Client and Fileshare Server(s) are running on and the type of network you are using.

By default, the following communications protocols are used:

Operating System

COBOL Product

Default CCI Protocol
DOS 16-bit CCINETB
Windows V3 16-bit CCINETB
Windows 95 32-bit CCITCP
Windows NT 32-bit CCITCP
OS/2 16/32-bit CCINETB
UNIX 32-bit CCITCP

If a communications protocol other than the default is required, it must be specified in the Fileshare Client configuration file.

To specify an alternative default CCI protocol, use the /cm option:

/cm ccinamp

This entry makes the Named Pipes protocol (CCINAMP) the default .

To specify that a particular CCI protocol is used when communicating with a specific Fileshare Server, use the /cm and /s options together:

/cm cciipx /s server1

This configuration file entry tells the Fileshare Client to use the Novell IPX protocol (CCIIPX) for communicating with the Fileshare Server named server1.

/cm ccinamp
/cm cciipx /s server1

These configuration file entries tell the Fileshare Client to use the Named Pipes protocol (CCINAMP) as the default and the Novell IPX protocol (CCIIPX) for communicating with the server named server1.

### 18.2.2 Standard Fileshare Operation - Fileshare Server

You must start the Fileshare Server running before Fileshare Clients can connect to it. Invoke the Fileshare Server using one of these command lines:

DOS:

xm fs

Windows V3:

fsw

NetWare:

load fs

Windows NT, Windows 95, OS/2 and UNIX:

fs


Fileshare Server configuration options can be specified on the command line (separated by spaces), or in the Fileshare Server configuration file (a text file which you can create using any text editor).

The Fileshare Server determines the configuration file to use as follows:

• If the FS environment variable is set, the Fileshare Server uses the configuration file specified by the FS environment variable

• Otherwise, the default configuration file fs.cfg, in the current working directory of the Fileshare Server, or along the path specified by the COBDIR environment variable, is used

Before a Fileshare Server is invoked, it needs to know:

• The name to assign itself on the network

• The communications protocols that it can use

#### 18.2.2.1 Specifying a Fileshare Server Name

Each Fileshare Server is identified on the network by a unique name. This name is specified using the /s option .

Example

UNIX:

-s server1

DOS, Windows, NetWare and OS/2:

/s server1

In this example the name of the Fileshare Server is registered as server1.

Note: The Fileshare Server cannot be initialized unless it registers a name on the network. The server-name can be up to 16 characters in length, depending on the CCI protocol you are using.

#### 18.2.2.2 Specifying Which Communications Protocols to Use

You do not need to configure the communications protocol for the Fileshare Server unless a specific CCI protocol must be used. When no CCI protocol is specified, the default CCI protocol for the operating system of the machine that the Fileshare Server is running on is used, as follows:

Operating System

COBOL Product

Default CCI Protocol
DOS 16-bit CCINETB
Windows V3 16-bit CCINETB
Windows 95 32-bit CCITCP
Windows NT 32-bit CCITCP
OS/2 16/32-bit CCINETB
UNIX 32-bit CCITCP
NetWare 32-bit CCIIPX

You must specify all of the CCI protocols (apart from the default) that may be used by Fileshare Clients to contact this Fileshare Server. To do this, use the /cm option.

Example

DOS, Windows, OS/2:

/cm ccinamp
/cm cciipx

These entries in the Fileshare Server configuration file tell the Fileshare Server that Fileshare Clients can communicate with it using the Named Pipes (CCINAMP) and the Novell IPX (CCIIPX) protocols.

UNIX:

-cm ccitcp
-cm ccinampu

These entries in the Fileshare Server configuration file tell the Fileshare Server that Fileshare Clients can communicate with it using TCP/IP (CCITCP) and the Named Pipes for UNIX (CCINAMPU) protocols.

#### 18.2.2.3 Stopping the Fileshare Server

Once started, a Fileshare Server runs as an active process until you explicitly stop it. You must stop the Fileshare Server when you no longer need it. To do this, press the Escape key. Fileshare displays:

FS097-I Are you sure you wish to close Fileshare ?

Enter Y to confirm that you want Fileshare to terminate. Any other entry causes the Fileshare Server to continue running.

If any data files are still open, the following warning is displayed:

FS111-I Warning - files are still open
Continue with the close (Y/N) ?

Enter Y to confirm that you want Fileshare to terminate. Fileshare automatically closes all data files and rolls back any outstanding transactions. Any other entry causes the Fileshare Server to continue running. This warning indicates one of the following:

• Fileshare Clients are still active, with open data files.

• A user program terminated abnormally without closing the data files it had open.

You can stop the Fileshare Server from a remote workstation using the Fileshare Monitor utility (FSView) or the Fileshare Manager module (fsmgr) . See the chapter FSView for details of FSView and fsmgr.

If you are using the CCITCP or CCINAMPU protocol and the Fileshare Server terminates abnormally, you can restart the Fileshare Server using the same server-name. However, Fileshare displays the warning message:

FS153-I The Fileshare Server name has been reregistered on the
network.

### 18.2.3 Tutorial

Now that you have completed this section on standard Fileshare operation, you may find it useful to go through the Fileshare tutorial. See the chapter Fileshare Tutorial for details.

## 18.3 Fileshare Client Configuration

This section describes all of the available Fileshare Client configuration options. These options can appear as many times as necessary within a Fileshare Client configuration file, and in any order, but only one option can be specified per line.

Notes:

• The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names.

• Filenames specified in the configuration file must match exactly the filenames used in your program (including case).

• UNIX:
In this section, options are shown starting with a forward slash (/). This is how you specify the options on DOS, Windows and OS/2. On UNIX, use the hyphen (-) character instead of the forward slash (/).

• UNIX:
Filenames are shown using the naming convention that is used on DOS, Windows and OS/2. On UNIX systems, use the UNIX file naming convention.

[/cm CCI-protocol]

Specifies the default communications protocol for this Fileshare Client. Valid values for CCI-protocol are listed below.

[/cm CCI-protocol /s server-name]

Specifies the communications protocol to use when contacting the Fileshare Server, server-name. Valid values for CCI-protocol are listed below.

[/f filename /s server-name]

Specifies that the data file filename is a remote file on the Fileshare Server named server-name. Repeat this option for every data file you want assigned to a specific Fileshare Server that is not the default Fileshare Server. Valid values for filename and server-name are listed below.

[/f filename]

Specifies that filename is a local data file held on the workstation where the Fileshare Client resides. Valid values for filename are listed below.

NetWare:
[/ma machine-address /s server-name]

Specifies the node address of the NetWare server that the Fileshare Server is running on. This is required if Fileshare Clients cannot contact a Fileshare NLM Server directly. The node address can be obtained using the NetWare Requester SLIST command. See the section Novell Communications in the chapter Fileshare on Novell Netware for more information.

[/s server-name]

Specifies server-name as a default Fileshare Server.

Accesses to data files not directed to a particular Fileshare Server or defined as local data files are directed to the default Fileshare Servers. The order in which the default Fileshare Servers are defined in the Fileshare Client configuration file is the order in which the Fileshare Client contacts each Fileshare Server in an attempt to locate the file.

If the data file is not found on any Fileshare Server, the request for that data file is directed to the first default Fileshare Server listed in the configuration file.

Valid values for options in the Fileshare Client configuration file are:

 CCI-protocol ccinetb ccinamp ccitcp ccinampu cciipx ccilu2 cciappc server-name Any character string up to 16 characters long depending on the CCI protocol you are using. The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names. filename Any valid filename that is supported by the operating system. Filenames cannot contain embedded space characters. You can use terminating wildcard characters in filename to designate groups of files. For example, use /f \accounts\* to specify all files starting with the string \accounts\.

Example

This example shows a typical Fileshare Client configuration file.

/s server1
/s server2
/cm cciipx
/f \orders\* /s server3
/cm ccitcp /s server3
/f \accounts\payroll.dat
/f \transport\delivery\*

where:

Line 1:

/s server1

Specifies that server1 is one of the default Fileshare Servers.

This Fileshare Server is searched for any file that is not defined to be on a particular Fileshare Server (see Line 4) or as local (see Lines 6 - 7). If you specify more than one default Fileshare Server (see Line 2), the Fileshare Servers are searched in the order that you have defined them in the configuration file. In this example, server1 is searched before server2.

Line 2:

/s server2

Specifies that server2 is also a default Fileshare Server. If you access a file that you have not defined to be on a particular Fileshare Server (see line 4) or as local (see lines 6 and 7), this Fileshare Server is searched after the Fileshare Server server1.

Line 3:

/cm cciipx

Specifies that the default communications protocol is CCIIPX. When the Fileshare Client tries to contact a Fileshare Server that does not have a specific CCI protocol defined (see Lines 1 and 2), this is the one used.

Line 4:

/f \orders\* /s server3

Specifies that FHRedir should direct all accesses to files with a name beginning with the string \orders\ to the Fileshare Server named server3.

Line 5:

/cm ccitcp /s server3

Specifies that the communications protocol to use when communicating with the Fileshare Server, server3 is ccitcp. This overrides any default CCI protocol specified in the Fileshare Client configuration file (see Line 3).

Line 6:

/f \accounts\payroll.dat

Specifies that the file \accounts\payroll.dat is a local file on the Fileshare Client machine. The Fileshare Client accesses this file using a local copy of the Callable File Handler.

Line 7:

/f \transport\delivery\*

Specifies that any files with a filename beginning with the string \transport\delivery\ are local files.

## 18.4 Fileshare Server Configuration

This section describes all of the available Fileshare Server configuration options. The /s option that defines the server-name is compulsory. All other options are optional or have default values that are specified below.

Notes:

• UNIX:
In this section, options are shown starting with a forward slash (/). This is how you specify the options on DOS, Windows and OS/2. On UNIX, use the hyphen (-) character instead of the forward slash (/).

• UNIX:
Filenames are shown using the naming convention that is used on DOS, Windows and OS/2. On UNIX systems, use the UNIX file naming convention.

/s server-name

Specifies the name that the Fileshare Server registers on the network. This must be a character string, up to 16 characters in length depending on the CCI protocol that you are using. The name specified must be unique. If a Fileshare Server with the same name is already registered on the network, an error is returned.

[/d database-reference-file]

Specifies the name of the database reference file that the Fileshare Server is to use. The database reference file is used to determine which Fileshare features you want to use. See the section Database Reference File Maintenance for details.

[/t timeout-period]

Sets the record lock timeout period after which the Fileshare Server releases all record locks held by a Fileshare Client and rolls back any outstanding transactions. The timeout period is specified in seconds. The default value is 60 seconds. Specifying a value of 0 disables the timeout and record locks are only released under the control of your application program. Valid values are 0 - 99999. The timeout only occurs if another Fileshare Client requests a record currently locked by this Fileshare Client. See the section Automatic Record Lock Timeout for more details.

[/m record-size]

Specifies the maximum record size that can be processed by the Fileshare Server. Setting a lower value than the default value reduces the amount of memory that the Fileshare Server needs to run. The record-size is specified in kilobytes. Valid values are 16 - 64. If you specify a value less than 16, the Fileshare Server uses a buffer size of 16K. If you specify a value greater than 64, the Fileshare Server uses a buffer size of 64K.

[/cm cci-protocol]

Specifies the CCI protocols that the Fileshare Server can use. Repeat this option for every communications protocol that you want to use to contact this Fileshare Server. Valid values for cci-protocol are:

ccinetb
ccinamp
ccitcp
ccinampu
cciipx

[/pf password-file]

Specifies the name of the password file that the Fileshare Server uses. See the section Password File Maintenance for details.

[/tr f]

Activates the Fileshare Server trace option on start-up. Trace messages are written to the screen and to a file called fsscreen.lst in the Fileshare Server's current directory. This option seriously impacts the Fileshare Server's performance so you should only use it for problem investigation.

NetWare:
[/mm memory-limit]

Specifies the maximum amount of memory that a Fileshare NLM allocates, in kilobytes. The default setting is 8000 kilobytes. Valid values are 4000 upwards. If you specify less than 4000, the Fileshare Server allocates a maximum of 4000 kbytes.

NetWare:
[/nu user-ID]

Specifies the user-ID that the Fileshare NLM uses when logging onto the NetWare server. The Fileshare NLM assumes the access rights of the user-ID specified. For more information, see the chapter Fileshare on Novell NetWare.

OS/2:
[/sc]

Specifies that the Fileshare Server is to use synchronous communications. See the section Synchronous Communications Mode for more details.

UNIX:
[-b]

Specifies that the Fileshare Server is to run as a background process. See the Section Fileshare on UNIX for more details.

Example

This example shows a typical Fileshare Server configuration file.

/s mainsrv
/cm ccinamp
/cm cciipx
/d dbase1.ref
/t 120
/pf \pass\passwd.fil


where:

Line 1:

/s mainsrv

Specifies that the Fileshare Server is to register its name on the network as mainsrv. Fileshare Clients must specify this name when they want to contact this Fileshare Server.

Line 2:

/cm ccinamp

Specifies that ccinamp is one of the communications protocols that a Fileshare Client can use to contact this Fileshare Server.

Line 3:

/cm cciipx

Specifies that cciipx is one of the communications protocols that a Fileshare Client can use to contact this Fileshare Server.

Line 4:

/d dbase1.ref

Specifies that the database reference file the Fileshare Server is to use is named dbase1.ref.

Line 5:

/t 120

Specifies that the automatic record lock timeout period is 120 seconds.

Line 6:

/pf \pass\passwd.fil

Specifies that the Fileshare Password Security feature is enabled and that the password file (containing valid user-IDs and passwords) is \pass\passwd.fil.

## 18.5 Transaction Processing

Transaction processing enables you to group a set of data file updates together into one logical unit of work. This unit of work is known as a transaction. The changes you make as part of a transaction can be:

• Permanently reflected in the data files by committing the work.

• Removed from the data files by rolling back the work. When a transaction is rolled back, the Fileshare Server returns the data files to the state they were in before the transaction started.

A transaction can include multiple updates to multiple data files on multiple Fileshare Servers.

A transaction starts when your program performs the first update operation after:

• The file is opened

• A COMMIT or ROLLBACK statement is executed

In COBOL, the update operations are WRITE, REWRITE and DELETE.

A transaction terminates when:

• A COMMIT verb is executed

• A ROLLBACK verb is executed

• The transaction is timed out (see the section Automatic Record Lock Timeout)

Notes:

• The COMMIT and ROLLBACK verbs release all the record locks held by a program on every data file. This does not depend on whether or not you specified the WITH ROLLBACK clause for a particular file.

• The time taken to process a COMMIT or ROLLBACK operation is directly proportional to the number of updates performed in that transaction.

• If you try to CLOSE a file that is participating in an active transaction, a 9/100 error status is returned and the file remains open. A COMMIT or ROLLBACK needs to be issued before the CLOSE can be executed.

• When you use the WITH ROLLBACK clause , multiple record locking is implicitly defined on the file.

Before using transaction processing you are strongly advised to do the following to ensure the highest level of integrity for your data:

• Include any file on which transaction processing is to be performed in the database reference file of the Fileshare Server that services the I/O requests against that file. For more information, see the section Database Reference File Maintenance.

• Specify a rollforward recovery log file in the database reference file. For more information, see the section Rollforward Recovery Logging.

Record locks are implicitly obtained on every record that is updated in a transaction. If a transaction is temporarily suspended, for example, if your program requests input and the user is not responding, record locks can remain in the file for a considerable length of time. If another Fileshare Client tries to access the locked records, and a specified length of time has passed, the Fileshare Server aborts (rolls back) the transaction. When this happens, the transaction is said to be timed out by the Fileshare Server. For more information, see the section Automatic Record Lock Timeout.

Note: By keeping the number of updates performed in a transaction to a minimum, the number of record locks obtained is also kept to a minimum. This reduces the number of record locking conflicts between Fileshare Clients sharing the data, and increases the speed of any subsequent COMMIT or ROLLBACK operations.

### 18.5.1 Automatic Record Lock Timeout

In a multi-user environment where files are being shared, programs use record locks to control concurrent access to individual records. In addition, Fileshare automatically obtains a record lock on any record that it updates within a transaction. The larger the number of record locks being held, however, the less concurrent access to data is possible. It is beneficial, therefore, for any one program to keep the number of record locks that it holds at any one time to a minimum.

If a Fileshare Client obtains a lock on a record (either explicitly or because it updated the record within a transaction) and a second Fileshare Client tries to read the locked record, the Fileshare Server checks to see how long ago the Fileshare Client holding the record lock contacted the Fileshare Server. If this period is greater than the timeout period, then:

• The Fileshare Server automatically rolls back any pending transaction being carried out by the first Fileshare Client.

• The Fileshare Server releases all the record locks held by the first Fileshare Client.

• The Fileshare Server returns error 9/068 "record locked" to the Client trying to read the record. Retrying the operation succeeds in gaining access to the record because the lock has now been released.

If this period is less than the timeout period, then:

• The Fileshare Server returns error 9/068 "record locked" to the Fileshare Client trying to read the record.

The default timeout period is 60 seconds. You can change this value using the /t option in the Fileshare Server configuration file. Specifying a value of 0 disables the automatic record lock timeout such that record locks will only be released under application program control.

A program that is timed out receives error 9/125 on its next I/O operation. You should treat this as a warning message and repeat the operation on which the error was returned. The Fileshare Server will roll back any active transaction and release all the record locks held by the program that timed out.

### 18.5.2 Transaction Processing - Fileshare Client

For each data file on which you want transaction processing active, use the WITH ROLLBACK clause when you define the data file using the SELECT statement in your COBOL program.

Example

     select test-file assign to "test.dat"
organization indexed
record key prime-key
lock mode manual with rollback
...

This sample code specifies that transaction processing is active on the file test.dat.

In your program, use the COMMIT verb to make the updates in a transaction permanent. Use the ROLLBACK verb to remove the updates in a transaction from the data files.

The COMMIT and ROLLBACK verbs work on all data files involved in a transaction. This means that you cannot check the status of the COMMIT or ROLLBACK operation using the file status of any one data file. Instead, you must call FHRedir to check the status of the COMMIT or ROLLBACK. The entry point to call in the FHRedir module is fs_status . The format of the call is:

call "fs_status" returning t-status
end-call

where t-status is defined as:

01 t-status pic x(2) comp-x.

A non-zero value returned in t-status indicates that the COMMIT or ROLLBACK operation failed.

Example

 1     SELECT test-file ASSIGN TO "test.dat"
2     LOCK MODE MANUAL WITH ROLLBACK
3    ...
4     OPEN I-O test-file
5     ...
6     move 1 to prime-key
7     WRITE test-file-record
8     ...
9     COMMIT
10     call "fs_status"
11         returning t-status
12     end-call
13     if t-status < > 0
14         display "Warning - Commit operation failed"
15     end-if
16     move 2 to prime-key
17     WRITE test-file-record
18     ...
19     ROLLBACK
20     call "fs_status"
21         returning t-status
22     end-call
23     if t-status < > 0
24         display "Warning - Rollback operation failed"
25     end-if
26     WRITE test-file-record
27     ...


where:

Lines 1 - 2:

SELECT test-file ASSIGN TO "test.dat"
LOCK MODE MANUAL WITH ROLLBACK

Specifies transaction processing for this data file.

Line 7:

WRITE test-file-record

Starts a new transaction.

Line 9:

COMMIT

Makes the updates to test-file permanent and terminates the transaction.

Lines 10 - 15:

call "fs_status"
returning t-status
end-call
if t-status < > 0
display "Warning - Commit operation failed"
end-if

Checks the status of the COMMIT operation.

Line 17:

WRITE test-file-record

Starts a new transaction.

Line 19:

ROLLBACK

Removes the updates made to test-file and terminates the transaction.

Lines 20 - 25:

call "fs_status"
returning t-status
end-call
if t-status < > 0
display "Warning - Rollback operation failed"
end-if

Checks the status of the ROLLBACK operation.

Line 26:

WRITE test-file-record

Starts a new transaction.

You do not need to change the configuration of the Fileshare Client to enable transaction processing.

### 18.5.3 Transaction Processing - Fileshare Server

You do not need to change the configuration of the Fileshare Server to enable transaction processing. However, if you recover a data file using the Rollforward Recovery Utility (see below), any outstanding transactions at the end of the recovery process are implicitly rolled back. For information on this utility, see the section Rollforward Recovery Utility.

## 18.6 Rollforward Recovery Logging

A system failure can result in loss of data in either of the following circumstances:

• The Fileshare Server's cache or operating system's cache is not written to disk.

• The system failed while updating a file. In this case, the integrity of the files cannot be guaranteed.

Rollforward recovery logging is the method used by Fileshare to store all the updates made to your data files in one or more log files. If your system fails, resulting in loss of data, the Rollforward Recovery Utility together with the log file(s) can be used to re-apply the updates to a back-up copy of the original data files. When the recovery is complete, the files contain the data they contained at the time of the system failure (with any outstanding transactions rolled back).

You do not need to make any changes to the Fileshare Client in order to use rollforward recovery logging.

### 18.6.1 Rollforward Recovery Logging - Fileshare Server

To log updates to one or more files you need to create a database reference file containing the name of the file(s) for which updates are to be logged, and the name of the log file. See the section Database Reference File Maintenance for details on creating database reference files.

You do not need to include an extension when you specify the log file name as this is generated automatically by the Fileshare Server. If you do specify an extension, the following message is displayed:

FS180-W The log file name specified has an extension.
FS181-I The name of the log file has been changed to <filename>.

During the logging process the Fileshare Server creates one or more recovery log files. The first recovery log file is called a "starter" log file, and subsequent log files are called "continuation" log files. The Fileshare Server creates a continuation log file whenever the current log file is backed up (see the section Recovery Log File Backup below).

The current recovery log file always has an extension beginning with the character "L". A recovery log file that has been backed up has an extension beginning with the character "B". Following either of these letters is a two digit number indicating the recovery log file number, starting at 01. These automatically generated extensions indicate the order in which the log files were written, and hence the order in which they should be applied if a rollforward recovery is performed. For example, suppose you specify a log file called RECOVER. When the Fileshare Server starts up it creates a log file called RECOVER.L01 and logs updates in this file. If the recovery log file is backed up, the Fileshare Server renames the current log file RECOVER.B01 and creates a new one called RECOVER.L02. If the Fileshare Server is shut down, there would be two recovery log files: RECOVER.B01 is called the "starter" log file and RECOVER.L02 is a "continuation" log file. There is only ever one starter log file, but there can be a number of continuation log files.

When performing a recovery operation, the Rollforward Recovery Utility processes the starter log file first and then the continuation log files in the order that they were created.

Data files with entries in the database reference file have their updates logged unless you explicitly turn logging off. A data file entry is added to the database reference file using the /f option of the Database Reference File Maintenance Utility. To turn logging off for a particular data file, use the /o l (omit logging) option when you add the filename entry to the database reference file .

Due to the caching used by some operating systems, not all of the information written to the log file is physically written to disk. The Fileshare Server periodically calls the operating system to force the log file updates to be written . By default, the log file is flushed after every 100 records are written to the log file. You can configure this interval using the /lc (log count) option when you add the log file name to the database reference file. If you specify a log count of zero, the Fileshare Server does not make any calls to the operating system to flush the updates to disk. Instead, the operating system controls the flushing of the log file to disk.

The log file updates are also flushed to disk after every COMMIT operation.

Note: In UNIX environments, log file flushing is only available on AIX and SVR4-compliant UNIX environments. If the version of the operating system does not support log file flushing, the Fileshare Server displays a warning message when it is started.

If a transaction was pending at the time of a system failure, the Rollforward Recovery Utility implicitly rolls back the transaction when the files are recovered.

Rollforward recovery logging can severely affect performance. You can use the /ol option in the database reference file to switch logging off for those files for which this feature is not essential. Alternatively, you can omit entries for these files from the database reference file altogether.

The recommended method of using recovery logging is:

1. Each time you want to take a backup of your data files (preferably every day), shut down the Fileshare Server. The Rollforward Recovery Log file(s) contains information about every update made to your database files since the Fileshare Server was started.

2. Now take a backup of your database files. The log file is now obsolete. Delete it.

3. Restart the Fileshare Server. It creates a new log file, and any further updates to the files in the database are logged in this new file. You only need to log the updates since your last backup. In the event of data loss due to a system failure, you can restore your latest database backup and re-apply the updates recorded in the log file(s) using the Rollforward Recovery Utility.

If you have a large number of updates being logged, the log file can grow very large. If the disk where the log file resides were to become full, the ability to write records to the log file could be lost. This would result in an incomplete log file forcing the Fileshare Server to close down. A warning is displayed when the amount of free disk space for the log file drops below a certain percentage of the total disk. You can configure this percentage using the /p database reference file option. When you see this warning take one of the following actions:

• Close down the Fileshare Server and take a new back up of your data files. This enables you to discard the log file and continue with a new one when the Fileshare Server is restarted.

• Use the FSView or fsmgr supervisor functions to backup the log file. See the chapter FSView for more information.

If you ignore the warning message and the log file continues to grow larger, the Fileshare Server suspends operation when the free disk space available for the log file drops below 200,000 bytes. It displays error message FS030 and waits for the old log file to be removed manually before continuing with a new log file of the original name.

### 18.6.2 Recovery Log File Backup

You can back up the recovery log file (for example when the disk is becoming full) using the FSView utility (see the chapter Fsview for more details) or an FSMgr API.

Normally the backup file is placed in the same directory as the log file itself. However, you can specify a different directory using the Database Reference File Maintenance Utility /backup option.

For example, the commands:

DOS:

xm fs /d dbase.ref /backup logback

Windows:

fsw /d dbase.ref /backup logback

Windows NT/95:

fs /d dbase.ref /backup logback

UNIX:

fs -d dbase.ref -backup logback

OS/2:

fs /d dbase.ref /backup logback

NetWare:

load fs /d dbase.ref /backup logback

add an entry to the database reference file called dbase.ref which specifies that the directory in which to place backed up recovery log files is logback. A full path can be specified for the recovery log file backup directory. Paths which are not fully qualified are taken to be relative to the current directory of the Fileshare Server.

Example

DOS:

xm fs /d dbase.ref /l \logdir\log /lc 20 /p 20
xm fs /d dbase.ref /backup \store
xm fs /d dbase.ref /f test1.dat
xm fs /d dbase.ref /f test2.dat /o l

Windows:

fsw /d dbase.ref /l \logdir\log /lc 20 /p 20
fsw /d dbase.ref /backup \store
fsw /d dbase.ref /f test1.dat
fsw /d dbase.ref /f test2.dat /o l

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /l \logdir\log /lc 20 /p 20
fs /d dbase.ref /backup \store
fs /d dbase.ref /f test1.dat
fs /d dbase.ref /f test2.dat /o l

UNIX:

fs -d dbase.ref -l /logdir/log -lc 20 -p 20
fs -d dbase.ref -backup /store
fs -d dbase.ref -f test1.dat
fs -d dbase.ref -f test2.dat -o l

NetWare:

load fs /d dbase.ref /l \logdir\log /lc 20 /p 20
load fs /d dbase.ref /backup /store
load fs /d dbase.ref /f test1.dat
load fs /d dbase.ref /f test2.dat /o l

This set of commands creates a database reference file that specifies:

• The database reference file is called dbase.ref.

• The log file name is log in the directory logdir. The first log file that the Fileshare Server will use, therefore, is log.L01.

• The Fileshare Server flushes the log file to disk every time it writes 20 records to the log file (as well as whenever a COMMIT statement is executed).

• A warning message is displayed when the amount of space left on the drive holding the log file falls below 20 percent.

• When the log file is backed up, the backup file is to be placed in the directory store.

• Updates to the data file test1.dat are logged in the log file.

• Updates to the data file test2.dat are not logged in the log file. The /o l option specifies that logging is disabled.

## 18.7 Rollforward Recovery Utility

The Rollforward Recovery Utility enables you to recover updates to data files after a system failure.

Note: The Rollforward Recovery Utility can only be used to recover a database if the updates were logged to a recovery log file. See the section Rollforward Recovery Logging for details.

Before attempting the rollforward recovery process:

1. All of the recovery log files created while the Fileshare Server was active should be in the recovery log file directory (or the log file backup directory if one is specified in the database reference file).

2. The original data files (the back-up versions taken before the Fileshare Server was started) should be restored to their correct directories.

The Rollforward Recovery Utility is invoked using the /r (recover) option. You must specifiy a database reference file when invoking the Rollforward Recovery Utility.

For example:

DOS:

xm fs /r dbase.ref [options]

Windows:

fsw /r dbase.ref [options]

Windows NT, Windows 95 and OS/2:

fs /r dbase.ref [options]



UNIX:

fs -r dbase.ref [options]

NetWare:

load fs /r dbase.ref [options]

In this example dbase.ref is the name of the database reference file used by the Rollforward Recovery Utility. This must be the same as the database reference file used by the Fileshare Server while it was running. The Rollforward Recovery Utility reads the database reference file to determine the location and name of the rollforward recovery log file(s) and the name(s) of the data file(s) to recover.

Note: You can select the data files you want to restore by erasing other entries from the database reference file using the Database Reference File Maintenance Utility (/e option) before invoking the Rollforward Recovery Utility.

The following options can be specified with the Rollforward Recovery Utility:

/dt date-time

Specifies that the Rollforward Recovery Utility restores the updates made to the data files up to the time specified. The format of date-time is YYMMDDHHMMSS (year, month, day, hour, minutes, seconds) specified numerically. When this option is not specified, the Rollforward Recovery Utility applies all of the updates that are stored in the rollforward recovery log file.

/v

Causes the Rollforward Recovery Utility to display additional information about which recovery log files it is searching for and in which directories.

Example

DOS:

xm fs /r dbase.ref /dt 931231235959

Windows:

fsw /r dbase.ref /dt 931231235959

Windows NT, Windows 95 and OS/2:

fs /r dbase.ref /dt 931231235959



UNIX:

fs -r dbase.ref -dt 931231235959

NetWare:

load fs /r dbase.ref /dt 931231235959

This example invokes the Rollforward Recovery Utility using the database reference file dbase.ref. Only those updates made up to 31 December 1993 are restored.

Updates can be recorded in multiple log files if you use the log file backup facility (see the section Recovery Log File Backup for details). The Rollforward Recovery Utility scans the log file directory for the starter log file. If none is found, the directory is scanned for a backed up starter log file. If a starter log file still cannot be found the same procedure is repeated with the searches being performed in the log file backup directory if one is specified in the database reference file. If the Rollforward Recovery Utility is able to locate the starter log file then the recovery procedure commences; if not an error is displayed and the recovery does not start.

Once the starter log file has been processed, the Rollforward Recovery Utility searches for a continuation log file. If no backup of the recovery log file was performed, there will be no continuation log file and the recovery process terminates. The Rollforward Recovery Utility seaches for the continuation log file in the log file directory and then in the log file backup directory. The recovery process continues using the continuation log file(s) until all of the updates have been recovered and applied to the data files.

## 18.8 Database Sequence Numbering

Database sequence numbering provides a method of linking groups of data files so that they can be kept in step.

It is also used to ensure that data files and their corresponding log file are kept in step. In order for the Rollforward Recovery Utility to work, all data files must have sequence numbers that match the log file. The log file contains a sequence number that is written to the header of each file for which sequence number checking is active at the time that the Fileshare Server is shut down.

A sequence number is automatically stored in the header of each data file for which you have specified sequence numbering. Fileshare increments these sequence numbers every time you invoke the Fileshare Server. If the sequence numbers in the data files do not match, the Fileshare Server fails to start after displaying this message:

FS038-S A matching sequence number not found in <filename>

The possible causes for this error are:

• A data file has been replaced that does not contain the same sequence number as all the other data files listed in the database reference file. To recover, you need to install the correct file(s) on the system.

• A power failure prevented proper shutdown of the Fileshare Server when it was last running. To recover the database files use rollforward recovery. See the section Rollforward Recovery Utility.

All data files listed in the database reference file have sequence number checking active by default. You can turn off sequence number checking using the database reference file option /o s (omit sequence numbering). If sequence number checking is not used on a file, your system administrator must make sure that the correct version of the files are installed in the Fileshare System.

Sequence numbering is only available on data files with a variable length record file header. The following file organizations do not contain headers and so sequence number checking is not possible:

• Line sequential files

• Non-data-compressed fixed length record sequential files

• C-ISAM format indexed files

• Non-data-compressed fixed length record relative files

If you have fixed length record data files that you want to use sequence numbering on, create them as variable length record data files. You can do this by changing the file definition in your COBOL program before creating the file.

Example

Data file definition specifying fixed length records:

FD account-file.
01 account-file-record.
03 account-file-prime pic x(4).

Equivalent data file definition specifying variable length records:

FD account-file recording mode is variable.
01 account-file-record.
03 account-file-prime pic x(4).

You do not have to change the configuration of the Fileshare Client or your program to make use of database sequence numbers.

### 18.8.1 Database Sequence Numbers - Fileshare Server

For data files that you entered in the database reference file, sequence number checking is on by default. If you do not need sequence number checking for a particular data file, you can disable the feature by using the /o s (omit sequence numbers) option for that data file's entry in the database reference file.

Example

DOS :

xm fs /d dbase.ref /l \logdir\log.dat
xm fs /d dbase.ref /f test1.dat
xm fs /d dbase.ref /f test2.dat /o l
xm fs /d dbase.ref /f test3.dat /o s

Windows:

fsw /d dbase.ref /l \logdir\log.dat
fsw /d dbase.ref /f test1.dat
fsw /d dbase.ref /f test2.dat /o l
fsw /d dbase.ref /f test3.dat /o s

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /l \logdir\log.dat
fs /d dbase.ref /f test1.dat
fs /d dbase.ref /f test2.dat /o l
fs /d dbase.ref /f test3.dat /o s

UNIX:

fs -d dbase.ref -l /logdir/log.dat
fs -d dbase.ref -f test1.dat
fs -d dbase.ref -f test2.dat -o l
fs -d dbase.ref -f test3.dat -o s

NetWare:

load fs /d dbase.ref /l \logdir\log.dat
load fs /d dbase.ref /f test1.dat
load fs /d dbase.ref /f test2.dat /o l
load fs /d dbase.ref /f test3.dat /o s

This example specifies:

• The database reference file is named dbase.ref.

• The log file is named log.dat in the logdir directory.

• Updates to the data file test1.dat are logged in the log file. By default, sequence number checking is on for any data file in the database reference file, and hence for this file.

• Updates to the data file test2.dat are not logged in the log file. The /o l option specifies that logging is omitted. However, sequence number checking is still active for this file.

• Updates to the data file test3.dat are logged in the log file. However, sequence number checking is not activated for this data file. The /o s option specifies that sequence number checking is not used on this data file.

## 18.9 Virtual File Handler Interface

The Fileshare Server can pass I/O requests to a program specified by you, rather than the Callable File Handler, as long as the program that you specify conforms to the call interface used by the Callable File Handler - see the chapter Callable File Handler for details.

You do not need to change the configuration of the Fileshare Client to use the Virtual File Handler Interface.

### 18.9.1 Virtual File Handler Interface - Fileshare Server

To specify a virtual file handler, use the /ap (application program) option with the /f option in the database reference file to specify the program that I/O requests for a particular data file are passed to by the Fileshare Server.

NetWare:
The Virtual File Handler Interface is not available with Fileshare NLM.

Example

DOS:

xm fs /d dbase.ref /f user1.dat /ap myprog

Windows:

fsw /d dbase.ref /f user1.dat /ap myprog

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /f user1.dat /ap myprog



UNIX:

fs -d dbase.ref -f user1.dat -ap myprog

In this example, the Fileshare Server passes all I/O requests for the data file user1.dat to the program myprog.

DOS, Windows and OS/2:
For DOS, Windows and OS/2, your program should be in .gnt or .int format and reside in the current directory of the Fileshare Server.

UNIX:
For UNIX, you must rebuild the Fileshare executable using the makefile supplied (see the section Fileshare Server Rebuild Script) and either link in your program or specify it as dynamically loadable and supply it in .gnt or .int format in the current directory of the Fileshare Server.

mkfs2 myprog.o

To enable your program to be dynamically loaded in .gnt or .int format enter:

mkfs2 -d myprog

Both commands create a new executable, fs.

## 18.10 Filename Mapping

Filename mapping enables I/O requests made against one data file to be mapped to a different data file when your program is executed. For example, you can use filename mapping to enable applications that use DOS or OS/2 file naming conventions to access data files under the control of a Fileshare Server running on an operating system that uses different file naming conventions, such as UNIX or NetWare.

You do not need to change the configuration of the Fileshare Client to use filename mapping.

### 18.10.1 Filename Mapping - Fileshare Server

To enable filename mapping, use the /af (alternate filename) option with the /f option in the database reference file.

The /fs (filename string) option used in conjunction with the /af option enables you to substitute characters at the start of the filename. This is particularly useful for mapping pathnames.

Example

DOS:

xm fs /d dbase.ref /f old.dat /af new.dat
xm fs /d dbase.ref /fs c: /af e:

Windows:

fsw /d dbase.ref /f old.dat /af new.dat
fsw /d dbase.ref /fs c: /af e:

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /f old.dat /af new.dat
fs /d dbase.ref /fs c: /af e:


UNIX:

fs -d dbase.ref -f old.dat -af new.dat
fs -d dbase.ref -fs /1993 -af /1994

NetWare:

load fs /d dbase.ref /f old.dat /af new.dat
load fs /fs c: /af vol2:

This example adds entries to the database reference file dbase.ref which specify that:

• All requests to the data file old.dat are directed to the data file new.dat.

• For DOS, Windows and OS/2, all accesses to data files starting with c: are directed to drive e:.

• For UNIX, all accesses to data files starting with /1993 are directed to the /1994 directory.

• For NetWare, all accesses to data files starting with c: are directed to vol2.

If the Fileshare Server finds an entry specifying an alternate filename, any character string substitution specified by a /fs option is applied to the new filename.

After processing any string substitution specified by an /fs option, the Fileshare Server does not search the database reference file for any matching /f option using the new filename.

Fileshare processes all filenames as relative to the Fileshare Server's current directory if you have not given a fully qualified filename after the /f option or a fully qualified filename is not passed from the Fileshare Client.

All filenames and paths are forced to upper case by Fileshare Servers not running on the UNIX operating system and are expanded to include the full path to ensure matching. Filenames specified with the /af option are not modified.

Example

DOS:

xm fs /d dbase.ref /f c:\accounts\ledger\bought.dat /af
d:\quarter1\affile1.dat

Windows:

fsw /d dbase.ref /f c:\accounts\ledger\bought.dat /af
d:\quarter1\affile1.dat

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /f c:\accounts\ledger\bought.dat /af
d:\quarter1\affile1.dat


UNIX:

fs -d dbase.ref -f /accounts/ledger/bought.dat -af
/quarter1/affile1.dat

NetWare:

load fs /d dbase.ref /f vol1:\accounts\ledger\bought.dat /af
vol2:\quarter1\affile1.dat

This example adds entries to the database reference file dbase.ref that specify:

• On DOS or OS/2, if the Fileshare Client accesses a data file c:\accounts\ledger\bought.dat, the Fileshare Client accesses to that file are mapped to the alternate filename.

• Also on DOS or OS/2, if the Fileshare Server's current directory is c:\accounts\ledger, Fileshare Client accesses to the data file bought.dat are mapped to the alternate filename.

The other environments are similar.

Example

DOS:

xm fs /d dbase.ref /f file1.dat /af c:\data\file2.dat

Windows:

fsw /d dbase.ref /f file1.dat /af c:\data\file2.dat

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat



UNIX:

fs -d dbase.ref -f file1.dat -af /data/file2.dat

NetWare:

load fs /d dbase.ref /f file1.dat /af vol2:\data\file2.dat

This example adds entries to the database reference file dbase.ref that specify that file accesses to the file file1.dat are mapped to the alternate filename file2.dat.

Example

DOS:

xm fs /d dbase.ref /f file1.dat /af c:\data\file2.dat
xm fs /d dbase.ref /fs c: /af e:

Windows:

fsw /d dbase.ref /f file1.dat /af c:\data\file2.dat
fsw /d dbase.ref /fs c: /af e:

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat
fs /d dbase.ref /fs c: /af e:


UNIX:

fs -d dbase.ref -f file1.dat -af /1993/data/file2.dat
fs -d dbase.ref -fs /1993 -af /1994

NetWare:

load fs /d dbase.ref /f file1.dat /af vol2:\data\file2.dat
load fs /d dbase.ref /fs vol2: /af vol1:

This example adds entries to the database reference file dbase.ref that specify that all requests made to the data file file1.dat are redirected to the alternate filename.

• On DOS, Windows and OS/2, the alternate filename is changed, using string substitution, to be on drive e:.

• On UNIX, the alternate filename is changed, using string substitution, to be in the directory /1994.

• On NetWare, the alternate filename is changed, using string substitution, to be on vol1.

## 18.11 Data and Key Compression

You can configure the Fileshare Server so that data files are created using data or key compression.

You do not need to change the Fileshare Client configuration in order to use data or key compression on a data file.

### 18.11.1 Data and Key Compression - Fileshare Server

To enable data or key compression for a data file, use the /k option in the database reference file. In conjunction with the /k option, use the d option to specify data compression and the i option to specify key compression.

Values that you specify after the d and i options are the same values that you would specify using the Compiler directives DATACOMPRESS and KEYCOMPRESS. For more information on these Compiler directives, see your Object COBOL User Guide.

Data and key compression specifications in the database reference file only have effect if the Fileshare Server creates the data files. They do not affect existing data files. For existing files, the data and key compression information is retrieved from the data file header. Any settings in your program or the database reference file are ignored.

Example

DOS :

xm fs /d dbase.ref /f file1.dat /k d001
xm fs /d dbase.ref /f file2.dat /k d001i7

Windows:

fsw /d dbase.ref /f file1.dat /k d001
fsw /d dbase.ref /f file2.dat /k d001i7

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref /f file1.dat /k d001
fs /d dbase.ref /f file2.dat /k d001i7


UNIX:

fs -d dbase.ref -f file1.dat -k d001
fs -d dbase.ref -f file2.dat -k d001i7

NetWare:

load fs /d dbase.ref /f file1.dat /k d001
load fs /d dbase.ref /f file2.dat /k d001i7

This example tells the Fileshare Server to create the file file1.dat with data compression and the file file2.dat with both data and key compression.

## 18.12 Database Reference File Maintenance

The database reference file contains information that the Fileshare Server uses to determine which Fileshare features you want to use on which files.

Note: You should only create or change a database reference file using the Database Reference File Maintenance Utility. This is because the file contains information that is stored in a special format.

The Database Reference File Maintenance Utility is invoked using the /d (database) option.

Example

DOS :

xm fs /d dbase.ref [options]

Windows:

fsw /d dbase.ref [options]

Windows NT, Windows 95 and OS/2:

fs /d dbase.ref [options]



UNIX:

fs -d dbase.ref [options]

NetWare:

load fs /d dbase.ref [options]

If the database reference file does not exist, it is created.

Each initiation of the Database Reference File Maintenance Utility adds a record to or removes a record from the database reference file specified.

You can add three types of records to the database reference file:

• A recovery log file record

• A filename record

• A file string record

These are described below.

[/l logfilename]

Specifies the name of the recovery log file. You can only have one of these entries in the database reference file. The following options can be specified for a recovery log file record:

    [/p nnn]

Specifies at what point the Fileshare Server displays a warning when the drive containing the log file is becoming full. The value nnn specifies the percentage disk space remaining, below which the Fileshare Server displays a warning message. The default value is 5, that is, the Fileshare Server displays the warning message when the drive containing the log file contains less than 5% free space.

    [/lc nnn]

Specifies how often the log file is flushed to disk. The value nnn specifies the number of records that are written to the log file before the Fileshare Server calls the operating system to flush the log file buffers to disk. The default value is 100, that is, the Fileshare Server flushes the log file to disk after each set of 100 records are written to it. In addition, the Fileshare Server automatically flushes the log file after every successful COMMIT operation.

The Fileshare Server is unable to flush a log file if the log file is not on the machine where the Fileshare Server is running or if the operating system does not allow Fileshare to force the log file to be flushed. In this situation, the /lc 1 option forces the Fileshare Server to specify writethrough when opening the log file. The log file is then written to disk if the operating system supports writethrough on files.

    [/e]

Erases the record from the database reference file. This is the only way to remove a record once you have created the database reference file.

[/f filename]

Specifies a data file that you want to include in the database reference file. Any file that you specify in the database reference file has logging and, for those file organizations that support it, database sequence numbering, enabled by default. You can explicitly disable logging using the /o l option (see below). You can explicitly disable database sequence numbering using the /o s option (see below.)

The following options can be specified for a filename record:

    [/af alternate-filename]

Specifies an alternate filename for the data file so that whenever the Fileshare Server is asked to access the data file filename, it accesses the alternate-filename data file instead.

    [/ap program-name]

Specifies the virtual file handler that Fileshare Server calls to process all I/O requests on the data file. See the section Virtual File Handler Interface.

The filename definition in the /f entry (corresponding to a /ap entry) can include a trailing wildcard to specify that groups of files are to have their requests passed to the specified virtual file handler.

    [/k DnnnIx]

Specifies that the data file is created with data and key compression. The value of nnn specifies the data compression routine number. The value of x specifies the key compression number. These values are the same as the values for the Compiler directives DATACOMPRESS and KEYCOMPRESS.

 [/o l]

Disables logging for this file.

    [/o s]

Disables database sequence numbering for this file.

    [/o t]

Disables transaction processing for this file. The WITH ROLLBACK clause in a SELECT statement for this data file is ignored. This option in the database reference file overrides any transaction processing specified in your program.

    [/e]

Erases the record from the database reference file. This is the only way to remove a record once the database reference file has been created.

[/fs string1 /af string2]

Specifies that for any data file with a filename starting with string1, string1 is replaced by the character string string2.

The additional option for the file-string entry is:

    [/e]

Erases the record from the database reference file. This is the only way to remove a record once the database reference file has been created.

Example

This example shows you how to create and add entries to a database reference file called dbase.ref on DOS, OS/2, Windows 95 and Windows NT. On Windows 3.1, substitute fsw for fs. On UNIX, use a hyphen (-) character in place of the slash (/) character, and UNIX format filenames.

fs /d dbase.ref /l \log\log.dat /p 10 /lc 200
fs /d dbase.ref /f \accounts\nomlgr.dat /k d001i7
fs /d dbase.ref /f \accounts\salesday.dat /o tl
fs /d dbase.ref /f \ref\clients.dat /af \oldref\oldclnts.dat /o s
fs /d dbase.ref /f \accounts\saleslgr.dat
fs /d dbase.ref /f \orders\week10.dat
fs /d dbase.ref /fs c:\accounts\ /af c:\lastyear\accounts\

where:

Command 1:

fs /d dbase.ref /l \log\log.dat /p 10 /lc 200

Specifies the log file as log.dat in the directory log. Any data files that are specified in this database reference file have all updates recorded in this log file, unless logging is explicitly disabled for a data file. The /p option specifies that the Fileshare Server displays a warning message when less than 10 percent of the disk space remains free on the drive where the log file resides. The /lc option specifies that the Fileshare Server flushes the log file to disk after every 200 records are written to it.

Command 2:

fs /d dbase.ref /f \accounts\nomlgr.dat /k d001i7

Specifies that the data file nomlgr.dat in the directory accounts has data compression and key compression activated if it is created by the Fileshare Server.

The d001 option specifies the data compression routine you want to use is the same as if you compiled your program with the DATACOMPRESS"1" directive. The i7 option specifies the key compression to use is the same as if you compiled your program with the KEYCOMPRESS"7" directive.

This overrides any data or key compression specified in the program.

Command 3:

fs /d dbase.ref /f \accounts\salesday.dat /o tl

Specifies that any transaction processing specified in your program for the data file salesday.dat in the directory accounts is ignored. Also, logging is disabled for this file.

Command 4:

fs /d dbase.ref /f \ref\clients.dat
/af \oldref\oldclnts.dat /o s

Specifies that all I/O requests for the data file clients.dat in the directory ref are redirected to the data file oldclnts.dat in the directory oldref. In addition, database sequence numbering is disabled for this file.

Command 5:

fs /d dbase.ref /f \accounts\saleslgr.dat

Enables logging and database sequence numbering for the data file saleslgr.dat in the directory accounts. By default, logging and database sequence numbering are enabled for every data file listed in the database reference file.

Command 6:

fs /d dbase.ref /f \orders\week10.dat

Enables logging and database sequence numbering for the data file week10.dat in the directory orders. By default, logging and database sequence numbering are enabled for every data file listed in the database reference file.

Command 7:

fs /d dbase.ref /fs c:\accounts\ /af c:\lastyear\accounts\

Specifies that the character string c:\accounts\ at the front of any filename is replaced by the character string c:\lastyear\accounts\. Note that the string specified by the /fs option is not expanded relative to the Fileshare Server's current directory.

## 18.13 Fileshare Security

Fileshare provides security features which enable you to restrict access to a Fileshare Server. You can also restrict access to specific data files under the control of a Fileshare Server.

These restrictions are implemented via:

• The Logon Validation module

• The File Access Validation module

If you invoke the Fileshare Server with the Password System enabled, all Fileshare Clients must supply a valid user-ID and password before they can connect to the Fileshare Server. By default, the Fileshare Password System is not enabled when you invoke the Fileshare Server.

If you want to use the Fileshare Password System you must code your program to pass a user-ID and password to FHRedir and you must create a password file on the Fileshare Server machine which contains the user-ID and password that your program will use.

Then, to enable the Fileshare Password System, you must use the /pf option to specify the name of the password file to the Fileshare Server.

With the Fileshare Password System enabled, the sequence of steps that your program and Fileshare follow (see Figure 18-3) is:

1. Your program registers its user-ID and password with the Fileshare Client by calling the FHRedir password module (FHRdrPwd).

2. Your program performs the first I/O operation.

3. FHRedir obtains the user-ID and password registered in step 1 by calling the FHRedir password module (FHRdrPwd).

4. FHRedir passes the user-ID and password to the Fileshare Server.

5. The Fileshare Server validates the user-ID and password using the password file.

6. If the Fileshare Server allows the logon, a connection is established between the Fileshare Client and the Fileshare Server. If the Fileshare Server does not allow logon, it returns a file status of 9/037 ("access denied") to the Fileshare Client.

#### 18.13.1.1 Fileshare Security - Fileshare Client

When Fileshare security is active, your program must supply a user-ID and a password before the first I/O operation is performed.

Even if you have not activated security, your program can still supply the Fileshare Client with a user-ID and password. This enables your program to run unchanged on Fileshare whether or not security is activated. It also enables Fsview to display the user name of Fileshare Clients - see the Chapter Fsview for more details.

To register a user-ID and password, your program must call the module FHRdrPwd as follows:

call "fhrdrpwd" using function-code,
user-ID,
end-call

where the parameters are:

01 function-code pic x comp-x.
01 user-ID       pic x(20).
01 user-password pic x(20).

The function-code to register a user-ID and password is 1.

Example

This example shows how to register a user-ID and password.

working-storage section.

01 function-code pic x comp-x.
01 user-name     pic x(20).
...
procedure division.
...
move 1          to function-code
move "UserID"   to user-name
call "fhrdrpwd" using function-code,
user-name,
end-call
...
open output testfile
...

You can substitute the FHRdrPwd module supplied with the Fileshare System with your own. This enables you to retrieve the user-ID and password from somewhere other than the application program. See Writing Your Own FHRdrPwd Module for details.

#### 18.13.1.2 Fileshare Security - Fileshare Server

By default, the Fileshare Password System is not active when you invoke the Fileshare Server. If you want password security activated, use the /pf (Password File) option in the Fileshare Server configuration file.

Example

DOS, Windows, OS/2 and Netware:

/pf password.fil
/s server1


UNIX:

-pf password.fil
-s server1

This example specifies that for the Fileshare Server, server1, Fileshare Password Security is enabled and the password file is password.fil. The Fileshare Server uses this file to determine whether a Fileshare Client is allowed to connect to this Fileshare Server.

#### 18.13.1.3 Writing Your Own FHRdrPwd Module

To register a user-ID and password, your program must call the module FHRdrPwd (the FHRedir Password Module). If you do not want to change your program to include this call, you can replace the supplied FHRdrPwd module with one that obtains the user-ID and password using a different method (for example, via a screen prompt). Your new module must still conform to the FHRdrPwd interface, that is:

when function-code = 1:

Register the supplied user-ID and password.

when function-code = 0:

Return the user-ID and password. The FHRedir module uses this call to obtain the user-ID and password when it is about to connect to the Fileshare Server.

DOS, Windows and OS/2:
Compile the FHRdrPwd module to .gnt format and put it in the utils.lbr file, replacing the one supplied with this COBOL system. See your Object COBOL User Guide for more information on changing library contents.

Create your own fhrdrpwd.obj module and link it into any application executable as needed. See the section Linking Fileshare Client Applications.

UNIX :
Compile the FHRdrPwd module to .gnt format and put it in the directory specified by the COBDIR environment variable, replacing the one supplied with this COBOL system.

Create your own fhrdrpwd.o module and link it into any application executable as needed. See the section Linking Fileshare Client Applications.

### 18.13.2 Logon Validation Module

If you have not activated the Fileshare Password System, the Fileshare Server validates logon requests by calling the Fileshare Security Logon validation module (FSSecLog).

The FSSecLog module supplied with Fileshare allows any Fileshare Client to logon to a Fileshare Server. If you need to restrict the Fileshare Clients that can logon to a Fileshare Server, you must provide your own alternative, FSSecLog module for the Fileshare Server to call.

For example, your own module can enable integration with the native operating system security, if this is needed.

The sequence of steps that your program and Fileshare follow (see Figure 18-4) is:

2. Your program performs the first I/O operation.

3. FHRedir obtains the user-ID and password registered in step 1 by calling its FHRedir password module (FHRdrPwd).

4. FHRedir passes the user-ID and password to the Fileshare Server.

5. The Fileshare Server calls the FSSecLog module passing the user-ID and password.

6. If the FSSecLog module allows the logon, a connection is established between the Fileshare Client and the Fileshare Server. If the FSSecLog module does not allow logon, a status 9/037 "access denied" is returned to the Fileshare Client.

Figure 18-4: Logon Validation Module

#### 18.13.2.1 Writing Your Own FSSecLog Module

To validate a logon request from a Fileshare Client, the Fileshare Server calls the module FSSecLog (the Fileshare Security at Logon Validation module) to validate the user-ID and password. You can replace FSSecLog with your own module in order to use your own criteria for validating the logon. Your new module must comply with FSSecLog interface described below.

##### Syntax:
call "fsseclog" using user-ID
return-status
##### Parameters:

 user-ID password return-status pic x(20). pic x(20). pic x comp-x.

##### On entry:

 user-ID The Fileshare Client's user-ID. password The Fileshare Client's password.

##### On exit:

 user-ID Unchanged password Unchanged return-status Set to 0 if the Fileshare Client is allowed to log onto the Fileshare Server. Any other status indicates the Fileshare Client is not allowed to log on and an error is returned to the Fileshare Client.

DOS, Windows and OS/2:
Compile the FSSecLog module to .gnt format and replace the fsseclog.gnt file in the Fileshare Library fs.lbr. See your Object COBOL User Guide for information on updating library modules.

UNIX:
Link the FSSecLog module into the Fileshare Server using the build script supplied. See the section Fileshare Server Rebuild Script for information on how to rebuild the Fileshare Server.

### 18.13.3 File Access Validation Module

Whenever a Fileshare Server receives an open request on a file from a Fileshare Client that does not currently have that file open, the Fileshare Server calls the Fileshare Security at Open validation module (FSSecOpn).

The FSSecOpn module supplied with Fileshare allows any Fileshare Client to access a data file. If you need to restrict access to specific files, you must provide your own, alternative, FSSecOpn module for the Fileshare Server to call.

If the FSSecOpn module allows the file access, the operation is allowed to complete. If the module does not allow the file access, a file status of 9/037 "access denied" is returned to the Fileshare Client and the operation is not allowed to complete.

Note: This file access security check is entirely independent of the Fileshare Password System and the User Supplied Logon Validation Module.

1. Your program registers its user-ID and password with the FHRedir Password module. This information is used when the Fileshare Client first logs onto the Fileshare Server.

2. Whenever your program subsequently performs an I/O operation on a file that it does not have open (such as an Open or Delete file operation), the Fileshare Server calls the FSSecOpn module.

#### 18.13.3.1 Writing Your Own FSSecOpn Module

To validate an open request from a Fileshare Client, the Fileshare Server calls the module FSSecOpn (the Fileshare Security at Open Validation module).

You can replace the supplied FSSecOpn module with one of your own in order to use your own criteria for validating the open request. Your new module must comply with the FSSecOpn interface described below.

##### Syntax:
call "fssecopn" using filename
filename-length
operation-code
user-ID
return-status

##### Parameters:

 filename pic x(n). filename-length pic x(2) comp-x. operation-code pic x(2) comp-x. user-ID pic x(20). return-status pic x comp-x.

##### On entry:

 filename The name of the data file that the Fileshare Client wants to open. filename-length The length of filename. operation-code The operation code specifying the I/O operation. These codes are those used by the Callable File Handler. See the chapter Callable File Handler for details. user-ID The user-ID of the Fileshare Client making the open request.

##### On exit:

 return-status Set to 0 if the open request is allowed. Any other status indicates that the Fileshare Client is not allowed to open the data file and an error status is returned.

DOS, Windows and OS/2:
ON DOS, Windows and OS/2, compile the FSSecOpn module to .gnt format and replace the fssecopn.gnt file supplied in the Fileshare Library fs.lbr. See your Object COBOL USer Guide for information on updating library modules.

UNIX:
On UNIX, link the FSSecOpn module into the Fileshare Server using the build script supplied. See the section Fileshare Server Rebuild Script for information on how to rebuild the Fileshare Server.

The password file contains details of user-IDs and passwords that the Fileshare Server uses when Fileshare Password Security is enabled. Because the information in the password file is encrypted for security reasons, you can only add records to, and remove records from the password file using the Password File Maintenance Utility.

Example

DOS :

xm fs /pf pass.dat [options]

Windows:

fsw /pf pass.dat [options]

Windows NT, Windows 95 and OS/2:

fs /pf pass.dat [options]



UNIX:

fs -pf pass.dat [options]

NetWare:

load fs /pf pass.dat [options]

This example invokes password file maintenance and appends the specified options to the password file pass.dat. If this file does not exist, it is created.

The following options are available:

/u user-ID /pw password

Adds the specified user-ID and password to the password file. Both user-ID and password are case sensitive and can be up to 20 characters in length.

[/e]

Erases the record from the password file. This is the only way to remove a record once the password file has been created.

Example

DOS :

xm fs /pf pass.dat /u pkel /pw fishwife

Windows:

fsw /pf pass.dat /u pkel /pw fishwife

Windows NT and OS/2:

fs /pf pass.dat /u pkel /pw fishwife


UNIX:

fs -pf pass.dat -u pkel -pw fishwife

NetWare:

load fs /pf pass.dat /u pkel /pw fishwife

### 18.14.1 Supervisor Mode (FSVIEW)

In order to use the password-restricted functions of the Fileshare Server Monitor Utility (see the chapter Fsview for details), a supervisor password must be defined.

To define a supervisor password, an entry must be made in the password file using the reserved user-ID, FSVIEW. Note that the user-ID FSVIEW must be entered in upper case.

If you are not using Fileshare Password Security, you can create a password file that contains a single entry - the FSVIEW user-ID. This defines a supervisor password without enabling Fileshare Password Security.

Example

The following example defines a supervisor password of "abracadabra" in the password file password.fil. If the file does not exist, it will be created.

DOS:

xm fs /pf password.fil /u FSVIEW /pw abracadabra

Windows:

fsw /pf password.fil /u FSVIEW /pw abracadabra

Windows NT, Windows 95 and OS/2:

fs /pf password.fil /u FSVIEW /pw abracadabra



UNIX:

fs -pf password.fil -u FSVIEW -pw abracadabra

NetWare:

load fs /pf password.fil /u FSVIEW /pw abracadabra

Once you have defined a supervisor password, you must specify the password file, either in the Fileshare Server configuration file, or on the command line when the Fileshare Server is started.

Note: If FSVIEW is the only entry in the password file, the Fileshare Server displays a message indicating that Fileshare Password Security is disabled, even though a password file has been specified.

## 18.15 Monitoring Fileshare

When the Fileshare Server is active, you can toggle the trace option on and off using the F2 key. If the trace option is on, the Fileshare Server displays the file access requests on the console as they happen. Each line of trace provides:

• Input:

• The user-ID assigned, in the order that the Fileshare Clients logged onto the Fileshare Server.

• The operation code, indicating the I/O operation requested (see the chapter Callable File Handler for the meaning of operation codes).

• The name of the file being accessed.

• Output:

• The status returned to the Fileshare Client, indicating the result of the operation.

Note: The trace option can degrade performance. You should only use it as a diagnostic aid in problem investigation.

You can activate the trace option when the Fileshare Server is started using the /tr f option . This causes the trace to be written to the file fsscreen.lst, as well as being displayed on the screen. Note, however, that this will severely impact Fileshare Server performance if tracing is switched on. If, however, tracing is switched off, only information messages are written to the screen and to the file. This is a useful method of keeping a permanent record of Fileshare messages on disk.

If you are using Fileshare in Single User Mode (see the section Single User Mode), the trace display together with all other output normally displayed on the Fileshare Server console screen is written to the file fsscreen.lst in the Fileshare Server's current directory.

The Fileshare Monitor Utility (FSView) provides a more sophisticated method of viewing the Fileshare System. The information displayed includes the number of open files and the number of Fileshare Clients logged onto the Fileshare Server. See the chapter FSView for more information.

## 18.16 Single User Mode

You can configure Fileshare to run in single user mode. All network communication is bypassed and the Fileshare Client makes direct calls to the Fileshare Server module. The Fileshare Server does not run as a separate process in this mode of operation.

This is useful when:

• You want to develop Fileshare applications without using a network or a multi-tasking operating system.

• A single user application makes use of one of Fileshare's advanced features, such as transaction processing.

To run Fileshare in single user mode, set the FSCOMMS environment variable to $local. Note: You cannot statically link an application that uses Fileshare in single user mode. The application must either be run in .int or .gnt form or be linked to the dynamic COBOL run-time system. NetWare: You cannot run Fileshare in single user mode using NetWare. UNIX : On UNIX, to run Fileshare in single user mode, you must create an executable with the Fileshare object modules included. Do this by using the Fileshare rebuild script file, mkfs2 (see the section Fileshare Server Rebuild Script) which is supplied in the$COBDIR/src/fs directory. To make sure that the resulting executable is a derivative of your own Fileshare Client application program, run the script file:

mkfs2 -e myprog -o myprog myprog.o

where myprog is the name of your Fileshare Client application program.

This command builds you an executable called myprog with the module myprog as the entry point on execution and includes all of the Fileshare modules necessary for your application to make use of Fileshare in single user mode.

Example

DOS, Windows and OS/2:

set FSCOMMS=$local  UNIX: FSCOMMS="\$local"
export FSCOMMS

Even when you are running in single user mode, you must still tell the Fileshare Client which Fileshare Server to use, either by specifying the Fileshare Server name as part of the filename in your program or by using a Fileshare Client configuration file.

The Fileshare Server is configured in the normal way using a Fileshare Server configuration file. At the minimum, you must define a Fileshare Server name in this file.

Note: The Fileshare Server does not have control over the screen when it is running in single user mode. It directs all screen output to the file fsscreen.lst in the current Fileshare Client directory. If your program fails, check this file for messages.

## 18.17 Fileshare Communications

The Fileshare Client(s) and Fileshare Server(s) communicate using the Common Communications Interface (CCI) which is described in full in your Programmer's Guide to Communications.

### 18.17.1 Overview

DOS, Windows and OS/2:
On DOS, Windows and OS/2, Fileshare defaults to the NETBIOS (CCINETB) protocol. To use CCINETB, you must have network services running on the Fileshare Client and Fileshare Server machine(s).

Windows NT and Windows 95:
The only CCI protocol currently available under Windows NT and Windows 95 is CCITCP so you must specify this protocol for any Fileshare Client application that needs to communicate with a Fileshare Server running on Windows NT or Windows 95.

UNIX:
On UNIX, Fileshare defaults to the TCP/IP (CCITCP) protocol.

When using CCITCP, the Fileshare Client and the Fileshare Server must have access to a registration process called ccitcp2 . This process can be running on any machine that the Fileshare Client and Fileshare Server can contact. The ccitcp2 process sets up the initial connection between the Fileshare Client and Fileshare Server. You must set the environment variable CCITCP2 to the host name of the machine where the ccitcp2 process is running. If you do not set the environment variable, CCITCP assumes that ccitcp2 is running on the local machine. The Fileshare Client and the Fileshare Server must register with the same ccitcp2 process in order to communicate with each other.

For example, consider the situation where the Fileshare Server and the Fileshare Client are running on different machines and the ccitcp2 process is running on the same machine as the Fileshare Server. The environment variable CCITCP2 does not have to be set on the machine running the Fileshare Server. However, it has to be set on the machine running the Fileshare Client to the TCP/IP host name of the machine where the Fileshare Server (and ccitcp2) process are running.

UNIX:
When running the Fileshare Server and Fileshare Client on the same UNIX machine, use the Named Pipes protocol for UNIX (CCINAMPU) as this provides significantly better performance than CCITCP.

NetWare:
The only CCI protocol available for NetWare is CCIIPX.

A Fileshare Server can use several communication protocols concurrently enabling it to communicate with a number of Fileshare Clients that do not all use the same protocol.

When you invoke a Fileshare Server, you need to specify the communications protocols it supports, using the /cm option in the Fileshare configuration file.

The following table shows how portable your applications can be. For example, using the CCITCP protocol you can have a Fileshare Server running on UNIX receiving I/O requests from copies of an application running on DOS, Windows, OS/2 and UNIX machines on the same network.

 Protocol Windows Windows NT/95 DOS OS/2 UNIX NLM CCINETB x x x CCINAMP x CCITCP x x x x x CCINAMPU x CCIIPX x x x x

### 18.17.2 CCI Trace

CCI Trace enables all the messages sent by CCI to be logged to a file. This can help in tracking down and debugging problems related to communications. To activate CCI Trace add:

/tr cci

to the Fileshare Server configuration file.

To prevent unauthorized access to the CCI Trace information, you are prompted for the supervisor password when you invoke a Fileshare Server with CCI Trace enabled. (The supervisor password is that specified for the user-ID FSVIEW in the password file so you must specify the appropriate password file when you start the Fileshare Server.) If the password is accepted, CCI Trace is enabled and a second prompt asks if CCI Trace should be activated immediately or not.

CCI Trace can be toggled on and off using the F3 key.

The CCI trace options are specified via the CCITRACE environment variable. See your Programmer's Guide to Communications for details.

### 18.17.3 Synchronous Communications Mode

OS/2:
On OS/2 systems, the Fileshare Server can be configured with the /sc option to specify that it is to run in synchronous communications mode. This can significantly improve the performance of the Fileshare Server's servicing of network requests in certain circumstances.

Normally, the Fileshare Server uses asynchronous communications, so that network requests can be processed by CCI at the same time as the Fileshare Server is performing its own processing. This means that in environments where many clients are sending many requests at the same time to the same Filehare Server, overall system performance will be quicker because the network requests are processed at the same time as the Fileshare Server is processing other clients' I/O requests.

In synchronous communications mode, the Fileshare Server synchronously waits for a network request, processes the I/O request received, and then sends the result back synchronously before then posting a new synchronous network request to wait for the next Fileshare Client's message.

In situations where a single Fileshare Client application does large amounts of continuous I/O through the Fileshare Server, you can obtain significant performance improvements by running the Fileshare Server in synchronous communications mode. In addition, performance is improved when you have a small number of users running an application which does updates in small groups (such as transactions) which will not often conflict with each other.

However, if you have many users running applications in which several users are trying to make large amounts of continuous I/O requests to the Fileshare Server at the same time, performance can be degraded if the Fileshare Server is run in synchronous communications mode.

Notes:

• Synchronous communications mode does not significantly affect the performance of Fileshare Servers running in UNIX environments. It can really only provide significant performance gains when used with the CCINETB protocol on OS/2.

• The utilization figure reported by the FSView utility when it is displaying information about a Fileshare Server which is running in synchronous communications mode may be misleading since this figure is related to how many asynchronous communications requests are occurring.

There are some restrictions to the Fileshare Server's operation when started in synchronous communications mode:

• The Fileshare Server can only service requests from clients using the same (single) CCI protocol. If more than one CCI protocol is specified when starting the Fileshare Server, the /sc option is ignored.

• Part of the performance improvements gained are due to the fact that the Fileshare Server does not check for keyboard input very often when in synchronous communications mode. The Fileshare Server only reads the keyboard very occasionally while it is processing client requests and so does not actually respond at all to keystrokes if it is idle. This means that it may not be possible to close down the Fileshare Server using the normal method of pressing the ESC key sequence. Instead you will need to use the FSView utility's supervisor functions remotely or write a program which calls FSMgr (Fileshare Manager). See the chapter FSView for details.

The Fileshare Server will not start in synchronous communications mode unless you start it with a password file which contains an FSVIEW supervisor password. If an FSVIEW supervisor password is the only entry in the password file, Fileshare security is not activated. See the section Password File Maintenance for more information.

As an alternative to using FSView or writing a program that calls FSMgr, you can run the supplied utility fsclose as follows:

Example

DOS:

xm run fsclose

Windows:

runw fsclose

Windows NT and OS/2:

run fsclose


UNIX:

cobrun fsclose

It calls Fileshare Manager itself and prompts you for the Fileshare Server name you want to close down, the CCI protocol to use and the FSView supervisor password.

There is no method of toggling Fileshare's trace display remotely. However, pressing the F2 key in the usual manner works when Fileshare is running in synchronous communications mode, although there may be some delay before the Fileshare Server responds to the keystroke.

Example

The following Fileshare Server configuration file entries configure the Fileshare Server to use the synchronous communications mode. The Fileshare Server name is server-1, the password file (containing an FSView user-ID) is called passwd.dat and the communications protocol is CCINETB.

/s server-1
/pf passwd.dat
/cm ccinetb
/sc 

## 18.18 Linking Fileshare Client Applications

To link a Fileshare Client program to create an executable, you need to include the Fileshare Client object modules. These are described below, together with details of when you need to include them.

DOS, Windows and OS/2:
For DOS, Windows, Windows NT, Windows 95 and OS/2 applications, the following modules are provided:

UNIX:
On UNIX, all the Fileshare Client modules are automatically available so you do not need to link any extra objects when creating an executable version of your application. However, if you want to create a stand-alone static executable, you need to include the objects fhrdrpwd.o and fhxscomp.o.

### 18.18.1 Statically Linking Fileshare Client Applications

DOS:
Programs that access data files through the Fileshare Client have their access requests processed via the File Handler Redirector module (FHRedir). The CCI modules are automatically loaded at run time as the COBOL system needs them.

However, if you want to statically link your programs with FHRedir using LCOBOL to run on DOS under XM, you need to link in the appropriate CCI module, CCIxxxD.lib where xxx is the CCI protocol you are using, for example, NETB. To avoid linker errors, the calls that FHRedir makes to other CCI protocols must be resolved at link time using the module fhrdrcci.cbl. This module includes entry points for all of the CCI modules supported by Fileshare. You must remove the entry from fhrdrcci.cbl that corresponds to the CCI protocol you want to use. You must also link the DOS XM version of FHRedir called fhredird.obj.

As an example, if you are linking ccinetb.lib into your program, you need to remove the entry point referring to CCINETB from the fhrdrcci.cbl module before compiling and linking it into your program.

UNIX:
For UNIX applications, the directory $COBDIR/src/fs contains the following objects for linking into your executable, if you are making use of certain Fileshare Client functionality.  fhrdrpwd.o The FHRedir password module. You need this module if your application makes use of Fileshare Security. (See the section Fileshare Security.) fhxscomp.o This module is provided for backward compatibility for applications that made use of the /xs option. ## 18.19 Byte-stream I/O Calls Fileshare supports some of the byte-stream I/O routines that are available with this COBOL system. Most of the routines use the same parameters and have the same effect as the corresponding COBOL system call, but access remote files via Fileshare. See the chapters Directory Handling and Byte-stream File Handling for syntax details. The only change needed to your program is to call the routine starting with FS_ instead of CBL_. The only routine that does not have exactly the same call interface as its corresponding CBL_ routine is FS_LOCATE_FILE. Fileshare supports the following byte-stream I/O routines: • FS_CHECK_FILE_EXIST • FS_CLOSE_FILE • FS_CREATE_FILE • FS_COPY_FILE • FS_DELETE_FILE • FS_JOIN_FILENAME (see below) • FS_LOCATE_FILE (see below) • FS_OPEN_FILE • FS_READ_FILE • FS_RENAME_FILE • FS_SPLIT_FILENAME (see below) • FS_WRITE_FILE You can use these routines to access files on remote Fileshare servers, as well as local files. Configure the Fileshare Client in the normal manner to define which files are local and which are remote. Notes: • Do not use byte-stream I/O and COBOL I/O on the same file. • If you want to share files between multiple Fileshare Clients you must access the files using normal COBOL I/O verbs. ### 18.19.1 FS_LOCATE_FILE The functionality provided by FS_LOCATE_FILE is the same as CBL_LOCATE_FILE except: • You cannot use FS_LOCATE_FILE to search for files in libraries on remote Fileshare Servers. • You can use CBL_LOCATE_FILE to search for files along each path specified in an environment variable. You can then use the returned actual-file-spec as the filename when opening the file. If you have specified a $$server-name prefix in user-file-spec, actual-file-spec must contain the same$$server-name prefix for an OPEN using actual-file-spec to be re-directed automatically. By default, Fileshare only returns the filename in actual-file-spec to your program. To return the $$server-name in actual-file-spec, set the most significant bit of user-mode before making the call to FS_LOCATE_FILE. • When a remote file is found, using an environment variable containing many paths, FS_LOCATE_FILE returns actual-file-spec including the full directory path where the file is located. ### 18.19.2 FS_SPLIT_FILENAME and FS_JOIN_FILENAME The functionality provided by FS_SPLIT_FILENAME and FS_JOIN_FILENAME is the same as that provided by the corresponding CBL_ routines. In addition, using FS_SPLIT_FILENAME and FS_JOIN_FILENAME you can process filenames that specify Fileshare Server names using the$$server-name prefix at the front of the filename. When processing such filenames, the$$server-name prefix characters are included as part of the pathname. ## 18.20 Performance Considerations Although Fileshare reduces the number of requests made across the network for COBOL I/O, some types of data file access benefit more than others. The following areas effect Fileshare's ability to improve the speed of accessing remote data. • File Organization A single request to an indexed data file can involve many accesses to the physical data file itself such as reading the header and updating the integrity marker. Complex key structures also increase the number of accesses needed to update the index structure in the file. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network. The simpler data file organizations (relative and sequential files) involve a smaller processing overhead. Any speed improvements using Fileshare are therefore more apparent when processing indexed data files. • I/O Request The number of accesses to a data file needed to process a WRITE, DELETE, or REWRITE operation is generally larger than the number needed to process a READ or START operation. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network. Any speed improvements using Fileshare are therefore more apparent when performing WRITE, DELETE, or REWRITE operations. • Concurrent Use of Data Files If your program opens a data file exclusively, the normal COBOL file handling system uses caching. This means that it does not have to check to see if the file has been updated on every I/O operation. The number of requests sent across the network, therefore, is significantly less if the data file is opened exclusively. Fileshare provides a greater improvement in performance, therefore, when a large number of users require concurrent access to data files than when files are opened exclusively. This is because access and caching are controlled by the Fileshare Server and so the additional requests needed when accessing a shared data file via the normal COBOL file handling system are not needed. • File Handler By default, this COBOL system uses different file handlers to process different file organizations. However, Fileshare always uses the same file handler and this can be slower when processing relative and sequential files. As a result, the processing overhead for such files can outweigh the performance advantages gained by the reduced network traffic. These areas make any speed improvements very application specific. In addition, any speed improvements become more pronounced as more Fileshare Clients concurrently access the same data files. UNIX: On UNIX, when running the Fileshare Server and Fileshare Client on the same machine, use the CCINAMPU CCI protocol as it performs better in this situation than the CCITCP protocol. ### 18.20.1 Fileshare Performance on UNIX Fileshare improves performance when remote COBOL applications are concurrently accessing shared data files across a network but it cannot improve peformance when the COBOL data resides on the same machine as the application. In this configuration, there is actually a performance overhead when using Fileshare instead of the standard Callable File Handler. Although UNIX machines can be used as remote data servers, it is not uncommon for the application itself to run on the machine where the data resides. For example, multiple users may log in, across a network, to a machine where they run applications which share the same data. In such a configuration, you will encounter the performance overhead of using Fileshare and performance will, therefore, be slower than using the standard Callable File Handler. See your Release Notes for more details. ## 18.21 Fileshare on UNIX ### 18.21.1 Fileshare Server Rebuild Script You can rebuild the UNIX Fileshare Server executable, enabling you to: • Provide your own security modules (see the section Fileshare Security) • Redirect I/O requests to a program other than the Callable File Handler (see the section Virtual File Handler Interface) In addition, you need to link Fileshare modules to your application program in order to use Fileshare in single user mode (see the section Single User Mode). To rebuild the Fileshare Server on UNIX, run the script file mkfs2 supplied in the$COBDIR/src/fs directory. Before running this script, you must:

• Log on as root

• Ensure that all the files to be linked into the Fileshare Server executable are in the $COBDIR/src/fs directory. To run the script file, enter mkfs2 [filename] ... You can supply more than one module for filename in .cbl, .o, or .c form. All are linked into the new Fileshare Server executable, fs. When running the script file, all object modules that make up the Fileshare Server executable are included in the directory where the script file is located,$COBDIR/src/fs. To replace the security modules supplied with the Fileshare system with your own, put fsseclog.o or fssecopn.o or both into this directory before running the script file.

When the mkfs2 script terminates, a new version of the Fileshare Server is in the \$COBDIR/src/fs directory. Copy this to the directory specified by the COBDIR environment variable so that all system users can access it.

### 18.21.2 Running Fileshare as a Background Process

Because the Fileshare Server uses Adis for its screen displays and keyboard handling, it accumulates a lot of processor time if started as a background process on UNIX. To avoid this, and allow the Fileshare Server to only use its usual amount of processor time while in the background, the Fileshare Server should be configured using the -b option when being run in the background. This disables all Fileshare displays and keyboard reading.

Since Fileshare does not read the keyboard in background mode, you cannot close it down in the normal manner using the ESC key sequence.

Warning: Do not kill the Fileshare process because this results in the corruption of any data files which are open.

Instead, use the Fsview supervisor options or write a program which calls Fileshare Manager (FSMgr). Alternatively, you can run the supplied utility fsclose as follows:

cobrun fsclose

The fsclose utility calls Fileshare Manager itself and prompts you for the name of the Fileshare Server you want to close down, the CCI protocol, and the FSView supervisor password.

Because the only way to shut down the Fileshare Server is remotely, the Fileshare Server must have been configured to use a password file which contains an FSVIEW supervisor id and password. See the section Password File Maintenance and the chapter FSView for details.

The Fileshare Server does not start in background mode unless you start it with a password file which contains an FSVIEW (supervisor) id and password.

In background mode, any messages the Fileshare Server would normally display on the screen are written to the file fsscreen.lst in the Fileshare Server's current directory.

An example configuration file follows. This configuration file specifies that the Fileshare Server name is server-1, the password file (containing an FSVIEW user-ID) is password.fil and the communications protocol to use is CCITCP. The -b option specifies background mode.

-s server-1
-b
-cm ccitcp

The Fileshare Server can now be started in background mode by entering:

fs > server-1.log 2>&1 &

You need to redirect the output from the command because otherwise, on some UNIX systems, output is sent to the terminal after it has been disconnected and, consequently, the entire session is terminated.

### 18.21.3 The NFILES Setting

On UNIX systems, the NFILES setting defines how many separate file descriptors can be used. This can be set for individual accounts and for the system as a whole. You must ensure that NFILES is set sufficiently high for Fileshare which uses file descriptors as follows:

• One file descriptor is used for every file opened on disk. So, two file descriptors are used for each indexed file opened. Note that two users sharing the same file only require the file to be opened once on disk.

• CCITCP uses one file descriptor for every connected Fileshare client.

• CCITCP uses one file descriptor for every outstanding Fileshare request (normally this is a maximum of two).

So, for the user account that the Fileshare session uses, NFILES must be set to accomodate the maximum number of open files and the maximum number of Fileshare clients. In addition, the system setting of NFILES may need to be increased.

## 18.22 Error Handling in Fileshare Applications

Fileshare error messages are listed in the chapter Fileshare Server Messages.

Fileshare can return a number of error codes, in addition to the normal error messages returned by the COBOL system.

Your program should also check for communications errors generated by CCI and errors generated by some of the advanced Fileshare features such as transaction processing.

### 18.22.1 Additional COBOL Run-time Errors

Status Code
Meaning
9/037 Access is denied. In addition to the normal situations where this error occurs, Fileshare generates this error when:

• An invalid user-ID and/or password is passed to a Fileshare Server and Fileshare Password Security is active.
• A Fileshare Client attempts to access a particular data file and access is denied.

9/100 A CLOSE operation is tried on a data file that is participating in an active transaction. See the section Transaction Processing for more information.
9/124 A communications error occurred between the Fileshare Client and the Fileshare Server. You can call fs_status to determine the cause of the error. For details of this call see the section Communications Errors below.
9/125 Caused by one of these conditions:

• A transaction or record lock timed out. (See the section Automatic Record Lock Timeout.)

• The Fileshare Client has been forced to log off from the Fileshare Server due to an FSView supervisor function.

• If using the Callable File Handler interface, an invalid Fileshare session ID was passed on the call to FHRedir. Check that the six bytes of the FCD from offset 79 have not been changed.

• A previous access to this open file returned a 9/124 status, so further operations cannot be made.
9/126 The record size used on the I/O operation is too large to be handled by the Fileshare Server. See the description of the /m option in the Fileshare Server Configuration section.
9/173 When using the virtual file interface, the program-name specified in the database reference file is not found. (See the section Virtual File Handler Interface.)

### 18.22.2 Communications Errors

Error status 9/124 on an I/O operation indicates that a communications error has occurred between the Fileshare Client and the Fileshare Server.

The most common time for error 9/124 to occur is on the very first I/O request that your program makes. It is then the Fileshare Client tries to contact the Fileshare Server. If the Fileshare Client is unable to do this, it returns error 9/124. If you receive this error, examine the configuration of Fileshare and check that:

• The Fileshare Server is started and operational.

• You have specified the correct Fileshare Server name. The name that you specify must exactly match the name specified when the Fileshare Server was started.

• The Fileshare Client and Fileshare Server are configured to use the same CCI communications protocol.

• You have a working network connection between the Fileshare Client and the Fileshare Server and the correct network driver and software is loaded.

Once a successful connection is made and the Fileshare Server is servicing the request from the Fileshare Client, the request is visible if trace is active at the Fileshare Server (See the section Monitoring Fileshare. Any further communications errors are returned to the program as error 9/124. To determine the cause of the error, call the entry point fs_status in the FHRedir module. The format of the call is:

call "fs_status" returning cci-status

where the parameter is defined as:

01 cci-status pic x(2) comp-x.

On return, cci-status contains the CCI error code returned to FHRedir from the CCI module. See your Programmer's Guide to Communciations for the meaning of these codes.

You can make an additional call after error 9/124 to return an extended error message. This message is in the form of a text string that indicates a CCI-specific error as well as some additional information. The format of the call is:

call "fs_commserr" using by reference buffer
by value maxlen
by reference actual-len

where the parameters are defined as:

01 buffer     pic x(n).
01 maxlen     pic x(4) comp-5 value length of buffer.
01 actual-len pic x(4) comp-5.

On return, the buffer contains the extended error message and actual-len contains the length of this message. The additional information in the returned message includes:

• The date and time that the last error 9/124 was returned

• Last return code from the CCI module (a 4 digit number)

• Message code (for FHRedir's internal use, a 2 digit number)

• The CCI error message text

In addition, FHRedir automatically logs communications errors in a local file called fhneterr.log. Each entry in the log file has the same format as the buffer returned from the fs_commserr call.

If you do not have a call to fs_commserr in your application, you can check this file for more detailed information following a 9/124 error.

This log file is not deleted by the Fileshare Client. You can, however, delete this log file if its contents are of no interest.

### 18.22.3 Transaction Processing Errors

The COMMIT and ROLLBACK operations work across many data files. You cannot check the file status of any one data file to see if the COMMIT or ROLLBACK operation was successful. Instead, call the entry point fs_status to determine the status of the COMMIT or ROLLBACK operation.

The format of the call is:

call "fs_status" returning t-status

where the parameter is defined as:

01 t-status pic x(2) comp-x.

A non-zero status indicates that the COMMIT or ROLLBACK operation failed. Due to the complexity of multiple file transactions across networks, Fileshare cannot provide definitive information on transaction processing errors.