PreviousSecurity Fileshare on UNIXNext

Chapter 6: Advanced Operation

This chapter describes the advanced features that are available with Fileshare.

Note: In Mainframe Express, Fileshare is only supported for use by the components of Mainframe Express. Information in this chapter that describes using Fileshare in your own applications is not supported.

6.1 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:

To run Fileshare in single user mode, set the FSCOMMS environment variable to $local, for example:

set FSCOMMS=$local

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

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

6.2.1 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 a filename. This is particularly useful for mapping pathnames.

For example:

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

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

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.


fs /d dbase.ref /f file1.dat /af c:\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.

For example:

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

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 and, in addition, the alternate filename is changed, using string substitution, to be on drive e:.

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

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

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.


fs /d dbase.ref /f file1.dat /k d001
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.

6.4 Virtual File Handler Interface

The Fileshare Server can pass I/O requests to a program specified by you, rather than the Micro Focus File Handler, as long as the program that you specify conforms to the call interface used by the File Handler.

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

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

For example:

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

adds entries to the database reference file, dbase.ref which specify that the Fileshare Server should pass all I/O requests for the data fileuser1.dat to the program myprog.

Your program should be in .obj format and needs to be linked into the main Fileshare module, FS.DLL. See Linking the Fileshare Server for details.

Your program should be compiled to intermediate or generated code, or to a callable shared object, and must be callable from the Fileshare process.

6.5 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:

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

6.6 Fileshare Manager

You can use the Fileshare Manager (fsmgr) to automate some of Fileshare's supervisor mode functions by writing a COBOL program that calls fsmgr. The Fileshare Manager can be called to perform any of the following functions:

Note: Any Fileshare Clients connected to the Fileshare Server when this instruction is issued will be logged off and any files which they had open will be closed.

6.6.1 Call Interface

The fsmgr program is called from a COBOL program as follows:

call "fsmgr" using parameter-block

parameter-block        A group item defined as:
   function-code         pic xx comp-x.
   error-status          pic xx comp-x.
   fileshare-name        pic x(16).
   supervisor-passwd     pic x(20).
   reserved              pic x(24).

On entry:
function-code The fsmgr function required:

1 = backup recovery log file.
2 = close all open data files.
3 = log off all connected clients.
4 = shut down Fileshare.
5 = shut down and re-start Fileshare.

fileshare-name The name of the Fileshare server (this is the name that was used when Fileshare was started).
supervisor-passwd The supervisor password. See Supervisor Mode for more information.
reserved Reserved for future use. Must contain binary zeros.
On exit:
error-status Reflects the success, or failure, of the call. Possible values of error-status are shown below.
0 Function completed successfully.
1 Communications error. A Fileshare server of the name specified in fileshare-name could not be contacted on the network using the specified communications protocol. This error is also returned if a network failure occurs during the execution of the function but after the initial connection was made.

Check that fileshare-name is specified correctly and that Fhredir is configured to use the correct communications protocol.

2 File error during initial connection.

To connect to Fileshare, fsmgr opens a file called fsmgr.ctl. This file should not already exist and fsmgr does not actually create it. If it does exist, this status is returned if there is a subsequent error in closing the file.

3 Invalid password specified in supervisor-password.

Ensure that Fileshare is running with a password file and that the contents of supervisor-password match the supervisor password entry in the password file. Note that Fileshare passwords are case sensitive.

See Supervisor Mode for more information.

4 Invalid value specified in function-code - must be within the range 1 to 5.
5 No Fileshare log file.

You have attempted to backup the log file on a Fileshare server that is running without a recovery log file.

6 Function 2 or 3 could not complete.

While attempting to log off all Fileshare's clients (function 3), it is possible for other clients to log on before the logging off operation completes. For example, fsmgr has to send a logoff client n request four times if there are four clients logged on. If, however, a new client logs on before all four original clients have been logged off, fsmgr retries the logoff client n request in order to log off the new client. It retries 10 times and if new clients are still logging on, it will return error 6. A similar situation can occur during processing of a function 2 (close all data files) if new files are continuously being opened at the same time.

10 Other error.

6.6.2 Fileshare Manager Configuration

Fileshare Manager, like other Fileshare Client applications, accesses a Fileshare server via Fhredir and so needs to be configured to use the correct communications protocol. See the section Client Configuration in the Configuration chapter for more information.

6.6.3 Linking Fileshare Manager Applications

If your program calls fsmgr, you will need to link in the Fileshare manager object file (fsmgr.obj on Windows, fsmgr.o on UNIX) when you create an executable file.

6.7 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. 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:

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.



The functionality provided by FS_LOCATE_FILE is the same as CBL_LOCATE_FILE except:


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

6.8 Running Fileshare as a Windows NT Service

Windows NT:
You can install the Fileshare Server so that it runs as a Windows NT service by entering the following at the command prompt for this Micro Focus product:

fsservice -i

Once installed, you can display the status of the service by entering:

fsservice -v

and you can uninstall Fileshare as an NT service by entering:

fsservice -u

Once Fileshare is installed as an NT service, you can start it as a background process as follows:

  1. Select the Services icon from the Control Panel.

  2. Select Micro Focus Fileshare Service from the list of displayed services.

  3. Press the Start button.

You can stop the Fileshare service as follows:

  1. Select the Services icon from the Control Panel.

  2. Select Micro Focus Fileshare Service from the list of displayed services.

  3. Press the Stop button.


You can specify that the Fileshare Server should be started up automatically when Windows NT boots up as follows:

  1. Select the Services icon from the Control Panel.

  2. Double-click on Micro Focus Fileshare Service.

  3. Select Automatic as the Startup Type.

Note: If you have specified that the Fileshare Service is to be started automatically when Windows NT boots up and you have logging switched on for any data files, it is recommended that you specify a Fileshare backup directory in your database reference file. See the section Automatic Database Backup and Rollforward Recovery in the Database Integrity chapter for more information.

Before starting Fileshare, you need to create a Fileshare Server configuration file so that you can specify Fileshare Server options. For more details on Fileshare Server options, see the section Server Configuration in the Configuration chapter. The Fileshare Service will inherit the Windows system directory (for example, c:\winnt\system32) as its current directory and so you should place your Fileshare Server configuration file in this directory. If you want Fileshare to use a different working directory, you can specify this using the /wd option as the first entry in your configuration file. On start-up, Fileshare will change to the working directory that you have specified and access any files (for example, a database reference file) that are not fully qualified as being relative to this working directory.

Because Fileshare runs as a background process, any messages it generates are written to the file fsscreen.lst in the current working directory. Check the contents of this file to diagnose any problems.

Example Configuration File

The following is an example of a Fileshare Server configuration file:

/wd d:\fsdir
/s server1
/d dbase.ref

where the first line specifies the directory fsdir on the drive d: as the Fileshare Server's current directory. Any data files without fully qualified pathnames will be searched for relative to this directory. The second line specifies that the Fileshare Server is to register its name on the network as server1 and the third line specifies that Fileshare is to use the database reference file dbase.ref. Because this name is not fully qualified it will be searched for in Fileshare's current directory, that is, d:\fsdir.

6.9 Linking the Fileshare Server on Windows

If you want to use the Virtual File Handler Interface or your own security modules on Windows, you need to recreate the file fs.dll. You can do this by entering a command line similar to the following:

CBLLINK -ofs.dll -d -RE,2.0 -Mfscmd fscmd.obj fsserver.obj
   fhxscomp.obj fsseclog.obj fsinstpw.obj fsinst.obj fsrcvr.obj
   fspthnam.obj fssecopn.obj fsossec.obj cbldc001.obj _codeset.obj

Alter this command line to suit your own purposes by adding object modules or substituting security modules as necessary.

Alternatively, if you are running Fileshare as a Windows NT Service, you will need to relink the fsservice.exe module using a command similar to the following:

cbllink -ofsservice.exe -Rm,+2.0 fssrvice.obj  CblNTService_Handler.obj
   CblNTService_SetStatus.obj CblNTService_ServiceRoutine.obj 
   servserv.obj fscmd.obj fsserver.obj fhxscomp.obj fsseclog.obj 
   fsinstpw.obj fsinst.obj fsrcvr.obj fspthnam.obj fssecopn.obj
   fsossec.obj cbldc001.obj _codeset.obj mfini.obj

You will then need to uninstall the old version of fsservice and install this new version.

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

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.

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.

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

6.11 File Striping with Fileshare

File striping was introduced in previous products as an interim solution to overcome limitations on the maximum allowed file size. It enables you to specify that a single file is stored in multiple physical files (or stripes) on disk.

Since this product by default supports very large sequential, relative and IDXFORMAT"8" indexed files, striping is not necessary on operating systems that support files greater than 2 Gbytes in size. Because of the complications involved with configuring striping together with Fileshare (these issues are discussed below), we recommend that you keep your large files non-striped.

If your operating system does not support large files, you should read the following information that pertains to configuring striped files under Fileshare control.

You should also review the File Handler Configuration chapter in the online book, File Handling.

Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousSecurity Fileshare on UNIXNext