| Callable Sort Module (Extsm) | Fileshare Tutorial | |
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.
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:
The ability of any one application to take advantage of these features depends on:
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.
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:
Figure 18-2: Fileshare network
Notes:
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:
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.
At the Fileshare Client machine, you need to do two things to enable your COBOL program to use Fileshare:
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.
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:
In order to successfully redirect I/O operations, FHRedir needs to know:
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:
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.
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.)
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:
Notes:
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.
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:
Before a Fileshare Server is invoked, it needs to know:
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.
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.
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:
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.
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.
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:
[/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.
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:
/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.
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:
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:
In COBOL, the update operations are WRITE, REWRITE and DELETE.
A transaction terminates when:
Notes:
Before using transaction processing you are strongly advised to do the following to ensure the highest level of integrity for your data:
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.
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:
If this period is less than the timeout period, then:
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.
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.
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.
A system failure can result in loss of data in either of the following circumstances:
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.
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:
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:
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.
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 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:
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.
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:
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:
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.
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:
/o l option specifies that logging is omitted.
However, sequence number checking is still active for this file.
/o s option specifies that sequence number
checking is not used on this data file. 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.
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.
To link your program object into the Fileshare Server executable enter:
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.
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.
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:
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:
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.
In addition:
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.
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.
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:
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.
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:
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:
Figure 18-3: Fileshare Password System
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,
user-password
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).
01 user-password pic x(20).
...
procedure division.
...
move 1 to function-code
move "UserID" to user-name
move "Password" to user-password
call "fhrdrpwd" using function-code,
user-name,
user-password
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.
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.
The Password File Maintenance Utility is used to create the password file and add user-ID and password entries. For more information on this utility, see the section Password File Maintenance.
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.
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:
Figure 18-4: Logon Validation 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.
call "fsseclog" using user-ID
password
return-status
user-IDpassword return-status |
pic x(20). pic x(20). pic x comp-x. |
user-ID |
The Fileshare Client's user-ID. |
password |
The Fileshare Client's password. |
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.
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.
The sequence of steps that your program and Fileshare follow are:
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.
call "fssecopn" using filename
filename-length
operation-code
user-ID
return-status
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. |
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. |
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.
Use the /pf (password file) option to add or remove entries in the password file.
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
This example invokes password file maintenance, creates or updates a password file called pass.dat and adds a user-ID of pkel and password of fishwife.
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 already using Fileshare Password Security, simply add the FSVIEW entry to your existing file.
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.
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 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.
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.
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.
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.
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 |
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.
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:
There are some restrictions to the Fileshare Server's operation when started in synchronous communications mode:
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
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:
| fhredir.obj | The linkable version of the File Handling Redirector module. You must link this module into the executable application. |
| fhredird.obj | The linkable version of the File Handling Redirector module that must be used when creating a statically linked executable to run on DOS under XM. |
| fhrdrpwd.obj | The FHRedir password module. You need to include this module if your application makes use of Fileshare Security. (See the section Fileshare Security.) |
| xfhname.obj | The module that resolves filenames defined using environment variables. You must include this module if your application uses this feature. |
| fhxscomp.obj | This module is provided for backward compatibility for applications that made use of the /xs option. |
| extfh.obj | The COBOL system Callable File Handler module. On 16-bit systems, you must link this module into the executable if your program accesses any local data files. |
| mffh.obj | The COBOL system Callable File Handler module. On 32-bit systems, you must link this module into the executable if your program accesses any local data files. |
| cbldc001.obj | The compression routine used by the Callable File Handler when accessing local data files that have data compressed records. You need this module if you have included the fhxscomp.obj module. See the description of the fhxscomp.obj module above. |
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.
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.
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:
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:
The functionality provided by FS_LOCATE_FILE is the same as CBL_LOCATE_FILE except:
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.
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.
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.
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.
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.
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.
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.
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.
You can rebuild the UNIX Fileshare Server executable, enabling you to:
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:
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.
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 -pf password.fil -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.
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:
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.
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.
| Status Code |
Meaning |
|---|---|
| 9/037 | Access is denied. In addition to the normal situations
where this error occurs, Fileshare generates this error when:
See the section Fileshare Security for more information. |
| 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:
|
| 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.) |
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:
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:
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.
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.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Callable Sort Module (Extsm) | Fileshare Tutorial | |