RoBridge Perl Server

RoBridge Perl Server

A Performance Enhancement

The Perl Server keeps multiple perl applications pre-compiled and in memory waiting to be executed. It will allow you to save the time that your system would be compiling the perl application before it runs it.

This server is applicable only to Unix. Window NT has a different approach, such as .exe filters.

The Perl Server is two programs: RoBridge.pl and RoPerlServer.pl. RoBridge is supplied complete, and you do not have to modify it. RoPerlServer.pl, on the other hand, does require customization. More on this later.

RoBridge.pl is what is actually executed by the WEB server. You remove the original perl applications, such as ItemList.pl and ItemGet.pl, and put symbolic links by these same names all to RoBridge.pl. The next time the WEB server runs one of these programs, RoBridge will be run. RoBridge.pl is the interface to the RoPerlServer.pl. If the RoPerlServer.pl server is not running, RoBridge.pl will start it. From that time on, RoPerlServer.pl remains listening.

RoPerlServer.pl is a true server daemon. It waits in memory waiting for a connection from RoBridge. When a connection is made, all the information is transferred from the browser to RoPerlServer.pl through RoBridge.pl. Once RoPerlServer.pl has everything it needs, if forks to actually run the application. The parent server then begins listening for additional connection requests by RoBridge.
How to Create RoPerlServer.pl

RoPerlServer.pl is divided into two basic sections: the code for the server and the code for all the applications. There is a sequence of lines:

#----------------------------------------------------------------------
#----------------------------------------------------------------------
# RoAccess server modules/programs follow. add after here
#----------------------------------------------------------------------

Put all the applications and all the needed "require" files after it. For instance, you might copy ItemGet.pl, common.pl, common2.pl and cgi-lib.pl all after these lines. At that point, RoPerlServer.pl is complete. You then save the original ItemGet.pl, and in its place put a symbolic link from it to RoBridge.

If a RoPerlServer.pl perl server is currently running, it must be killed. The next time RoBridge runs, it will start the new RoPerlServer.pl and will have your latest applications. When RoPerlServer.pl starts running the first time, it is compiled as would any perl application. However, since it waits in memory to run the applications later, it never needs to re-compile the code you included after the above lines. However, if you do not copy all the "require" run-time included files, then they will be included and at run time compiled each time the application is run.

RoPerlServer.pl is highly automated. When it communicates with RoBridge.pl, it asks the name of the application that it is to run. It then runs the corresponding application. For instance, if the application being run is ItemGet.pl (via a symbolic link to RoBridge.pl from ItemGet.pl), then RoPerlServer.pl calls a procecure/subroutine named: ItemGet_pl. Notice the name of the subroutine it calls must be the name of the application, less the ".pl" plus "_pl", or another way, the period is replaced by an underscore.

Programming Considerations:

If you put a symbolic link to RoBridge.pl from an application, but that application was not made a part of RoPerlServer.pl by the copying procedure above, it will fail. This is because the subroutine RoPerlServer.pl will finally call will not be there, and RoPerlServer.pl will terminate. Example: if you do a symbolic link from Test.pl to RoBridge.pl, and have not added Test.pl to build_RoPerlServer.pl, RoPerlServer will attempt to call subroutine Test_pl(), won't find it, and will fail.

No duplicated procedure names are permitted. If two different applications each define a procedure by the same name but each does something different then the copying operation will place both in RoPerlServer.pl. Only the last procedure by a name is used, so one of the applications will call the wrong procedure. To solve this, make sure no procedure names are duplicated between any applications you want to load into RoPerlServer.pl.

The way to tell if subroutine names are unique is to issue the following command:

  grep "^sub " app1.pl app2.pl app3.pl | sort | uniq -d

This says to look for all lines that start with "sub space", the way all procedures are defined in RoAccess. The next two steps will tell you which ones were duplicated. Be sure to put one space between the "sub" and the "procedure name" in the applications for consistency.

Example: if there is a subroutine display_TEXT() in both application_a.pl and application_b.pl, then you should change the names so they are not the same, such as app_a_display_TEXT() and app_b_display_TEXT(); That way when both files are concatenated into RoPerlServer.pl, the subroutines names will not conflict with each other.

After adding all the application files by copying, compile RoPerlServer.pl by:

perl -c -w RoPerlServer.pl

and check for errors. The -w option will emit warnings about unused variables and other things that might actually be a problem.

Do Not run RoPerlServer.pl by hand. When RoPerlServer.pl is run, it creates a temporary directory and some files. These files and directory will get the ownership of the user running it. When RoPerlServer.pl is run by the the WEB server, its user id is "nobody" in most cases, for security reasons, so its files and directory will be owned by "nobody". However, if you should run RoPerlServer.pl by hand, and those special files and directory don't exit yet, then they will be created owned by you. Even, after you kill it, those files will exist. Then when the WEB
server runs RoPerlServer.pl, RoPerlServer.pl will not be able to access those files and directory because they are owned by another owners and will cause RoPerlServer.pl to fail in unexpected ways. If you insist on running it by hand, and there are some reasons why it is helpful, after you have, be sure to kill RoPerlServer.pl running in memory and remove all its temporary files. A word to the wise....

All the configuration information for RoPerlServer.pl is in the standard RoAccess configuration file: AConfig.pl. There are a number of parameters, including a temporary directory.

One parameter allows you to choose what kind of connection to make, and can have a great impact on your security. If you choose a standard Internet Socket, then you must block access to your machine from the outside by a firewall. If you choose a Domain Socket, you are secure because a Domain Socket is really a local file which no one outside your system can access. Obviously, we highly recommend Domain Sockets. The last time we asked, the Rochade Server only supports the more common Internet Sockets, so unless its port is blocked outside by your firewall, anyone with Autopilot on the outside can access your data even if they have insufficient Autopilot privileges.

NOTE: do not use the "apache" flag in AConfig.pl. It does not support non-parsed headers.

How Do I Code an Application?

You will typically copy an existing application and then convert it to your new application. If you want it to be able to be loaded into the Perl Server, in addition to the "no duplicate procedure names", you must have you application run as a procedure/subroutines. The following are a few of the lines from ItemGet.pl:

ItemGet_pl(); # main RoAccess perl server call
#----------------------------------------------------------------------
# ItemGet_pl
# now just a subroutine call
#----------------------------------------------------------------------
sub ItemGet_pl
{
local($tIt);
local($ItemGet_target) ;
local($ItemList_target) ;
....
The very first executable line in any application must be a call to a subroutine with the same name as the application, followed by "_pl". This allows the RoPerlServer.pl to cal the appropriate application by just a simple subroutine call and allows you to only have to copy you application to the bottom of RoPerlServer.pl. Notice above that for application ItemGet.pl, the first line is a call to subroutine ItemGet_pl and the next few lines encapsulates the ItemGet application into a subroutine. This "main" procedure is then free to call any procedures defined later in ItemGet.pl or in any of the ADK took kit library.

Short rules for adding a new application to RoPerlServer.p:

The initial code must be enclosed in a subroutines named xxx_pl() fir the application is xxx.pl

The first line of xxx.pl must be a call to xxx_pl().

None of its subroutines must have the same name as other subroutines in RoPerlServer.pl

How Do I automate the building of RoPerlServer.pl?

The utility build_RoPerlServer.pl will automatically build it for you. It is located in the cgi-bin directory. It takes the RoPerlServer.pl plus a list of the libraries and application files to merge, and then writes the results to RoPerlServer.new .

Here are the steps:

Go into a directory that has all the small version of the application perl files.

View the source to the script build_RoPerlServer.pl to see what files will be included. Make any changes to the list of files. Also, set or reset the flags if you want the comment lines and/or the debug lines to automatically be stripped in the process.

Run build_RoPerlServer.pl which will create RoPerlServer.new

Copy this to the cgi-bin directory

Kill any currently running copy of RoPerlServer.

With your WEB browser, run any application that is linked to RoBridge.pl

You new RoPerlServer.pl is not active and waiting for connection requests.

The following are a few lines of build_RoPerlServer.pl:
@files=
    (
    #----- put applications/screens here
    "ItAddDo.pl",
    "ItAddQ.pl",
    "ItemDo.pl",
    "ItemGet.pl",
    "ItemList.pl",
    "Login.pl",
    "SelAppl.pl",
    "SpeedTst.pl",
    "StrdRepQ.pl",
    "TypeList.pl",
    );
The common libraries are loaded once. Then all the applications that have been coded to be runnable under RoPerlServer are listed.

The following is a typical output from the build_RoPerlServer utility:

roaccess>   build_RoPerlServer.pl  
Reading RoPerlServer.pl
Writing RoPerlServer.new
Be sure to rename RoPerlServer.new to RoPerlServer.pl
Removing old common libraries and applications....
  adding file=ItAddDo.pl
  adding file=ItAddQ.pl
  adding file=ItemDo.pl
  adding file=ItemGet.pl
  adding file=ItemList.pl
  adding file=Login.pl
  adding file=SelAppl.pl
  adding file=SpeedTst.pl
  adding file=StrdRepQ.pl
  adding file=TypeList.pl
Done

It first looks for the comment lines that define the starting point for the perl that is to be served,
removes the old perl code, adds a datestame so you can see when it was built,and adds the new application code following it.