Client Server
The Client Server (or CS) model accomplishes 2 things:
- It integrates Unix with Windows (phase one).
- 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 NT/W2K/XP 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 ME | -- |
| Windows NT | Windows NT |
| Windows 2000 | Windows 2000 |
| Windows XP | Windows XP |
| Vista | Vista |
| -- | Linux |
| -- | SCO Openserver |
| MAC | MAC |
Components
| BRClient.exe | Client - Runs on a workstation |
| BRListener.conf | Listener configuration file (place on server in Windows dir or /etc ) |
| BRServer.exe | NT BR Server Program (location specified in conf file) |
| BRListener.exe | Server Connection Agent for NT (place in Windows\System32) |
| Install.exe | BRListener.exe Installer for NT Server (can be found at the bottom of [br_version]_WinSvr.zip on the web site download section ( http://www.brulescorp.com/brules/download.html )) |
| BRServer.exe | SCO BR Server |
| BRListener.exe | Server side Connection Agent and Server side Connection Agent |
InstallShield Installation Instructions
Before Running Setup Please Read:
TIP: You must be logged in as Administrator in order to run Setup.
- If you have a BR Service running
- 1.) Stop the BR Service on the machine where you intend to install. If your previous installation was done using InstallShield, use "stop BR service" from the Programs/BR Service icon list.
- 2.) You can also stop the BR Service by going to start, run, and typing "install /release".
- 3.) If your previous installation was done using InstallShield, you can remove it by using the Add/Remove Programs feature in the Control Panel. In this case, your BRConfig.sys and license file (brserial.dat) will not be removed. This is to make them available for subsequent use.
- 4.) When you run install, installation will modify your BRListener.conf file if your target directory is different from the one previously specified.
How to use the Program Menu.
After running the installation, you can use the Program Menu to start, stop and test BR Server. In order to test the server, the client application is also included in this package. To test client and server, simply click the "test client-server" icon in start/programs/BR Server. This will start the BR Client.
- Release Notes
After the Setup is finished, please read the Release Notes, which are accessible from Programs/BR Server menu.
- Client-Server Notes
These notes are also available from Programs Menu. You will find useful information on how to configure, start, and use the service, or how to manually install this service.
Installing Lexi
BR programs are much easier and faster to edit if you're using an External Editor, such as MyEditBR, that has Lexi installed. Lexi is a BR lexical pre-processor which allows you to edit programs without line numbers.
Lexi can be installed in MyEditBR with these simple steps:
- ) Download LEXI from SageAX.
- ) Unzip Lexi.zip into "C:\Lexi". You must use this directory in order for the automatic installation to work.
- ) Copy your own brserial.dat file into this directory (C:\Lexi).
- ) Launch MyEdit.
- ) Select Tools -> Configure User Tools from the menu, and click the Import Tools button. Select the "Lexi.mut" file that came in Lexi.zip.
Installing Lexi in Notepad++.
Installing Lexi in Sublime.
Manual Installation Instructions
WINDOWS-
First modify the BRListener.Conf file and copy it into your Windows directory on your NT 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
loglevel= leave at 10 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 STDERR= EXECUTABLE= Pathname of BRserver executable. Note- You can now initiate an application from 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
After the brlistener.conf file is in place on the server, install (activate) the brlistener.exe NT service on the server. This can be done by placing BRlistener.exe in the Windows\System32 directory and then logging in as administrator and running Install.exe. Once the listener is installed as a service, it will automatically be invoked each time the server is rebooted.
The brlistener.conf file is processed only at the time the listener is started. So if it needs to be changed, you must uninstall (see remove below) and reinstall the listener to activate the revised conf file.
At this point if installation is successful NT Diagnostics/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'.
TO REMOVE the listener from your system, the install program may be used by typing install /release.
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.
UNIX- (first read the Windows install instructions)
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 ]
00000 or -
[ 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
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 set up appropriately 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 SCO, or both)
BRclient computer BR ( 8555 )
Where computer is an IP address or IP name and BR is the labelname in brlistener.conf.
To remove the listener from your system simply kill the process (-9 not needed). This may be handy for restarting the listener - especially since its configuration file is only read when it starts.
You will need to put the startup command into either inittab or rc2.d in order to automatically start the brlistener upon bootup.
LINUX-
You should install the listener and the server the same as you would for Unix.
A script has been written (brlist) 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.
- 3.) BRCONFIG.SVR contains OPTION 30, 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 script is used, 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 $*
SHELL CALL (SYSTEM command) PARAMETERS
Concerning Unix 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 Unix | is performed on the client. | |
| -@ | Client Shell Call | If Unix - 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. | |
| Unix frames the command | ||
| with NOHUP and &. | ||
| -r (restore) | Windows always performs shell | Unix forwards standard |
| calls in a separate window. | out and stdin data to and | |
| Unix 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 Unix 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 Unix server only | without pausing. | |
| -m | Minimized under Windows | A separate application |
| -Ignored by Unix | 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 unix / aix / 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 / @S
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
- Version 4.1 will be provided in client-server form for SCO, Linux, AIX, MAC and NT/Win2K/XP servers. BR will also be available in the combined (traditional standard) 4.0 format for Windows platforms only, and in the 4.1 standard model on all of the above platforms.
- The client-server keepalive handshake timeout was extended by a factor of ten. This may reduce disconnects.
- 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.
- BR's method for maintaining a keepalive connection was changed to not use UDP. So we're back to using only one type of IP protocol- 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 ERROR_AFTER=180 EXIT_AFTER=300
The client will attempt to reconnect to the server after RECONNECT_AFTER seconds (default is 20 seconds).
ERROR_AFTER generates a BR error and awaits for reconnection (default is 120 seconds).
EXIT_AFTER generates a BR error and continues in unattended mode ( no client IO allowed - exit at next keyboard wait ). This is the normal exit from an unrecoverable disconnect (default is 240 seconds).
If both ERROR_AFTER and EXIT_AFTER are specified, EXIT_AFTER will terminate an ERROR_AFTER wait.
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.
Client Server Firewall Concepts
Client Server runs on a [File Server] and uses TCP communications to connect with it's clients.
Typically, [BRListener] uses PORT 8555
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 port 8555.
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 to your server.
Many Routers provide now only forwarding, but also firewall capabilities. Make sure that your router has been configured to allow inbound traffic over port 8555.
CLIENT_CURRENT_DIR EXTENSION
The third parameter of the DRIVE statement will apply 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 will provide 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 will support 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.