Fileshare Manager

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:

Perform an automatic backup of its recovery log file
Close all of its currently open data files. Any client application accessing these files is returned a file status, indicating that the file is no longer open. This is particularly useful in the event of a system crash or power failure, either of which could cause a Fileshare client program to terminate without disconnecting properly from Fileshare. If this happens, and data files are left open on the Fileshare server, it can prevent automatic disk backups from running and possibly prevent other clients from accessing the files.
Log off any clients currently connected to it, close any open files and roll back any incomplete transactions belonging to these clients.Any subsequent access attempts by these client applications result in an error status (9/125).
Close down completely. Any open files are closed and any incomplete transactions rolled back
Close down completely and then re-start. If a backup directory has been specified in the database reference file, Fileshare copies all the files named in the database reference file to the backup directory, deletes the recovery log file(s) and re-starts with a new recovery log file.

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:

Syntax:

call "fsmgr" using parameter-block

Parameters:

parameter-block

A group item defined as:

function-code: pic xx comp-x.
error-status: pic xx comp-x.
fileshare-name: pic x(16).
supervisor-passwd: pic x(20).
reserved: pic x(24).

On Entry:

function-code

The Fileshare Manager program function required:

1: Backup recovery log file
2: Close all open data files
3: Log off all connected clients
4: Shut down Fileshare
5: Shut down and re-start Fileshare

fileshare-name

The name of the Fileshare server (this is the name that was used when Fileshare was started)

supervisor-passwd

The supervisor password. See the section Supervisor Mode in the chapter Security for more information

reserved

Reserved for future use. Must contain binary zeros.

On Exit:

error-status

Reflects the success, or failure, of the call. Possible values of error-status are shown below.

Value	Description
0	Function completed successfully
1	Communications error. A Fileshare server of the name specified in `fileshare-name` could not be contacted on the network using the specified communications protocol. This error is also returned if a network failure occurs during the execution of the function but after the initial connection was made. Check that `fileshare-name` is specified correctly and that the Fileshare Handling Redirection module (FHRedir) is configured to use the correct communications protocol.
2	File error during initial connection. To connect to Fileshare, the Fileshare Manager opens a file called fsmgr.ctl. This file should not already exist and the Fileshare Manager does not actually create it. If it does exist, this status is returned if there is a subsequent error in closing the file.
3	Invalid password specified in `supervisor-password`. Ensure that Fileshare is running with a password file and that the contents of `supervisor-password` match the supervisor password entry in the password file. Note that Fileshare passwords are case sensitive. See Supervisor Mode in the chapter `Security` for more information.
4	Invalid value specified in `function-code` - must be within the range one to five
5	No Fileshare log file. You have attempted to backup the log file on a Fileshare server that is running without a recovery log file.
6	Function 2 or 3 could not complete. While attempting to log off all Fileshare's clients (function 3), it is possible for other clients to log on before the logging off operation completes. For example, the Fileshare Manager has to send a "logoff client `n`" request four times if there are four clients logged on. If, however, a new client logs on before all four original clients have been logged off, the Fileshare Manager retries the "logoff client `n`" request in order to log off the new client. It retries 10 times and if new clients are still logging on, it returns error 6. A similar situation can occur during processing of a function 2 (close all data files) if new files are continuously being opened at the same time.
10	Other error