Chapter 2: Standard Operation
This chapter 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 chapter, you should be able to configure any COBOL program to use Fileshare.
Note: In Mainframe Express, Fileshare is only supported for use by the components of Mainframe Express. Therefore some of the following information about writing applications that use Fileshare is not relevant to Mainframe Express users.
Fileshare Client
To enable your COBOL program to use Fileshare at the Fileshare Client machine, you need to do two things:
- Force your program to pass file I/O requests to the File Handling Redirector module (FHR), 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.
You might also need to configure CCI for the communications protocol you have chosen. For more details, please refer to:
- Your Net Express or Server Express online book Configuring CCI
- Your Mainframe Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, click CCI, configuring.)
Using the File Handling Redirector Module
There are three ways of forcing your program to pass file I/O requests to the File Handling Redirector module:
- If your program uses COBOL I/O syntax, you must compile it with the CALLFH"FHREDIR" Compiler directive so that the File Handling Redirector module processes any I/O requests that your program makes.
- If your program uses the Micro Focus file handler API, you need to change the program
so that it calls "FHREDIR" and not "EXTFH". (The call interface to the File Handling
Redirector module is exactly the same as the call interface to the Callable File Handler
(ExtFH).)
For example:
call "FHREDIR" using operation-code, fcd
- Set the File Handler configuration option FHREDIR=ON.
Note: Take care with this option. If it is in effect when Fileshare itself is running, Fileshare will attempt to redirect file I/O requests to itself, and this will cause a timeout failure.
When you have performed any of these actions, you have created a Fileshare Client but your program works in exactly the same way as it did before because the File Handling Redirector module simply forwards I/O requests to a local copy of the Micro Focus File Handler.
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, if one has been set up. Alternatively, you can specify the location of the Fileshare Client configuration file using the FHREDIR environment variable, for example:
Windows:
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:
set 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 Micro Focus 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.
In order to redirect I/O operations successfully, the File Handling Redirector module needs to know:
- Which Fileshare Server to communicate with
- Which communications protocol to use when contacting the server
Specifying the Fileshare Server
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.
This requires changes to your code.
- In a Fileshare Client configuration file.
This does not require changes to your code.
These methods are listed below.
As a Filename
Specifying the server as a filename in your program overrides any configuration file settings.
Windows:
select account-file assign to "$$server1\c:\accounts\main.dat"
This SELECT statement tells the File Handling Redirector module 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. The File Handling Redirector module 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 SELECT statement tells the File Handling Redirector module to direct requests for this data file to the Fileshare Server named server1. The data file is main.dat in the directory accounts on the Fileshare Server machine. The File Handling Redirector module 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:
Windows:
/s server2
UNIX:
-s server2
tells the Fileshare Client to use the default Fileshare Server named server2. The File Handling Redirector module redirects all file I/O to this server unless you:
- Specifically define a file as a local file. See the section Client Configuration in the chapter Configuration for further information.
- Specify that a file is on a different Fileshare Server, using the Fileshare Client configuration file. See the section Client Configuration in the chapter Configuration for further information
- Specify a different Fileshare Server as part of the filename in your program (see above)
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 File Handling Redirector module on the first OPEN request passed by your program
Specifying the Communications Protocol
A Fileshare Client communicates with a Fileshare Server using the Common Communications Interface (CCI).
CCI supports 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.
The default protocol is TCP/IP (CCITCP).
If you require a communications protocol other than the default, you must specify it in the Fileshare Client configuration file.
To specify an alternative default CCI protocol, use the /cm option:
-
/cm cciipx
This entry makes the Novell IPX protocol (CCIIPX) 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 ccitcp /cm cciipx /s server1
These configuration file entries tell the Fileshare Client to use the TCP/IP protocol (CCITCP) as the default and the Novell IPX protocol (CCIIPX) for communicating with the server named server1.
To configure CCI for your chosen protocol, please refer to your online book, Configuring CCI, or click Help Topics on the Help menu, and on the Index tab, click CCI Configuration Utility.
FHREDIR Return Codes
Each call to FHREDIR returns a status code in fcd-file-status in the FCD. Most codes returned are the usual file handling codes as described in the topic File Status Codes. The following codes specific to Fileshare might also be returned:
| Code | Meaning |
|---|---|
| -128 | Fileshare Security is enabled and the user name specified by the caller is not found in the password file on the server. |
| -127 | The named file is not currently open by the fileshare server. This does not mean that the file does not exist on the disk. |
| -126 | Fileshare Security is enabled and the password given is incorrect. |
| -125 | The requested data is larger than the buffer provided to contain it. Increase the size of your buffer. |
Fileshare Server
Before a Fileshare Server is invoked, you need to configure the Fileshare Server to specify:
- The Fileshare Server name to use on the network
- The communications protocols that it can use
Configuring the Fileshare Server
You can specify these Fileshare Server configuration options in one of two ways:
- On the command line (separated by spaces)
- In a Fileshare Server configuration file (a text file which you can create using any
text editor).
The Fileshare Server identifies the configuration file to use by checking the FS environment variable:
- If set, the Fileshare Server uses the configuration file specified by this variable
- If not set, the Fileshare Server uses the default configuration file fs.cfg either in the current working directory of the Fileshare Server or on the path specified by the COBDIR environment variable
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, for example, the command line:
Windows:
fs /s server1
UNIX:
fs -s server1
registers the name of the Fileshare Server 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.
Specifying the Communications Protocol
By default the Fileshare Server uses CCITCP to communicate with Fileshare Clients using the TCP/IP protocol. You need to specify any other protocol you want Fileshare to use by specifying the /cm option, for example:
Windows:
/cm cciipx
This entry in the Fileshare Server configuration file enables the Fileshare Server to communicate with Fileshare Clients using the Novell IPX (CCIIPX) protocol.
UNIX:
-cm ccitcp -cm ccinampu
These entries in the Fileshare Server configuration file enable the Fileshare Server to communicate with Fileshare Clients using TCP/IP (CCITCP) and the Named Pipes for UNIX (CCINAMPU) protocol.
Starting the Fileshare Server
You must start the Fileshare Server running before Fileshare Clients can connect to it.
To start the Fileshare Server use the following command line:
fs
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 that you wish to close down the Fileshare Server?
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 to close down the Fileshare Server (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
If you are using the CCITCP 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.
Copyright © 2008 Micro Focus (IP) Ltd. All rights reserved.