This chapter describes the advanced features that are available with Fileshare.
Note: In Mainframe Express, Fileshare is only supported for use by the components of Mainframe Express. Therefore some of the following information about writing applications that use Fileshare is not relevant to Mainframe Express users.
You can configure Fileshare to run in single user mode. All network communication is bypassed and the Fileshare Client makes direct calls to the Fileshare Server module. The Fileshare Server does not run as a separate process in this mode of operation.
This is useful when:
To run Fileshare in single user mode, set the FSCOMMS environment variable to $local, for example:
Windows:
set FSCOMMS=$local /s servername
UNIX:
set FSCOMMS="\$local" /s servername
export FSCOMMS
Even when you are running in single user mode, you must still inform 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 FSSERVER environment variable must be unset.
Filename mapping enables I/O requests made against one data file to be mapped to a different data file when your program is executed. For example, you can use filename mapping to enable applications that use DOS file naming conventions to access data files under the control of a Fileshare Server running on an operating system that uses different file naming conventions, such as UNIX or NetWare.
You do not need to change the configuration of the Fileshare Client to use filename mapping.
To enable filename mapping, use the /af (alternate filename) option with the /f option in the database reference file.
The /fs (filename string) option used in conjunction with the /af option enables you to substitute characters at the start of a filename. This is particularly useful for mapping pathnames.
For example:
fs /d dbase.ref /f old.dat /af new.dat fs /d dbase.ref /fs c: /af e:
adds entries to the database reference file dbase.ref which specify that:
If the Fileshare Server finds an entry specifying an alternate filename, any character string substitution specified by a /fs option is applied to the new filename.
After processing any string substitution specified by an /fs option, the Fileshare Server does not search the database reference file for any matching /f option using the new filename.
Fileshare processes all filenames as relative to the Fileshare Server's current directory if you have not given a fully qualified filename after the /f option or a fully qualified filename is not passed from the Fileshare Client.
All filenames and paths are forced to upper case by Fileshare Servers not running on the UNIX operating system and are expanded to include the full path to ensure matching. Filenames specified with the /af option are not modified.
fs /d dbase.ref /f file1.dat /af c:\data\file2.dat
This example adds entries to the database reference file dbase.ref that specify that file accesses to the file file1.dat are mapped to the alternate filename file2.dat.
fs /d dbase.ref /f file1.dat /af c:\data\file2.dat fs /d dbase.ref /fs c: /af e:
This example adds entries to the database reference file dbase.ref that specify that all requests made to the data file file1.dat are redirected to the alternate filename and, in addition, the alternate filename is changed, using string substitution, to be on drive e:.
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.
Data and key compression specifications in the database reference file are effective only if the Fileshare Server creates the data files. They do not affect existing data files. For existing files, the data and key compression information is retrieved from the data file header. Any settings in your program or the database reference file are ignored.
fs /d dbase.ref /f file1.dat /k d001 fs /d dbase.ref /f file2.dat /k d001i7
This example tells the Fileshare Server to create the file file1.dat with data compression and the file file2.dat with both data and key compression.
The Fileshare Server can pass I/O requests to a program specified by you, rather than by the Micro Focus File Handler, as long as the program that you specify conforms to the call interface used by the File Handler.
You do not need to change the configuration of the Fileshare Client to use the Virtual File Handler Interface.
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 to which I/O requests for a particular data file are passed by the Fileshare Server.
fs /d dbase.ref /f user1.dat /ap myprog
This adds entries to the database reference file, dbase.ref which specify that the Fileshare Server should pass all I/O requests for the data file user1.dat to the program myprog.
Windows:
On Windows, your program should be in .obj file format and needs to be linked into the main Fileshare module, fs.dll. See the section Linking the Fileshare Server on Windows for further details.
UNIX:
On UNIX, your program should be compiled to intermediate or generated code, or to a callable shared object, and must be callable from the Fileshare process.
You also need to use the fcd3 copybook instead of the standard fcd layout.
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 severely impacts the 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 .
FSVIEW is a data tool which enables you to view data and statistics produced by Fileshare and manage Fileshare servers remotely.
You can use FSVIEW to perform the following tasks:
All of the features of FSVIEW are available to you as a command line utility.
The commands you specify on the command line define the operation to be carried out by FSVIEW. Information is returned as a scrolling screen output. See the topic FSVIEW Command Line for detailed information on FSVIEW commands.
On the FSVIEW command line, an at character (@) followed by a filename indicates that the named file contains FSVIEW commands.
If you use a file to supply FSVIEW commands, the file must be an ASCII text file.
Within the FSVIEW command file:
The following example shows an FSVIEW command file that identifies a file and lists the users currently accessing it:
! Demo of fsview command file ! Identify file and list its users option upcase option no-echo admin logon FSVIEW MFTEST server set NWB-GLEN server get users get files get file get-users F:\testing\fsvtests\fresh\testfile1.dat user-file close 7 F:\testing\fsvtests\fresh\testfile1.dat users get files get exit ! All done
Note that if your command file does not use the FSVIEW exit command, you will remain in FSVIEW after the file has been executed.
All information displayed by the FSVIEW command line utility can be redirected to a text file using standard operating system redirection:
> | Creates a new file |
>> | Extends an existing file |
For example:
@fred.ctl >> fsview.txt
redirects the output from fred.ctl to the existing file fsview.txt.
All of the functionality of FSVIEW is available as an API. We provide two copybooks for use with the FSVIEW API:
Defines the FSVIEW API call names and their parameters.
Defines the passed data block for use when tables are passed.
Note that the FSVIEW API includes the Fileshare Manager (fsmgr) API. See the section Fileshare Manager for more information on Fileshare Manager.
The FSVIEW API is called fsviewc. All usage of the FSVIEW API must begin with a call to FSV-C (fsviewc) and end with a call to FSVIEW-C-TERM (fsviewc_term). See the topic FSVIEW API for more information on FSVIEW API functions.
The following example shows access to a Fileshare server which does not have Fileshare security enabled. The name of the server, the time the server was started and the current server usage level are returned:
*** initialize fsview call FSV-C *** connect to a server called serverx move spaces to l-user-name move spaces to l-server-password move “serverx” to l-server-name call FSV-C-change-server using l-server-name l-user-name l-server-password *** get basic server information call FSV-C-get-server-info using fsvw-data-block if return-code = h”3030” display "Current Server Status" display "Server Name - " fsvw-server-name display "Started - " fsvw-server-startup display "Utilization - " fsvw-server-usage end-if *** terminate fsview call FSVIEW-C-TERM
Note: This example uses the two provided copybooks.
Some FSVIEW calls do not directly return information to the calling program but make repeated calls back to a user-defined call. This is because fsviewc only processes items in blocks of ten.
For example, FSV-C-get-files-users uses the FSV-C-add-to-user-list callback to return a list of logged-on users for a specific file. Because fsviewc processes blocks of ten, repeated calls must be made in order to handle enough blocks of ten to code the total number of logged-on users being returned.
The following example shows an FSV-C-add-to-user-list callback. The entry point in this program allows fsviewc to execute the main body of the program. Without the entry point, the program would just set the number of users to 1 and exit:
working-storage section.
*------------------------
copy "fsviewop.cpy".
01 work-vars.
03 i pic xx comp-x.
03 j pic xx comp-x.
linkage section.
copy 'fsdatab.cpy'.
01 number-of-entries pic xx comp-x.
procedure division.
*-------------------
move 1 to user-list-ptr
exit program
.
list-users section.
entry FSV-C-add-to-user-list using number-of-entries
fsvw-data-block.
if hide-changeable
perform user-test-masking
end-if
perform varying i from 1 by 1
until i > 10
or user-list-ptr > number-of-entries
if FSVW-INSERT-LIST-BOX-ITEM (i) not = spaces
if hide-changeable
move all "X"
to FSVW-INSERT-LIST-BOX-ITEM (i)(s:l)
perform user-line-test-masking
end-if
display FSVW-INSERT-LIST-BOX-ITEM (i)(1:78)
else
if i = 1
display "No users found"
end-if
move 11 to i
end-if
add 1 to user-list-ptr
end-perform
.
move zero to return-code
exit program
.
You can use the Fileshare Manager (fsmgr) to automate some of Fileshare's supervisor mode functions by writing a COBOL program to call it. The Fileshare Manager can be called to instruct a Fileshare server to:
Note: Any Fileshare Clients connected to the Fileshare Server when this instruction is issued will be logged off and any files which they had open will be closed.
The Fileshare Manager program (fsmgr) is called from a COBOL program as follows:
call "fsmgr" using parameter-block
parameter-block | A group item defined as: |
function-code | pic xx comp-x. |
error-status | pic xx comp-x. |
fileshare-name | pic x(16). |
supervisor-passwd | pic x(20). |
reserved | pic x(24). |
function-code | The Fileshare Manager program function required:
|
||||||||||
fileshare-name | The name of the Fileshare server (this is the name that was used when Fileshare was started) | ||||||||||
supervisor-passwd | The supervisor password. See the section Supervisor Mode in the chapter Security for more information | ||||||||||
reserved | Reserved for future use. Must contain binary zeros. |
error-status | Reflects the success, or failure, of the call. Possible values
of error-status are shown below.
|
Fileshare Manager, like other Fileshare Client applications, accesses a Fileshare server via the Fileshare Handling Redirection module (FHRedir) and so needs to be configured to use the correct communications protocol. See the section Client Configuration in the chapter Configuration for more information.
If your program calls the Fileshare Manager, you need to link in the Fileshare manager object file (fsmgr.obj on Windows, fsmgr.o on UNIX) when you create an executable file.
Fileshare supports some of the byte-stream I/O routines that are available with this COBOL system. Most of the routines use the same parameters and have the same effect as the corresponding COBOL system call, but access remote files via Fileshare. The only change needed to your program is to call the routine starting with FS_ instead of CBL_. The only routine that does not have exactly the same call interface as its corresponding CBL_ routine is FS_LOCATE_FILE.
Fileshare supports the following byte-stream I/O routines:
You can use these routines to access files on remote Fileshare servers, as well as local files. Configure the Fileshare Client in the normal manner to define which files are local and which are remote.
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 parameter.
If you have included the callable sort, and receive error 173 after switching to release build, you need to include fhrsub.obj in your project.
Windows NT:
You can install the Fileshare Server so that it runs as a Windows NT service by entering the following at the command prompt for this Micro Focus product:
fsservice -i
Once installed, you can display the status of the service by entering:
fsservice -v
and you can uninstall Fileshare as an NT service by entering:
fsservice -u
Once Fileshare is installed as an NT service, you can start it as a background process as follows:
You can stop the Fileshare service as follows:
Notes:
You can specify that the Fileshare Server should be started up automatically when Windows NT boots up as follows:
Note: If you have specified that the Fileshare Service is to be started automatically when Windows NT boots up and you have logging switched on for any data files, we recommend that you specify a Fileshare backup directory in your database reference file. See the section Automatic Database Backup and Rollforward Recovery in the chapter Database Integrity for more information.
Before starting Fileshare, you need to create a Fileshare Server configuration file so that you can specify Fileshare Server options. For more details on Fileshare Server options, see the section Server Configuration in the chapter Configuration.
The Fileshare Service inherits the Windows system directory (for example, c:\winnt\system32) as its current directory and so you should place your Fileshare Server configuration file in this directory. If you want Fileshare to use a different working directory, you can specify this using the /wd option as the first entry in your configuration file. On start-up, Fileshare changes to your specified working directory and accesses any files that are not fully qualified as being relative to this working directory, for example, a database reference file.
Because Fileshare runs as a background process, any messages it generates are written to the file fsscreen.lst in the current working directory. Check the contents of this file to diagnose any problems.
The following is an example of a Fileshare Server configuration file:
/wd d:\fsdir /s server1 /d dbase.ref
where the first line specifies the directory fsdir on the drive d: as the Fileshare Server's current directory. Any data files without fully qualified pathnames are searched for, relative to this directory. The second line specifies that the Fileshare Server is to register its name on the network as server1 and the third line specifies that Fileshare is to use the database reference file dbase.ref. Because this name is not fully qualified it is searched for in Fileshare's current directory, that is, d:\fsdir.
Windows:
If you want to use the Virtual File Handler Interface or your own security modules on Windows, you need to recreate the file fs.dll. You can do this by entering a command line similar to the following:
cbllink -ofs.dll -d -RE,2.0 -Mfscmd fscmd.obj fsserver.obj fhxscomp.obj fsseclog.obj fsinstpw.obj fsinst.obj fsrcvr.obj fspthnam.obj fssecopn.obj fsossec.obj cbldc001.obj _codeset.obj mfini.obj mffh.obj bsio.obj extfhsub.obj esdssub.obj xfhtrace.obj c2banner.obj fsdll.rbj
Alter this command line to suit your own purposes by adding object modules or substituting security modules as necessary.
Alternatively, if you are running Fileshare as a Windows NT Service, you will need to relink the fsservice.exe module using a command similar to the following:
cbllink -ofsservice.exe -Rm,+2.0 fssrvice.obj CblNTService_Handler.obj CblNTService_SetStatus.obj CblNTService_ServiceRoutine.obj servserv.obj fscmd.obj fsserver.obj fhxscomp.obj fsseclog.obj fsinstpw.obj fsinst.obj fsrcvr.obj fspthnam.obj fssecopn.obj fsossec.obj cbldc001.obj _codeset.obj mfini.obj mffh.obj extfhsub.obj bsio.obj esdssub.obj c2banner.obj fssexe.rbj
Then uninstall the old version of fsservice and install this new version.
Note:
The .obj files required by the above commands are not supplied with Mainframe Express. If you are using Mainframe Express and need to recreate fs.dll or relink fsservice.exe please contact Micro Focus SupportLine who can supply you with additional software containing the required files.
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 affect 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.
Any speed improvements are therefore very specific to individual applications and become more pronounced as more Fileshare Clients concurrently access the same data files.
We recommend you always use the synchronous mode of operation for best performance with Fileshare. Async-mode should be considered as being for development purposes only, and production installations should always use synchronous operation.
UNIX:
On UNIX, when running the Fileshare Server and Fileshare Client on the same machine, we recommend that you use the CCINAMPU CCI protocol as it performs better in this situation than the CCITCP protocol.
UNIX:
Fileshare improves performance when remote COBOL applications are concurrently accessing shared data files across a network but it cannot improve peformance when the COBOL data resides on the same machine as the application. In this configuration, there is actually a performance overhead when using Fileshare instead of the standard Callable File Handler.
Although UNIX machines can be used as remote data servers, it is not uncommon for the application itself to run on the machine where the data resides. For example, multiple users may log in, across a network, to a machine where they run applications which share the same data. In such a configuration, you encounter the performance overhead of using Fileshare, making performance slower than when using the standard Callable File Handler.
Fileshare, by default, supports files that can be up to 4 Gigabytes in size. If your operating system supports larger files, you can configure the file handler used by Fileshare to allow sequential, relative and IDXFORMAT(8) indexed files greater than the default 4 Gigabytes.
An alternative technology, file striping, was introduced in previous releases as an interim solution to overcome limitations on the maximum allowed file size. It enables you to specify that a single data file is to be stored in multiple physical files (or stripes) on disk.
Because of the complications involved with configuring striping together with Fileshare (these issues are discussed below), we recommend that you keep your large files non-striped and instead, configure the file handler to use its standard large file support.
You should also review the chapter File Handler Configuration in your File Handling book.
To configure large file support under Fileshare, you should consider the following:
The extfh.cfg file must be located in the same directory as the Fileshare Server or, if the EXTFH environment variable has been set to point to the extfh.cfg file, it must have been set in the Fileshare Server session.
Add the following line to the extfh.cfg file:
[XFH-DEFAULT] Filemaxsize=8
The following information explains how to configure striped files under Fileshare control if your operating system does not support large files:
You must use the fully qualified name of the base file in the extfh.cfg configuration file. This name includes the pathnames that you can see if you press F2 at the Fileshare Server to switch tracing on.
UNIX:For example, on UNIX:
[/u/username/file.dat] Striping=on
Note: You need only do this for files accessed through Fileshare. To enable the file handler to find the setting in extfh.cfg the filename tag must match exactly that specified by the I/O request, which in the case of Fileshare includes a fully qualified path.
The backslash character is treated as an escape character within the extfh.cfg file.
Windows:On Windows platforms you must therefore specify two backslash characters for each backslash character in the pathname, for example:
[d:\\fsrvr\\file.dat] Striping=on
You can specify file striping on an alternate filename (specified in the database reference file using filename mapping). In this case, the expanded filename is not required. For example, if the database reference file contains the following line:
/f file1.dat /af file2.dat
you can specify the following in the extfh.cfg file:
[file2.dat] Striping=on
StripeNameType=1 (the default is StripeNameType=0) only works with Fileshare if the base filename does not have an extension. If you specify StripeNameType=1 for a filename that has an extension, the file is created but it is not striped.
The use of striping complicates the process of logging for rollforward recovery because the administrator has to ensure that the correct versions of the files are in the latest backup, and that they are correctly restored in the event of needing to run the Fileshare Recovery Utility. This process is much more complex if file stripes also have to be maintained.
The Automatic Database Backup and Recovery facility does not work correctly on striped files because it uses low-level I/O routines for backups and restores which are unaware of the stripe configuration.
The filenames passed to the File Handler must match exactly so that the File Handler can locate the filename tags in the extfh.cfg file.
Generally, only Fileshare passes fully qualified names. Therefore, if you have set up an extfh.cfg file for use under Fileshare with expanded pathnames and then want to access the files outside of Fileshare, you need to change the filename tags in extfh.cfg to match exactly the filenames passed by the application.
Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.