| Configuring CICS for Communications | Configuring CICS Terminals | |
This chapter explains how to set up Fileshare. It covers the following topics:
For more information about Fileshare and its more advanced features see the Fileshare User Guide.
Fileshare provides CICS Option with VSAM data integrity, enabling you to use SYNCPOINT and SYNCPOINT ROLLBACK commands. Fileshare also enables you to access data files on other Windows systems running on the same network as the machine running Mainframe Express.
CICS Option can connect to up to sixteen Fileshare Servers, giving you the option of splitting your data across several machines. You can also run a Fileshare Server as a separate process on the same machine running CICS Option. This means you can effectively test a network application without a network.
If you are running single tasking and do not have to share your data files, you can configure Fileshare to run in "local mode".
Fileshare Servers can be used for the following CICS Option resources:
Fileshare works in a client/server setup, with the Fileshare Server being the server and a CICS Option region being the Fileshare client. The two can communicate with each other over a variety of protocols. The support for these protocols is provided by Micro Focus Common Communications Interface (CCI) modules. You establish the protocols to be used by each server by specifying the appropriate CCI modules when you start the Fileshare Server. The following table shows which protocols are supported on which operating systems, and lists the names of the corresponding CCI modules. Fileshare files can still be accessed by non-CICS applications at the same time.
The remainder of this chapter explains how to set up both the Fileshare Server and the client region to communicate over these protocols.
Before you try to run a Fileshare Server, you must ensure that Fileshare is available on the server machine.
You must run Fileshare commands from the Mainframe Express command prompt - from the Windows Start menu for Mainframe Express click Mainframe Express Command Prompt.
To start a Fileshare Server, enter the following:
fs /s server-name
where server-name names the server, and
corresponds to the ID
by which the client region knows the server. The /s parameter is
mandatory on each fileshare command. For a list of valid parameters, see
the section Using a Fileshare Configuration File.
This command starts a server with the default protocol enabled, and with
no password-checking performed when a client tries to access the server.
The default protocol is TCP/IP. You
can use the /cm switch to explicitly name the protocols to
be used. For example:
fs /s fstest /cm ccitc32 /cm ccinb32
In this example, ccitc32 and ccinb32 are the CCI modules required for TCP/IP and NetBIOS, respectively.
The following example starts a server with password-checking applied through the file fs.pwd:
fs /s fstest /cm ccitc32 /pf fs.pwd
The section Using a Fileshare Password File explains how password-checking works.
You can avoid specifying a list of parameters whenever you start the server by creating a Fileshare configuration file, as the next section explains.
If you enter the fs command with no parameters, Fileshare
looks for a configuration file named fs.cfg in your current
directory.
You can also specify a configuration file of a different name with the
/cf option, for example:
fs /cf c:\filesh.cfg
A Fileshare configuration file is an ASCII text file that contains one option per line.
The Fileshare configuration file, fs.cfg, contains the Fileshare
configuration options described below. Only the /s option is
required. The /pf option is strongly recommended, however,
as without it you cannot enforce any Fileshare security, although CICS
Option does provide Resource
Security Level (RSL) checking.
/s server-name
Specifies that server-name is the name that the
Fileshare Server registers on the network. The name specified has to be
unique to that Fileshare Server and must correspond to the Fileshare
Server ID
specified in the client region's Resource Definition Tables. If a
Fileshare Server with that name is already registered on the network, an
error is returned.
[/d database-reference-file]
Specifies database-reference-file as the name of
the database reference file that the Fileshare Server is to use.
Sets the transaction processing timeout, in seconds. If the server does not hear from its client in this period, and another client has requested access to records locked as part of the transaction, all files involved in the transaction are rolled back to their original state and all locks are removed.
The default timeout is 60 seconds. You can disable timeout by setting this to 0. The valid values are 0 through 99999999.
[/m record-size]
Specifies the maximum record size that the Fileshare Server processes.
Setting a lower value than the default value reduces the amount of memory
that the Fileshare Server needs to run. The value of record-size
specifies the maximum number of kilobytes of any record. The valid values
for record-size are 16 through
64.
Specifies cci-protocol as one of the CCI
communications protocols that the Fileshare Server can use to receive
communications from a Fileshare Client. Repeat this option for every
communications protocol that you want to use to contact this Fileshare
Server. Valid values for cci-protocol are:
CCITC32
for TCP/IP
CCINB32
for NetBIOS
CCIIX32
for IPX
If you do not specify any entries, the default is CCITC32.
[/cf configuration-file]
Specifies the name of the Fileshare Server configuration file. Use this option only on the command line. When using this option, you must specify the required Fileshare Server options in the configuration file. If you do not specify a name for the configuration file, it defaults to fs.cfg in the Fileshare Server's current directory.
/pf password-file
Names the password file used by this server. This option activates the Fileshare Password system. If you do not use this option, the Fileshare Server runs without security enabled.
[/tr f]
Specifies that the Fileshare Server trace option is activated as soon as the Fileshare Server starts. The trace echoes to the screen and a file called fsscreen.lst in the Fileshare Server's current directory. This option seriously impacts the Fileshare Server's performance. Use it only for problem investigation.
Examples
Assume the file fs.cfg contains the following lines:
/s fsserv1 /cm ccitc32 /cm ccinb32 /pf serv1.pwd
If you enter the command:
fs
Fileshare reads fs.cfg and starts a server named FSSERV1, with the TCP/IP and NetBIOS protocols enabled. It uses the file serv1.pwd for password security.
A Fileshare Server uses its password file to verify that a client region is entitled to access its files. Although Fileshare can run without a password file, you must use one if you want to apply any security through the Fileshare Server itself. This is strongly recommended, since Fileshare has access to all the files on your system.
The Fileshare Server uses its password file only when the region makes its first attempt at access (that is, when it starts up). File-level security is controlled by CICS Option itself, through the resource definitions you make.
The only way to maintain a password file is through this command line:
fs /pf pwd-filename options
Depending on the options you specify, Fileshare creates, modifies, or
deletes pwd-filename. You can name the password file
whatever you want, but it must correspond to the name you specify with the
/pf option when configuring the Fileshare Server.
The options are as follows:
/u username |
The user name used by the region to log onto the server. (This must correspond to the value specified in the FS user name field in the region's SIT.) Can be up to 20 characters. |
/pw password |
The region's password. (This must correspond to what is specified in the FS password field in the region's SIT.) Can be up to 20 characters. |
/e |
Erases the specified user from the password file. You
must specify both the /u and /pw options on
the same command line when you are using /e.
If you delete all the entries in the password file, the Fileshare server deletes it. Note: Both passwords and user names are case-sensitive. |
Examples
Assume no password file exists, and you want to create one with two entries. The following commands:
fs /pf fssecu.pwd /u mfereg1 /pw fspass1 fs /pf fssecu.pwd /u mfereg2 /pw fspass2
result in the password file fssecu.pwd being created, with entries for both mfereg1 and mfereg2. The mfereg1/fspass1 and mfereg2/fspass2 combinations must correspond to FS username and FS password fields in the regions' SITs.
To put password
checking into effect on a Fileshare Server called FSSERV (for
example), you must use the /pf option when starting it:
fs /s fsserv /cm ccitcp /pf fssecu.pwd
To disable mfereg2's access to this Fileshare Server, use the following command:
fs /pf fssecu.pwd /e /u mfereg2 /pw fspass2
If you now enter this command:
fs /pf fssecu.pwd /e /u mfereg1 /pw fspass1
Fileshare removes the entry for mfereg1, and deletes the file fssecu.pwd.
You can monitor the activity on a Fileshare Server with Fileshare's trace facility.
You can monitor the activity on a Fileshare Server by pressing F2 from the same session in which you started the server. This turns on Fileshare's trace facility, which displays file requests as they occur. For each request, you see the user identifier, opcode, requested filename, and file status bytes of the reply to the user.
You should use this facility only as a diagnostic aid, since it can degrade performance. Press F2 again to turn it off.
Before stopping a Fileshare Server, you must either close all regions that are connected to it, or close all files on the region.
To stop a Fileshare Server locally, go to the session from which you started it, and press the Esc key. You see the prompt:
FS097-I Are you sure you wish to close the Fileshare Server? (Y/N)
Enter Y to continue the shutdown; enter any other key to let the server continue running.
If any database files are open when you reply Y, a second prompt appears:
FS111-I Warning - database files are still open
Continue with the close (Y/N)?
If you enter Y, Fileshare closes all open files and shuts down. Enter any other key to cancel the shutdown.
The method of setting up a region as a Fileshare client depends on whether you have enabled Fileshare security or not. If security is enabled, you must first give the region a Fileshare user name and password. These must be specified in the FS user name and FS password fields of the region's SIT. The region uses this user name and password combination to log on to all its Fileshare Servers. The combination must appear in the password file for each Fileshare server the region wants to access.
Once you have set up the passwords, or if you have not enabled Fileshare security, you should name the servers the region is to connect to. The mechanism for doing this is the Resource Definition File (RDF), which specifies the location of individual resources (including whether they are on Fileshare Servers).
Finally, you must specify the protocols over which the region communicates with its servers. This is done through the File Handling Redirector (fhredir) configuration file.
The next sections explain how to use the RDF and the fhredir configuration file to enable Fileshare access.
Through the Resource Definition File, you can specify that any of the following resources reside on a Fileshare Server:
The FCT, DCT, and SIT contain fields for specifying the name of a Fileshare Server. If you fill one of these fields in, CICS Option looks for the resource on a Fileshare Server.
The FCT fields are on the Overrides page of the FCT Properties dialog. (Right-click the FCT entry in the right-hand pane of the CICS View, click Properties on the popup menu, and click the Overrides tab.)
The fields are:
| FS server | The Fileshare Server through which CICS Option accesses the file. This name must correspond to the name you give the server when you start it. This field is mandatory. |
| File name | The filename Fileshare uses to find the file. This field is optional. |
| Path | The path Fileshare uses to find the file. This field is optional. It must be specified if the path defined by the Mainframe Express project does not exist on the Fileshare server machine. |
| Extension | Specifies the file extension Fileshare uses to find
the file. This field is optional. For indexed files, this results in a
filename and its index component as follows:
filename.dat
|
The fields in the DCT can be accessed only through the character interface to resource definition. (Click CICS on the Tools menu of the IDE, then click Resource Definition.)
The fields are:
| FS server ID | The Fileshare Server through which CICS Option accesses the file. This name must correspond to the name you give the server when you start it. This field is mandatory. |
| Filename | The filename Fileshare uses to find the file. This field is optional. |
| Path | The path Fileshare uses to find the file. This field is optional. It must be specified if the path defined by the Mainframe Express project does not exist on the Fileshare server machine. |
| Extension | The file extension Fileshare uses to find the file.
This field is optional. For indexed files, this results in a filename
and its index component as follows:
filename.dat
|
In the SIT, there are two sets of fields through which you specify Fileshare Servers for TS and intrapartition TD queues. You do not have to specify the Fileshare Server and path for each individual queue.
You can create or modify a System Initialization Table (SIT) using the SIT View of the character interface to resource definition.
The SIT View is divided in to six screens. The third screen of the SIT View enables you to define the following resources:
Each Fileshare server id field should name the server through which CICS Option accesses the queue. This name must correspond to the name given to the server when it is started. Each path field must specify the full path name Fileshare uses to find the queue. The path field is optional.
CICS Option uses a Fileshare Client configuration file to establish the communications protocols that are used between its regions and Fileshare Servers. (fhredir is the module that forms the client interface to Fileshare.) If no configuration file is used, the Fileshare Client defaults to using the CCITC32 protocol.
You must create this file, adding entries that specify which protocols to use to communicate with each server. You must also tell CICS Option where to find this file.
You can use any text editor to create the fhredir configuration file. It must contain one entry per line, in the following format:
/cm cci-module
where:
server-name |
names a server | ||||||
cci-module |
is one of the following:
|
If, for example, you have two Fileshare Servers called FSSERV1 and FSSERV2, and you want regions to communicate with them as follows:
| FSSERV1 | over NetBIOS |
| FSSERV2 | over TCP/IP |
then your Fileshare Client configuration file should contain the following lines:
/cm ccinb32 /s fsserv1 /cm ccitc32 /s fsserv2
You can also set a default communications protocol for any servers not named in this file, using the following line:
/cm ccitc32
The result is that TCP/IP is used as the protocol for any servers other than FSSERV1 and FSSERV2.
To put the Fileshare Client configuration file into effect, you must set the environment variable FHREDIR to point to the file. You must set the FHREDIR environment variable from the Mainframe Express command prompt before starting Mainframe Express as follows:
set fhredir=e:\mfuser\projects\projectname\fhredir.txt
mfe
to start Mainframe Express.
CICS Option consults this file whenever a region requires a resource from a server. You should not, therefore, change this file while any regions using servers defined by it are running.
Integrated Fileshare support provides dynamic transaction backout for files, temporary storage, and transient data without requiring an external Fileshare server to be started. It provides improved performance over using an external Fileshare server. To enable integrated Fileshare support, you need to set one field in the SIT.
We recommend that you do not use integrated Fileshare support to access IMS databases on both single- and multi-tasking CICS systems. You should instead use external Fileshare.
Integrated Fileshare support includes support for the CICS Backward Recovery (Backout) facility. To enable backward recovery for a file, check Backward recovery on the Advanced page of the FCT properties dialog box. If Backward recovery is not set, the file is not recoverable even if it resides on a conventional Fileshare server.
If you do not specify a Fileshare server (in the FS server field on the Overrides page of the FCT properties dialog box) for a file that is marked as recoverable, Mainframe Express uses the integrated Fileshare support. Similarly, if you do not specify a Fileshare server (in the DCT) for recoverable temporary storage and transient data data sets, Mainframe Express uses the integrated Fileshare support.
The logical Fileshare server name for the integrated support is TX-{regionname}, and the support is enabled by setting the Integrated Fileshare support field in the SIT to Y.
When using the CCI protocol IPX, the logical Fileshare server name is not prefixed by TX-. For this protocol, the logical Fileshare server name is {regionname}. The internal name is still TX-{regionname}, and this must be used for FCT entries in the region {regionname}.
When integrated Fileshare support is enabled in a multi-tasking region, and when a CCI gateway is started for the appropriate network protocol, the region is able to provide Fileshare services to external clients. To enable the Fileshare services to be used externally, you must have transaction X'FCFFFFFF' defined in the PCT and associated with program dfhzai (this program name must be lowercase).
You should consult your Fileshare documentation to make sure that any CCI network protocols you are using with CICS Option are supported by Fileshare.
Files accessed through integrated Fileshare support are locked in the same way as with conventional Fileshare. In a multi-tasking system, the only way batch programs can access these files is through the CICS Option gateways. In a single-tasking system, the files are locked and other batch programs cannot access them (any attempt receives a "file locked 9/65" status).
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Configuring CICS for Communications | Configuring CICS Terminals | |