Client Server

The Client Server (or CS) model accomplishes 2 things:

1. It integrates Linux with Windows (phase one).
2. It extends the server environment to the client with respect to printing and file transfers (phase two).

Please note that REMOTE PRINTING is a logical requirement of using CS with Windows servers because these operating systems were not designed to support CS server printing. When a login is authenticated on a Windows server, the user is granted access to their own defined printers only if they are also logged into the server's desktop. This means REMOTE PRINTING (printing through the user's desktop) is a practical prerequisite of using the CS model with Microsoft servers. (See REMOTE PRINTING details below.)

Supported Platforms

Client	Server
Windows	Windows
Windows	Linux
Windows	MAC|
MAC	MAC
MAC	Windows
MAC	Linux

Components

BRClient.exe	Client - Runs on a workstation
BRListener.conf	Listener configuration file (place on server in Windows dir or /etc )
BRServer.exe	Windows BR Server Program (location specified in conf file)
BRserver	Linux or MAC BR Server Program
BRListenerInstaller.exe	BRListener.exe Installer for Windows Server
BRListener.exe	Server side Connection Agent and Server side Connection Agent

Installation Instructions

WINDOWS-

First modify the BRListener.Conf file and copy it into your Windows directory on your Windows server. Change the logfile, the executable and the startdir as necessary. Startdir is used on the server. It specifies the BRserver initial working directory. This is where it will look for BRConfig.sys. However a different configuration file name and path can be specified in the session statement. This may be desirable when you are using both conventional and CS models together, with different screen specifications for each.

The brlistener.conf file has three statements:

logfile= specifies the location and name of a trace file ( do not use quotes nor spaces in this path)
loglevel= leave at 6 for now - may be significant later
port= port number to use (default is 8555)

The brlistener.conf session statement format is:

LABEL=BR       Arbitrary statement label name - must be referenced in client startup command
STARTDIR=      Starting server directory ( do not use quotes nor spaces in this path)
STDERR=        Filename to contain error reports.
EXECUTABLE=    Pathname of BRserver executable.  

Note- This executable refers to BR itself. You can initiate your application via a BRCONFIG.SYS EXECUTE statement.

CAPTION=       The client login prompt window caption.
CONFIG=        Pathname to BRConfig.sys file - optional - defaults to server startdir
ANONYMOUS=     username@password - optional (see below)
MULTISESSION   This keyword tells the brlistener to allow multiple sessions to operate with a single login. If your application doesn't support multiple sessions, omit this keyword.

Example

[ LABEL=BR STARTDIR=C:\Myapp EXECUTABLE=C:\Myapp\BR\brserver CONFIG=C:\Myapp\brconfig.svr ]

Session Statement Notes:

If the client fails to connect with the server, for now, remove all but one label statement.

Any names containing blanks must be enclosed in quotations.

The WSID may be set in the CONFIG file according to username. See BRConfig.sys for more information.

Activating the Server

The BRListenerInstaller.exe program is used to install BRlistener.exe as a Windows service.

When you execute BRListenerInstaller you must have Administrator privileges, BRListener.exe must be in C:\Windows\System32 and BRListener.conf must be configured and located in C:\Windows. No parameters are required by the BRListenerInstaller.

To remove BRlistener.exe from Windows services specify:

BRListnerInstaller  /Release

A number of other configuration options using the installer are described in BRlistener.exe.

After installation is done, Windows Services will have an entry for BR_Listener. If the logfile has been set up appropriately it should now be created and have a few messages in it. Rebooting is NOT needed in order to use it.

If all has worked so far you should be able to launch the client. To launch the client run

      BRclient computer BR

Where 'computer' is an IP address or IP name and BR is the labelname in brlistener.conf. You can get your server's IP number by going to a DOS shell and running 'ipconfig'.

An alternate way to specify the server location is to use a separate control file called BR_Parms.txt.

The BR_Parms.txt file can be used in client server installations of Business Rules! to configure the Host and Label.

host=[ip address or dns name or localhost]
label=[the BRLISTENER.CONF label you are connecting to] 

This file must reside in the same directory as BRClient.exe.

This file can be overidden in the startup ICON by specifying the host IP and label right after the executable (all separated by spaces).

Security Issues:

If ANONYMOUS= is specified, all users accessing the process will be logged in under username on the server. In this case, the user is not requested to provide his or her name and password, and it is not possible to specify a particular WSID for the user. USE THIS FEATURE WITH CAUTION. It is left up to the application to authenticate access. USERNAME SHOULD HAVE RESTRICTED OS ACCESS. Remember, it is possible to access any pathname under BR by preceding the reference with a colon.

You may wish to remap command characters such as ctrl-A to a null value. If you wish to make interrupts possible by only your support staff, you can map hex CO, or any other BR line draw character, to 01 (ctrl-A). Hex C0 is generated by the digit 1 only when in line draw mode which is toggled by ctrl-\. (e.g. keyboard 01 41, keyboard C0 01 - accessed by ctrl-\ 1 ctrl-\)

Generally, BRserver inherits the security privileges of BRlistener. They are then restricted according to the permissions of the person logging in (or the "anonymous=" username).

Note regarding 2003 Server:

When using client-server BR with a Windows 2003 Server, users need to have the permission “Allow log on locally”. By default, Windows 2003 Server only grants this permission to administrators. This setting can be enabled using the Domain Controller Security Policy administration utility. This can be found though:

 Start -> Administrative Tools -> Domain Controller Security Policy

After starting the utility, in the tree, go to

 Security Settings -> Local Policies -> User Rights Assignment

This will bring up a list of policies in the window to the right and one of them will be:

 Allow log on locally

To add/edit users that have this permission double click on it.

---

LINUX- (first read the Windows install instructions)

First we describe the steps involved in installing brlistener under Linux. Then we provide an install script for managing the process.

Revise the brlistener.conf file appropriately. See the Windows install section for brlistener.conf specifications.

Examples-

  [ LABEL=BRX  STARTDIR=/u/myapp  EXECUTABLE=/u/myapp/br/brserver CONFIG=/u/myapp/brconfig.svr ]

  [ LABEL=BRX  STARTDIR=/u/myapp  EXECUTABLE=/u/myapp/br/brserver.script CONFIG=/u/myapp/brconfig.svr ]

Where brserver.script contains

      TERM=ansi;            # this is not needed for BR to work - it is simply an example of using a script
      export TERM;
      /u/myapp/br/brserver run menu $*

Note- The trailing $* is required.

Copy or link brlistener.conf to the /etc directory.

Place brserver in the directory where it will reside.

As superuser, execute brlistener. It will configure itself as a daemon. If the logfile has been specified in brlistener.conf, it should now be created and have a few messages in it.

At this point you should be able to launch the client (either Windows or MAC, or both)

BRclient computer-ref label-name

Where computer-ref is an IP address or IP name and label-name is the label name in brlistener.conf. computer-ref can be followed by :port-number in the event you wish to use a port other than 8555.

BRclient computer-ref:7543 label-name

To deactivate the listener from your system simply kill the process (-9 not needed).

You will need to put the startup command into either inittab or rc2.d in order to automatically start the brlistener upon bootup.

Linux Install Script

A script has been written to make the listener into a service on Linux. This makes it easy to initiate the listener in a way that it automatically starts at bootup and it is easily managed thereafter. The name of the script is "brlist". This script is self installing. First (as superuser) copy the script into a temporary directory and make it executable. Next place a link to brlistener in /usr/sbin (or copy brlistener to /usr/sbin) and make it executable. Then type "./brlist install". This will copy the script to where it will be needed and it will establish bootup linkage to itself.

Thereafter the listener can be (re)started or stopped as follows

*      brlist start
*      brlist stop
*      brlist restart

Linux Installation Checklist

This installation assumes that both terminals and clients will access the application. Filenames are shown in uppercase. However they will actually be lowercase.

1.) Setup the normal BR terminal based application.

2.) In the BR program directory place BRLISTENER, BRLISTENER.CONF, BRSERVER, BRLIST and BRCONFIG.SVR. Note- under Linux these names are lower case.

3.) BRCONFIG.SVR contains OPTION 30 (if server side printing), a SCREEN statement and GRAPHIC_LINEDRAW SUNKEN, in addition to including the regular BRCONFIG.SYS.

4.) BRLISTENER.CONF STARTUP= this directory EXECUTE=/path/BRSERVER (or a script) CONFIG=BRCONFIG.SVR.

5.) Link BRLISTENER.CONF to /etc.

6.) Link BRLISTENER to /usr/sbin.

7.) Make sure permissions are correct on all of the above files.

8.) ./BRLIST install

9.) If a Linux login script is used to start BR, be sure there are NO echo or other screen output statements, the PATH and other environment variables are set the way they would normally be in PROFILE processing, and that the BRSERVER invocation ends with $*

Also see #Installing Lexi

SHELL CALL (SYSTEM command) PARAMETERS

Concerning Linux shell calls the following flag combinations are prevented-
-W and -C
-R and -C
-W and -R
In other words Without Shell, Restore Screen, and Continue are mutually exclusive options. If more than one is specified at a time error 2222 is generated.

The ability to perform the System command on the server will be able to be disabled for anonymous sessions. Clients will also be able to prohibit all client file operations.

FLAG	RESULT	OMITTED
-s	Server Shell Call	If Windows - shell call
	-Default for Linux	is performed on the client.
-@	Client Shell Call	If Linux - shell call is
	-Default for Windows	performed on the server.
	(search path not implemented on client)

Important Note- Ctrl+] ALWAYS performs a DOS shell call on the client.
PRIMARY

FLAG	RESULT	OMITTED
-c	Windows launches task and	Wait until process is
	resumes BR operation	done up to a maximum of
	(like it did before).	SHELL LIMIT seconds.
	Linux frames the command
	with NOHUP and &.
-r (restore)	Windows always performs shell	Linux forwards standard
	calls in a separate window.	out and stdin data to and
	Linux ignores shell standard	from the client window.
	out data.
-w	Without Shell - Program	-Timeout / Ctrl-A does
	called directly. MUST be a	not kill process..
	program (not script)	can leave orphans.
	-Search Path is used ON
	SERVER only (if no slashes)
	-Does not open a DOS window
	-Does not use Bourne shell -
	enables unfiltered return values
	-Timeout / Ctrl-A kills process.

Note- Currently -w is ignored in Linux standard models.

FLAG	RESULT	OMITTED
blank	Application standard output	see above
	is forwarded to the client.
	However the Bourne shell is
	utilized to initiate the process.
	Can be an executable script.

SECONDARY

FLAG	RESULT	OMITTED
-p	Page Standard Output	Output goes to screen
	-Applies to Linux server only	without pausing.
-m	Minimized under Windows	A separate application
	-Ignored by Linux	window is created.
-M	Minimized and doesn't appear on the task bar.
-t9999	Wait up to specified seconds.	Wait up to SHELL LIMIT
	(client server only)	seconds.

BRConfig.Sys Additions

SHELL LIMIT 9999

Sets default timeout - maximum seconds to wait for a child process. If not specified, this value is set to 240 seconds. Minus one ( -1 ) indicates never timeout unless -t is specified in the System command.

Timeout flag on shell calls - only works on client server model.

Use the config statement "SHELL LIMIT -1" to force unlimited waiting. See BR_CS.Txt for further details.

SHELL DEFAULT CLIENT / SERVER

Sets default location of shell operation and WBPLATFORM$ to WINDOWS / LINUX.

The WBPLATFORM$ system function now returns WINDOWS when running MAC / Linux client server when the config statement SHELL DEFAULT CLIENT is present. This allows programs that test for the Windows platform using WBPLATFORM$ to run in Windows mode in the client server environment. In this case, since shell calls occur on the client, and printing occurs on the client, the program's environment is that of the client's, even though the application and all file IO is actually running on the server.

Client_Current_Dir now supports / SYNC

Remote Printing

Remote Printing is used in the Client Server model of Business Rules!

Valid Business Rules printer names are:

• LPT1: ( port name )
• PRN://10 original BR printer designation - denoting LPT1:
• PRN:/ printer number or name

Normally legacy programs redirect PRN:/ printer names to one of the following (via SUBSTITUTE configuration statements):

• WIN:/ case sensitive printer name substring (partial name)
• PREVIEW:/ name substring
• DIRECT:/ name substring

In Client Server mode printing normally occurs on the CLIENT.

SPOOLCMD governs PRN:/ output, and if @ is not indicated SPOOLCMD runs and prints on the server. There is nothing, however, that prevents SPOOLCMD from forwarding spooled output to clients.

With OPTION 30- (suppress remote printing)

PRN:/ and WIN:/     print on the server
PRN:@/ and WIN:@/   print on the client

Option 31 - suppresses native windows formatting but doesn't suppress printing via Windows. OPTION 31 has been deprecated in favor of DIRECT:/

==========================================================================

 Printer                        Output Method
 Name	------------------------------------------------------------------
 PRN:/	Server:	Linux 	Linux 	   Linux	Windows		Linux
		Opt 30	Spoolcmd   both		Spoolcmd	Spoolcmd @
	------------------------------------------------------------------

 PRN:/	client	server	server	   server	client		client
	direct	lp	spoolcmd   spoolcmd	spoolcmd	spoolcmd


                    PRN:@/, WIN:/, WIN:@/ or PREVIEW:/ 

 Opt 31	client	client	client	   client	client		client
        direct mode ---------------------------------------------------->

 WIN:/	client	server	client	   server	client		client
        native windows printing ----------------------------------------->

 PREVIEW:/
  -or-
 WIN:@/	client	client	client	   client	client		client
        native windows printing ----------------------------------------->

==========================================================================

Notes

OPTION 30 is not allowed on Windows servers.

SPOOLCMD always runs on the server unless it specifies a leading @.
e.g. SPOOLCMD @ print.bat [SPOOLFILE] runs print.bat on the client.

Ctrl-P only works at a LINPUT statement or at a command prompt.

Client side reports are always created in a spool file on the client. This includes both WIN:/ and 'SPOOLCMD @' reports.

Two SPOOLPATH statements are allowed, one for the server and one for the client. The client SPOOLPATH should have '@' right after the SPOOLPATH keyword (e.g. SPOOLPATH @ ...) to designate where on the client spool files should be placed.

The config statement

SPOOLCMD  @  print.bat [SPOOLFILE]

Causes print.bat to be issued ON THE CLIENT in the client current directory.

Direct Printing

DIRECT:/ can be used in lieu of PRN:/ to ignore SPOOLCMD. DIRECT:/ is synonymous with PRN:/ except that SPOOLCMD doesn't apply to DIRECT. ( DIRECT:/ is equivalent to specifying WIN:/ with OPTION 31 on. )

Now Parametrized Printer Substitution statements are now supported along with several other NWP enhancements, including shading, boxing and pictures.

Printer_List()

Printer_List() is a system function that loads an array with local printer definitions.

An example of its use:

10 DIM A$(1)*1000
20 Printer_List(A$)
30 PRINT MAT A$

This will print a list of printer names with each followed by their respective @port-name.

The array A$ will be redimensioned by the system to the correct number of elements, but you must first dimension the length of the elements as shown in the example. Microsoft OneNote tends to include a very lengthy printer definition.

Other Client Server Operations

Copy Files

See Copy#Client Server.

Miscellaneous

• Any names containing blanks must be enclosed in quotations.
• The WSID may be set in the CONFIG file according to username. See BRConfig.Sys for more information.
• We use TCP/IP only (not UDP).

Client Server Extensions

The Edit command now works with client server.

Client Exists() is now supported.

Client Server Reconnect Configuration Statement

This Client Server Reconnect Configuration Statement can be used in versions 4.3 and higher.

CLIENT_SERVER RECONNECT_AFTER=20   RECONNECT_TIME=300

The client will attempt to reconnect to the server after RECONNECT_AFTER seconds (default is 20 seconds).

RECONNECT_TIME= specifies the maximum time to be spent attempting to reconnect (default is 120 seconds) before aborting the session.

When a client is attempting to reconnect, it displays the session number it is using. The normal client login window will contain a check box that facilitates the entry of a reconnection session number. This allows reconnection from another workstation.

Troubleshooting

Sometimes client server will disconnect when executing a particularly long/slow command. In these situations, setting this command to higher values may help. Setting both values to 999 seems to work in most cases.

Caution should be used when setting this value as the workstation will appear to "Lock up" while it is waiting, and if the server actually fails, the client will wait until the time limit has been reached.

Client Server Firewall Concepts

Client Server runs on a File Server and uses TCP communications to connect with it's clients.

BRListener uses PORT 8555 by default. We recommend that you use a different port of your own choosing for security reasons.

Remember that the Allow logon locally Policy will need to be enabled, particularly if running on a domain controller.

In addition an Inbound policy for C:\Windows\system32\brlistener.exe should be set for the brserver port.

Client Server Router Concepts

In order to use Client Server over the internet, you will need to configure your router.

While you can assign a dedicated IP address to Client Server, you may simply elect to use [NAT] and [Forwarding] or Port Forwarding to forward TCP Port 8555 (or your specified port) to your server.

Many Routers provide not only forwarding, but also firewall capabilities. Make sure that your router has been configured to allow inbound traffic over port 8555 (or your specified port).

CLIENT_CURRENT_DIR EXTENSION

The third parameter of the DRIVE statement applies to client-server operations. It will still be ignored for standard model operations. The third parameter, if it begins with \\ or X: ( or any mapped drive letter followed by colon) will indicate the OS full path (relative paths not allowed) to the initial client directory for the drive referenced by that drive statement. In effect this provides a client fullpath for each drive statement. Essentially, the third parameter specifies for the client what the second parameter specifies for the server.

If this parameter is not specified or does not begin with \\ or X:, then the client current directory will still be the client startup directory.

CLIENT_CURRENT_DIR supports the following parameters:

• Full path – specifies use this path for all @: ( single colon ) file references.
• SYNC – Treat each BR Drive individually and when you CD on the server perform the same CD on the client for that respective drive.
• OFF – Use the client startup directory for all @: references.

The default mode is OFF.