Install Notes

First, we are always available to help you with your installs.  You do not have to be a "RoAccess" expert.  We can make your configuration files for you if you wish.  We can then step you through on the phone the installation and the Installation Verification Tests and other screens to let you know your installation is working fine.  So don't hesitate to call us.  We are here to make your life easier.

However, there are some powerful "RoAccess Options" that can be set.  By looking at roaccess/cgi-bin/AConfig.pro and http://www.roaccess.com/ro-access/htdocs/help/AConfig.htm, you can view their description and how to set them.

There are two main configuration files: AConfig.pl and RoAccess.ini.  While you can create them yourself, we prefer to provide you with your initial ones so you can come up faster.  Then you can make customizations.

The site configuration parameters are enclosed in either ' apostrophes or " double quotes.  Use ' when the value is does not need prior values substitution, like a complete file or directory name.  Use " quotes when prior variable substitution is needed inside the current parameter.

Note that file names always use "/" slash (not the "\" Windows backslash).  RoAccess will automatically convert it to a backslash as necessary with dealing with Windows.
 

Typical Installation Overview

  • Install a WEB server
  • Install perl
  • Install Autopilot if on Windows or install batch client if on Unix
  • Install RoAccess files into WEB server DOCUMENT_ROOT directory of roaccess
  • Make index.html the default page to bring up for the roaccess directories
  • Set cgi-bin, user_cgi-bin, and bin subdirectories executable
  • Make the two tmp directories writable (click here).
  • Install the AConfig.pl, no_echo.cli and RoAccess.ini files you get from us
  • Import ROA_PROC.001 into the AP-PROC database
  • Import the RoAccess model (RIM) IMROACC.001 into your AP-DATA database.  Gen it
  • Get a Java Applet license key from RoAccess support
  • Test the installation using http://yourserver/roaccess/Test.html
  • Test the versions of the supplied Stored Procedures

 

 

Quick Install Summary

Unix Installations:

    • You must install a WEB server, such  Apache or Netscape Enterprise, etc.
    • You must install perl
      • Have the perl executable in /usr/local/bin/perl, or create a symlink to there
    • Batch Client
      • You will need the rochade/bin/roclictu batch client
    • Create the roaccess directory under your WEB Serve root
    • ungzip and Un-tar  the distribution file
    • make roaccess/cgi-bin and roaccess/user_cgi-bin directories executable in WEB Server
    • Proceed to Common for All WEB Servers

 

 


 

Windows Installations

For ALL Windows installations, use the 8 character names for directories and file names when making entries into the cgi-bin/AConfig.pl file.  For example use:

$ro_dir='c:/progra~1/rochade';   # CORRECT

rather than

$ro_dir='c:/Program Files/Rochade';    #  WRONG

Using the 8 character names assures all the Java Applets and third party software we supply will always work.

IIS 4.0 and Higher

    While IIS 4.0 and 5.0 have a lot of nice features, they frequently incorrectly set themselves up.  We have had many,  many complaints about how sometimes setting up a WEB site works and sometimes does not, and the they have had to re-do the installation.  Below is a sequence of steps that gets around a number of the IIS bugs.  It basically centers around creating virtual directories.  To IIS code to set up virtual directories make mistakes and many time mis-configures itself, so do these steps.  Once IIS configures itself correctly, it runs great, but the bugs in IIS and the Management Console can be very frustrating:

    • You will need perl installed.  It can be obtained from www.activestate.com, or from our download site.
    • Note: DO NOT install RoAccess until the last step, strange as this may seem.
    • First create the directory where you intend to install RoAccess, such as: C:\inetpub\wwwroot\roaccess See the hyperlink to the "pictorial description" below for help.  If you don't follow these steps in this precise, you may have problems.
    • Then using the IIS Services Manager Management Console, create your new WEB site for this directory
    • Then using Windows Explorer or a DOS box, create two sub directories of this directory:

      •      C:\inetpub\wwwroot\roaccess\cgi-bin
           C:\inetpub\wwwroot\roaccess\user_cgi-bin
    • Then create virtual directories for cgi-bin and user_cgi-bin.   Do this by clicking on your newly created WEB site, and select NEW/Virtual Directory.  The first name is "cgi-bin" and the complete path would be C:\inetpub\wwwroot\roaccess\cgi-bin.  Likewise do this for user_cgi-bin.  Note: after you create the cgi-bin and user_cgi-bin virtual directories, IIS shows you have instead cgi-bin2 and user_cgi-bin2, IIS has mis-configured itself (a very common problem, but is hard to un-do), call us for help.  IIS is loaded with bugs, but once it gets configured, it runs fine.
    • At this point, unzip the RoAccess files into c:\inetpub\wwwroot\roaccess
    • Your IIS Web Server should be correctly configured, now.
    • Proceed to Common for All WEB Servers


    Click here for a pictorial description of the above steps.  Note: this shows first loading RoAccess and then making the virtual directories.  We recommend that in steps above you just create the empty directories, make them virtual, and if that works, then load RoAccess.  If you have any questions just give us a call and we can explain the details.


    Windows Apache WEB Server

    Apache for Windows has been found to be an excellent WEB server for both NT and Unix.
     

    • AConfig.pl:  Apache usually installs itself into c:\program files\apache group\apache.  However in general files and directories with blanks are a problem with WEB servers.  Therefore, do not put blanks into any AConfig.pl file or directory entries.  Instead use the "8 character file and directory name" instead.  Example:

      • C:/Program Files/Apache Group/Apache/htdocs/RoAccess/bin/dot.exe should be changed to 
      C:/Progra~1/Apache~1/Apache/htdocs/RoAccess/bin/dot.exe'.
    • Apache does not set the DOCUMENT_ROOT environment variable, so you need to set it in AConfig.pl.  Note this directory path uses NO blanks.  Add this line to  AConfig.pl:
        • $ENV{"DOCUMENT_ROOT"}="C:/Progra~1/Apache~1/Apache/htdocs";
    • By default, Apache looks at the first line of the perl applications to find where perl is installed.  This works fine for Unix, but perl installs itself in a different place for Windows.  Instead, add the following line to the top of your apache\conf\httpd.conf file to tell NT to use the Registry to locate where perl is installed:
        • ScriptInterpreterSource registry
    • When adding the ScriptAlias entries, to set roaccess\cgi-bin and roaccess\user_cgi-bin as executable and and when specifying any other file or directory names, only use lower case file and directory names. Do not mix upper and lower case.   Stick to lower case only.  Here is an example of how your two ScriptAlias lines might appear:
        • ScriptAlias /roaccess/cgi-bin/ "C:/inetpub/wwwroot/roaccess/cgi-bin/"
ScriptAlias /roaccess/user_cgi-bin/ "C:/inetpub/wwwroot/roaccess/user_cgi-bin/"

    RoAccess on Windows 2000/2003/XP Professional

    If you want to install RoAccess on a PC running Windows 2000/2003/XP Professional, you must add the Internet Services Component, which happens to be IIS 5.0.  RoAccess and Rochade run great here, even though this is not a "server" platform.

     

    RoAccess on Win98/Win95

    This is not officially supported by RoAccess Support.  We suggest you use XP professional. But we know there will be many who will want to do this.  Below are some helps, but we cannot help you much here, because it is in many cases trial and error.

    • Win98/95 is not a very good platform.  IIS does not run on Win98/95 because of that.  However, you may desire to development on a Win98 platform for convenience.
    • First, we suggest you run the MicroWEB server on Win98/Win95.  Microsoft's PWS (Personal WEB Server/Peer WEB Services) runs sub processes in a popup DOS box, which is very irritating, as you will see.  The MicroWEB Server, however, runs them silently.  You will like it much better.
    • Create your ro-access directory under your WEB Server root,

      •   like c:\inetpub\wwwroot\roaccess
    • unzip the file, and install into that directory
    • make roaccess/cgi-bin and RoAccess/user_cgi-bin executable in WEB Server and make them virtual directories

      • Proceed to Common for All WEB Servers

 

 


Common for All WEB Servers
 
  • Proceed to install:
    • cgi-bin/AConfig.pl - main configuration file we will send you or you can create yourself.
    • config/no_echo.cli - we will send you
    • config/roaccess.ini - we will send you, or you can create yourself
  • The do initial tests using the Installation Confirmation Screen:

    •     http://yourserver/roaccess/Test.html

 

RoAccess.ini file:

Note: you can skip the section initially if you let us configure your initial RoAccess.ini file.  It's a bit cryptic, and your looking
at what we send you will help you immensely on understanding it.  
This file format is required by the Rochade client and is specified by ASG, so we can't make it any easier or meaningful for you. Here is the info for your ro-access.ini on your server.
This file can be found in the "install" directory.  If you are running RoAccess 5.3, then the sections for code pages and messages will need to be added, including the $IMPORT line to activate them from your main TAGS, such as ROA_FIRST_SERVER, ROA_SECOND_SERVER, etc.
Put this file in your RoAccess/config (Unix) or RoAccess\config (Windows).
Below is a sample RoAccess.ini file using a Unix Rochade 5.0-5.2 installation:
;-----------------------------------------------------
; This is a sample .ini file for RoAccess to use for a 5.0-5.2 Rochade installation 
;   You do not have to name it rochade.ini.  You just
;   specify in AConfig.pl the name and location of
;   this file.
;
; You can define multiple Rochade Servers or
;   virtual servers, where you have multiple databases
;   served by the same Rochade Server, but you want different
;   Databases associated by a Name.  This way, you can have
;   development, test and production servers on different
;   Rochade Servers or the SAME server.
;   For example, if the SECOND_V defined DEVELOPMENT-PROC
;    and DEVELOPMENT-DATA as its two database, then RoAccess
;    will handle them just as if they were on different servers.
;-----------------------------------------------------
;
;
;-----------------------------------------------------
;RoAccess First or Only Server
;-----------------------------------------------------
[ROA_FIRST_SERVER]
STARTUP=@/usr/local/rochade5/appl/no_echo.cli
LASTRC=HALT; T
MODE=BATCH
SERVER1=FIRST_S
LANG=E
VARS=FIRST_V

;-----------------------------------------------------
; If you have a second server, use the SECOND sections
; If you want 3 or more servers/virtual servers, then
;  just cut and past sections changing SECOND with THIRD,
;  etc, and put the right host access and database 
;  declarations.
;-----------------------------------------------------
[ROA_SECOND_SERVER]
STARTUP=@/usr/local/rochade5/appl/no_echo.cli
LASTRC=HALT; T
MODE=BATCH
SERVER1=SECOND_S
LANG=E
VARS=SECOND_V

;-----------------------------------------------------
; Define the databases/permissions for each Server
;   Note, the second server has only TWO databases
;   declared, while first server has 3.
;-----------------------------------------------------
[FIRST_V]
DB1=AP-DATA
DB2=AP-PROC
DB3=AP-TEST
DB1_PROT=U
DB2_PROT=U
DB3_PROT=U
DB1_FUNC=P
DB2_FUNC=P
DB3_FUNC=P

[SECOND_V]
DB1=AP-DATA
DB2=AP-PROC
DB1_PROT=U
DB2_PROT=U
DB1_FUNC=
DB2_FUNC=P

;-----------------------------------------------------
; Define the Host Access parameters
;  In this example, both servers are on the same host
;   but are on different PORTS.
;-----------------------------------------------------
[FIRST_S]
BUFFERSIZE=8192
PORT=8880
HOSTNAME=localhost
COMM=TCP

[SECOND_S]
BUFFERSIZE=8192
PORT=8881
HOSTNAME=localhost
COMM=TCP

 ---- End ro-access.ini for a Rochade 5.0-5.2 installation ---------------------------
Below is a RoAccess.ini file for Rochade 5.3 and above.  Note it has the CODE PAGES section
which you can get from your rochade.ini file and just cut and paste it into
your roaccess.ini file:
;-----------------------------------------------------
; This is a sample .ini file for RoAccess to use  for Rochade 5.3 and later
;   You do not have to name it rochade.ini.  You just
;   specify in AConfig.pl the name and location of
;   this file.
;
; You can define multiple Rochade Servers or
;   virtual servers, where you have multiple databases
;   served by the same Rochade Server, but you want different
;   Databases associated by a Name.  This way, you can have
;   development, test and production servers on different
;   Rochade Servers or the SAME server.
;   For example, if the SECOND_V defined DEVELOPMENT-PROC
;    and DEVELOPMENT-DATA as its two database, then RoAccess
;    will handle them just as if they were on different servers.
;-----------------------------------------------------
;
;
;-----------------------------------------------------
;RoAccess First or Only Server
;-----------------------------------------------------
[ROA_FIRST_SERVER]
$IMPORT=RO_MESSAGES;RO_CODEPAGES
STARTUP=@/export/home/simpson/products/ro-access/config/no_echo.cli
MODE=BATCH
SERVER1=FIRST_S
LANG=E
VARS=FIRST_V

;-----------------------------------------------------
; If you have a second server, use the SECOND sections
; If you want 3 or more servers/virtual servers, then
;  just cut and past sections changing SECOND with THIRD,
;  etc, and put the right host access and database 
;  declarations.
;-----------------------------------------------------
[ROA_SECOND_SERVER]
$IMPORT=RO_MESSAGES;RO_CODEPAGES
STARTUP=@/export/home/simpson/products/ro-access/config/no_echo.cli
LASTRC=HALT; T
MODE=BATCH
SERVER1=SECOND_S
LANG=E
VARS=SECOND_V

;-----------------------------------------------------
; Define the databases/permissions for each Server
;   Note, the second server has only TWO databases
;   declared, while first server has 3.
;-----------------------------------------------------
[FIRST_V]
DB1=AP-DATA
DB2=AP-PROC
DB3=AP-TEST
DB1_PROT=U
DB2_PROT=U
DB3_PROT=U
DB1_FUNC=P
DB2_FUNC=P
DB3_FUNC=P

[SECOND_V]
DB1=AP-DATA
DB2=AP-PROC
DB1_PROT=U
DB2_PROT=U
DB1_FUNC=
DB2_FUNC=P

;-----------------------------------------------------
; Define the Host Access parameters
;  In this example, both servers are on the same host
;   but are on different PORTS.
;-----------------------------------------------------
[FIRST_S]
BUFFERSIZE=8192
PORT=8888
HOSTNAME=localhost
COMM=TCP

[SECOND_S]
BUFFERSIZE=8192
PORT=8880
HOSTNAME=localhost
COMM=TCP

[RO_CODEPAGES]
DESCRIPTION=Codepages-5.3
;
CODEPAGE=@/export/home/local/rochade53/bin/c1252.icp
CODEPAGE_FILES=@/export/home/local/rochade53/bin/c437.icp

[RO_MESSAGES]
DESCRIPTION=Messages-5.3
;
ROAPIMSG.E=@/export/home/local/rochade53/bin/roapieng.imf
ROCLIMSG.E=@/export/home/local/rochade53/bin/roclieng.imf
RORCIMSG.E=@/export/home/local/rochade53/bin/rorcieng.imf
ROSRVMSG.E=@/export/home/local/rochade53/bin/rosrveng.imf
;
ROAPIMSG.G=@/export/home/local/rochade53/bin/roapiger.imf
ROCLIMSG.G=@/export/home/local/rochade53/bin/rocliger.imf
RORCIMSG.G=@/export/home/local/rochade53/bin/rorciger.imf
ROSRVMSG.G=@/export/home/local/rochade53/bin/rosrvger.imf


------- End of Sample RoAccess.ini file for Rochade 5.3 and later ------
If you are running NT, look at your Rochade.ini file (rochade\appl\rochade.ini) to
get the "NT" syntax for the CODE PAGE and MESSAGES sections.  Cutting and pasting
is the recommended way.  Also make sure the $IMPORT line matches.  We have found
Rochade has used two different forms of the $IMPORT command and MESSAGE sections.
Cutting and pasting make sure it is in correct format.
The roaccess.ini file must be  readable and writable by the effective user of the WEB server.   When a WEB server starts up, its configuration parameters define the user it is to run as.  For instance, a Unix WEB server, such as Apache,  might be configured to run under a special non-privileged users, such as "nobody".  Under NT, if you are running NT and MS IIS 4.0/5.0, the Management Console automatically knows the "effective user" for IIS.  By default, it seems RoAccess.ini will be writable.  Rochade writes the result status of the latest access into a variable "LASTRC".  That is why it must be writable.

Beware, some Rochade 5.2 database servers in the past, CHANGE the permissions on rochade.ini every time is starts up, removing world read. You may have to change the startup script to start the database server, delay and then add back the world read permissions. By utilizing ro-access.ini rather than the system rochade.ini, you don't have to worry about the Rochade server removing the read permission you need.
 

Code Pages:

For languages other than English, you will probably be using a code page.  It will handle the translations of "special characters" from Rochade's internal format to your "outside world" format.

If you are using Rochade 5.3+ and a codepage, other than the default 437, then you must make the following type entries (German example):

Your lines probably look like:
CODEPAGE=@/export/home/local/rochade53/bin/c1252.icp
CODEPAGE_FILES=@/export/home/local/rochade53/bin/c437.icp

Change the second one to be:
CODEPAGE=@/export/home/local/rochade53/bin/c1252.icp
CODEPAGE_FILES=@/export/home/local/rochade53/bin/c1252.icp;@/export/home/local/rochade53/bin/c437.icp

If you are using Rochade 5.2 or earlier and a codepage, other than the default 437, then you must make the following type entries into your ROA_FIRST_SERVER, ROA_SECOND_SERVER, etc., sections (German Example):

[ROA_FIRST_SERVER]
CODEPAGE_FILES=1252
CODEPAGE=1252
 

Rochade 5.4+,6.x Notes

 The topics below reference 5.4 a lot, but it's the same for Rochade 6.x.
Many of the settings in RoAccess.ini are taken are taken from Rochade server configuration file.  In Rochade 5.0-5.2 the server file name is: "rochade.ini".  However for Rochade 5.4+, the file is "server.ini".
 
Rochade Version 5.0-5.3 5.4+
  Windows Unix Windows Unix
        Unix
ini file name rochade/appl/rochade.ini rochade/appl/rochade.ini rochade\appl\server.ini rochade/appl/server.ini
batch client file name rochade\bin\rocligxn.exe rochade/bin/roclictu rochade\sbin\roclictu rochade/sbin/roclictu
Unix Shared Libraries
 

The Unix batch client starting with Rochade 5.4 utilizes shared libraries.  We know this is true for Sun Solaris and HP/UX, believe it to be true for AIX.  We do not know about HP/UX.  Run the test "Verify perl can run a cgi-bin script" in the Installation Verification Tests Screen( roaccess/Test.html ), if you get a message like "libroapi.so: open failed: no such file or directory", then the WEB server needs be told to add the rochade/sbin directory to the LD_LIBRARY_PATH environment variable.  The file "libroapi.so" is a shared library (.so) file.  Some shared library files might look like xxxx.so.2 where the .so is inside the name.

Some WEB servers allow you to add "environment variables" that get passed to the cgi programs.  Your other option is to create a wrapper script to execute.

How to Tell if your Batch Client uses Shared Libraries

This is how we had our Solaris Users do it:

First try running the Test1.pl mentioned above.  If you get the missing shared library message, you are using shared libraries.

If Rochade was installed in /usr/local/rochade54, do this:

  • open a telnet session to your Unix RoAccess WEB server system
  • cd /tmp
  • run this command "/usr/local/rochade54/sbin/roclictu

    • If you get a "shared library missing" message, then it is using the new shared libraries, and you will need the change mentioned below.   If you do not get this error message, you do not need to make any changes.
     

    Method 1: Adding LD_LIBRARY_PATH to WEB Server's Environment

    Sun Solaris uses LD_LIBRARY_PATH.  Note: HP/UX uses a different environment variable.  If your WEB server allows adding "environment variables", you need to add LD_LIBRARY_PATH, and it should include the complete path to your Rochade sbin directory.  For instance, if your standard LD_LIBRARY_PATH is

    LD_LIBRARY_PATH=/usr/openwin/lib:/usr/4lib/libxview.so.3.73

    Then you would change it to be like:

    LD_LIBRARY_PATH=/usr/openwin/lib:/usr/4lib/libxview.so.3.73:/usr/local/rochade54/sbin

    This adds one more directory to search for shared libraries.

    Restart your WEB server, so it will receive the new LD_LIBRARY_PATH, and run the Test1.pl from the roaccess/Test.html Installation Verification Screen.
     

    Method 2: Creating a "Wrapper Shell" to set LD_LIBRARY_PATH

    If your WEB server does not allow this, then create the following wrapper script: rochade/sbin/roclictu.sh.  This wrapper is executed instead of the Rochade client.  It then executes the Rochade client.

    Here is a typical AConfig.pl line executing the Rochade client directly:

     $ro_cmd="$ro_dir/sbin/roclictu RO_TAG $ro_ini";

    Here is it modified to execute the "wrapper":

    $ro_cmd="$ro_dir/sbin/roclictu.sh RO_TAG $ro_ini";

    Solaris 

    Solaris uses the LD_LIBRARY_PATH environment variable to list where to search for shared library components.  The Solaris roclictu.sh script is below:

    #!/bin/ksh
export LD_LIBRARY_PATH=/usr/local/rochade/sbin
/usr/local/rochade54/sbin/roclictu $*

    HP/UX

    HP/UX uses the SHLIB_PATH environment variable to list where to search for shared library components.  The HP/UX roclictu.sh script is below:

    #!/bin/ksh
export SHLIB_PATH=/apps/rochade/rochade6/sbin
/apps/rochade/rochade6/sbin/roclictu $*

    Set roclictu.sh as executable, and change the $ro_cmd line in your roaccess/cgi-bin/AConfig.pl file to point to roclictu.sh (instead of the normal roclictu).

    This has RoAccess execute this batch client "wrapper" that sets the LD_LIBRARY_PATH or SHLIB_PATH so roclictu can find its shared libraries.

    Here is a variation that cd's to the executables directory first, then runs the batch client.  This ways the batch client can find its shared librarees.  below is a sample script:.  Only use if the above scripts fail.

    #!/bin/ksh
    cd /usr/local/rochade54/sbin
    /usr/local/rochade54/sbin/roclictu $*

     

    Just to summarize: if you cannot pass the LD_LIBRARY_PATH or SHLIB_PATH to your WEB server via a configuration file, create a shell script that sets it, and then executes the batch client.  The $* parameter on the last line says to pass all the parameters given to the script also to the batch client.  Then tell RoAccess to execute the batch wrapper script rather than the batch client.

    Have problems or questions?  Give us a call.

     


     

    The no_echo.cli file

    There must be a file:
      roaccess/config/no_echo.cli or
      C:\RoAccess\config\no_echo.cli
    that contains only one line: 

     #$OPTION ECHO OFF

    and must be world readable.

     

     

    AConfig.pl/AConfig.pro:

    Again, we recommend you let us create your initial AConfig.pl file to save you time and effort.  RoAccess probably has over 100 options.  You may initially only use a few, but later use many more.  Lets us save you time by making your initial AConfig.pl file.  They you can extend it as required.

    For your initial installation,  create cgi-bin/AConfig.pl.

    It starts with a 

      RoaRequire("AConfig.pro");
... variables that are overridden go here
...
#  end of AConfig.pl
1

    The first line should be"

        RoaRequire("AConfig.pro") ;
     

    Then look at AConfig.pro for variables that will be different in your installation.  Example variables are: $ro_dir, @ro_servers, $ro_tmp_dir, $ro_web_os, and $ro_ini.  The only variables you put in AConfig.pl are those you are overriding.

    When installing new versions of RoAccess,  your AConfig.pl will not be overwritten.

    Note: do not just copy the AConfig.pro and rename it AConfig.pl.  Yes that will work, but this effectively overrides every site parameter variable.   Then when the next version of RoAccess is installed that has a different default value, an new features may not work, which will make you spend a lot of time debugging.  AConfig.pl is meant to only override the necessary default values, so should be a somewhat short file.  Then as new defaults and features are added to the AConfig.pro file, which does get overwritten with each new RoAccess upgrade, the new features will automatically be configured and available.

     

    Graphics Module:

    In directory roaccess/bin copy the correct graphics module to the generic program name:
    There are two programs: dot and neato.  There are multiple versions for various operating systems and versions.
     

    $graphviz_dot='C:/inetpub/wwwroot/roaccess/bin/dot1.4.exe';

    or

    $graphviz_dot='/usr/local/etc/httpd/htdocs/ro-access/bin/dot-1.4.hpux10.20;
     

    Example:
       REM Under NT
       copy dot-1.4.exe dot.exe

       #Under HP/UX 10.20 Unix
        cp dot-1.4.hpux10.20 dot

    Each release of RoAccess may have a  new version, and you should look to get the latest version.   If you don't copy the executable to a generic name, then the $graphviz_dot variable must merely point to the executable name as delivered to you.

    If you are using a Unix WEB Server, then go into the roaccess/fonts directory.  Follow the README directions to install these True Type fonts onto your system.  2003/2000/XPWinNT/98/95 does not need this.  Only Unix.

     

     

    Special Text Attribute: ROA_EXTRA

    Add the ROA_EXTRA text attribute to all of your ItemTypes with binary/blob attributes.

    If an ItemType has blobs, you MUST add the ROA_EXTRA text attribute to that ItemType.

    RoAccess will take it from there. Every time you upload a Blob, RoAccess will record the name of the file and a short description of the file into this "hidden" attribute.  Then when the Blob attribute is displayed, you can know what the original file name was and a description of that file because it is taken from this ROA_EXTRA attribute.

    The attribute ROA_EXTRA is defined when you import the IMROACC.001 file which defines the ROACCESS RIM.  When displaying the attributes for ItemTypes, the ROA_EXTRA attribute is hidden from display, but it is there holding information for all the binary/blob attributes for that Item.   When you declare a graphic to be AutoDisplay by putting the word AutoDisplay in the file description, it is actually stored in the ROA_EXTRA text attribute.

     

     
     

    Import the ROA_PROC Stored Procedures

    Install Stored Procedures

    RoAccess comes with a library of "Rochade stored procedures".  You have to import them into Rochade.

    This contains stored procedures to improve Rochade database throughput.  Since they are procedures, they must go into a procedure database.  They are contained in install/ROA_PROCS.001.   To do this:

  • log into Autopilot as ADM. Select "Open AUTOPILOT Administration".
  • Under the Tools menu, select Import.
  • In the "Import into Database" field, set it to AP-PROC (or whatever your PROC database is)
  • Enter the file name complete with directories for roaccess\install\ROA_PROC.001.
  • Click the Import button.

    • The stored procedures are ready for use.

    A note on procedure databases;  If you have several data databases, and all use AP-PROC for procedures, if you import the RoAccess procedures into AP-PROC, then all your Subject Areas using AP-PROC are ready to go.  That is, you only have to import the RoAccess stored procedures once.

    However, if you choose to put the RoAccess procedures into your data database (be sure to mark this database as P in ro-access.ini) then only this database will have the RoAccess procedures installed.  You will have to import the RoAccess procedures into every data database.  We recommend installing the RoAccess procedures into AP-PROC or whatever your common procedure data base is.

    Verify Stored Procedures are Loaded

    To verify that the procedures are indeed loaded and are the correct version, run this URL: 

      http://yourserver/roaccess/set_cookies.html#proc_info

    Click the "RoAccess Stored Procedure Information" section's button "Get Procedure Info".

    It will interrogate the system and list the versions of the stored procedures and what they should be.  It will also determine which are missing.

    You can do the same by then verifing the procedures were loaded correctly by running this URL in your browser:

    http://yourserver/roaccess/cgi-bin/ProcInfo.pl

    Make sure the versions of the installed procedures match what they should be.

     

     

    Import the ROACCESS RIM

    To enable the extended features of RoAccess, you must import the ROACCESS RIM and add some new ItemTypes to your Subject area for RoAccess to use.

    Import roaccess/install/IMROACC.001 into your DATA database.  It contains the ROACCESS RIM having the the ROA_EXTRA attribute, plus other RoAccess objects, such as ROA_STORED_PROCEDURES and ROA-AP-ITEMTYPE.  GEN this RIM.  Then add the Item Types ROA_STORED_PROCEDURES,  ROA_SYSTEM and ROA-AP-ITEMTYPE  to your Subject Area, re-GEN it.  Then using Administration for that Subject Area,  do a "Reorganize" and an "Update View" to activate these new Item Types.   If you have purchased the RoLoader Spreadsheet Loader PlugIn module,  then also add ItemType ROA_RO_LOADER.

    The ROA_STORED_PROCEDURES Item Type contains information on your Rochade procedure Language report procedures so they can be run from the browser.  You can add a text description, whether the report write text or HTML, plus other things.

    ROA-AP-ITEMTYPE will allow you to add extended metadata to a subject area, such as defining a list of allowable link qualifiers or defining an attribute as an integer with a PIC of I4.  You can display the Attributes in any order you wish.

    ROA_RO_LOADER defines how to load each file of spreadsheet data and allows you to keep documentation about the data file, and even store that data file in Rochade so it will never get lost.

    Rochade has NO capability to store the name of the blob file or any information about it when a Blob attribute is loaded. You have to remember whether it is a picture, spreadsheet or text and what file extension you should give it when it is downloaded. Also Rochade has no capability of giving a short description of the contents of the uploaded Blob attribute.

    To get around this shortcoming, this ROA_EXTRA text attribute is added by RoAccess. You will not see it when items are displayed, because it be hidden from view.    You must add the ROA_EXTRA attribute to all of your Item Types that are to have blob/binary attributes.

    The ROA_SYSTEM ItemType allows you to create Virtual Hierarchical Subject Area, a powerful RoAccess-only feature.

    The ROA_RO_LOADER Item Type is used in conjunction with the RoLoader optional software.  This Item Type must be added to any Subject Areas if RoLoader is to be used.
     

    Details on How to Import the ROACCESS RIM

    This is a bit detailed, but it may help those who are relatively new to Rochade or who have forgotten how to do it.
     

  • Run Autopilot as a privileged user
  • Select "Application/ Open Autopilot Administration"
  • Select "Tools/Import"
  • Select the correct data database. (this does not go into AP-PROC).  It will usually be AP-DATA, AP-TEST, etc.
  • for the file name, enter "/roaccess/install/IMROACC.001" using the Browse button.  It is in the "install" sub directory for RoAccess
  • Click the "Import" button.  The basic ROACCESS RIM has been read in, but must be "generated" to be useable.
  • Select "System/Model Administration/Information Models"
  • You will see a new RIM called ROACCESS, and it will be flagged as "IN-WORK"
  • In the field to the left of ROACCESS, enter "GEN" and click "OK".  This will GEN (generate) the RIM, and it will then be changed from "IN-WORK" to "GENERATED"

    • The RoAccess RIM has been installed, containing some special ItemTypes.  You must add these ItemTypes to your Subject Area(s).

  • Put a "W" next to the RIM that is used by your Subject Area,  and click "Ok". This will bring up a screen listing the ItemTypes for the user RIM.
  • 1) To the left of the "Item Type" text, enter a "S" for New.  By typing in "S" is will bring up a list of existing ItemTypes to select from. This will avoid the problem of possibly mis-typing the ItemType.
  • 2) To the right of the "Item Type" enter "ROA-AP-ITEMTYPE"   and click OK
  • This adds this one new ItemType to your RIM.
  • Do the same above steps 1 and 2 for ItemTypes: ROA_STORED_PROCEDURES and ROA_RO_LOADER

    • You have added these three ItemTypes to your main RIM.  However, you need to GEN your RIM to incorporate these new ItemTypes

  • Go back one screen, and to the left of your RIM's name , enter:  GEN, and click OK.
  • The phrase to the right of your RIM should change from IN-WORK to GENERATED.

    • The above adds the new ItemTypes to your RIM.  Now you must inform the Subject Areas that use this RIM to use the new ItemTypes:  (Bu default, ItemTypes added to a RIM do not automatically appear is associated Subject Areas):

  • Go BACK as far as you can.
  • Select "Application/Administration"
  • Open your Subject Area
  • Select "Status/Suspend"
  • Select "Update/Reorganize".  This now adds the new ItemTypes to you Application, but marks them as "do not show".  You must make the "visible";
  • Select "Update/View"
  • Next to the three ROA ItemTypes, put an X, and click OK.  You should see "+" to the next to these three ItemTypes.
  • The ItemTypes have been added to your Subject Area.
  • Click the "Close" button
  • Select "Status/Put IN-WORK"

    • Exit Autopilot, and bring up RoAccess on your browser.

     

    The  ImInt Java Applets

    The family of Java Applets are licensed, and  you will need a key to unlock them.  Send RoAccess support the URL of how you run RoAccess, and we will send you a "key".   For more information see the two Applet hyperlinks on this page.

    Perl on Unix

    RoAccess expects Perl to be located in the gnu standard location of /usr/local/bin/perl. If you have chosen to install perl elsewhere, you must put a symbolic link from /usr/local/bin/perl to your perl executable.

     

    Tmp Temporary Directories

    RoAccess uses TWO temporary directories. One in c:\tmp\ro_tmp (Windows) or /tmp/ro_tmp (Unix), or you can specify a different location.  Set the permissions for full access by everyone, but default.  This directory is usually created by RoAccess when it is run the first time.  If you have special security needs, you may want to pre-create this directory.

    Beneath your RoAccess installation directory, you must make a directory tmp. It must be writable.  It is at the same level as cgi-bin, images and htdocs. On Unix, make it owned by the WEB server effective user or full access.   On Windows, set the permission to "Full Access" for everyone.

     

    Upgrading to a Newer Version of RoAccess

    Before upgrading to a new version, we suggest backing up your RoAccess directory tree.

    You can upgrade to a newer version by going into the main directory for RoAccess and un-tarring or un-zipping the file. However, first SAVE cgi-bin/AConfig.pl, your configuration file, as a precaution. When you un-tar or un-zip the new files, your AConfig.pl file will not be overwritten.

    Under Unix, the tar file will need to replace read-only files.  Normally, it will just replace the files.

    Depending on your privileges, tar may be unable to overwrite these read-only files. In this case, from the main install directory (.../roaccess) issue the following command:

    find . -type f -print |xargs chmod +w This will make all files writable (but leave the directories alone). Now that the files are writable, then un-tar the distribution file. If you then look at the files, they will then be re-set to read-only.

    If you're running NT, Windows 2000 or other Windows platform, just unzip the RoAccess distribution into the top lever RoAccess directory.

     

    Performance and General Information

    This optional section is not needed for normal installation. It is useful when you want to get the most our of RoAccess, but are willing to allow more maintenance steps to achieve it.

    RoPerlServer Installation

    This is Unix only.  Replace the files of the applications to be run via the RoPerlServer with a symbolic link to RoBridge.pl.  For more information, look at URL: ../htdocs/help/RoPerlServer.htm.

     To activate the various screens that will served by RoPerlServer go into the cgi-bin directory and run script "install_RoPerlServer.sh".  This will remove each current application, and put a symbolic link to RoBridge.pl.

    To de-activate RoPerlServer, go into the cgi-bin directory and run either "install_modular.sh" or "install_monolithic.sh".  These will remove RoBridge links, if any, and copy up the normal executable screens.
     

     

    Constant Connect Servers ( RoDbServer )

    Constant-Connect servers are not "installed".  They are activated by entries in the AConfig.pl file.  For more information look at AConfig.pro and URL: /ro-access/htdocs/help/RoDbServer.htm.

    As part of your bootup, you need to run /ro-access/cgi-bin/CleanRoDbDir.pl
    This is a standalone executable perl script that cleans out the working directory for the RoDbServer.  If the server host crashes, like due to a power failure, some files are left that should be removed before the RoDbServer is started.

    On Win95/NT place a  shortcut to "perl.exe CleanRoDbDir.pl"  in the Startup Group.  When your server starts up, you will see a DOS box pop up during  the "clean" operation.     .

     

    Special Subdirectories

    This is an optional section, only needed in special cases.  There are some special sub directories you receive with the "full" version. The "monolithic" programs are by default not enabled, but you can do so for performance reasons.  But if you do, you will have to rebuild all the programs each time you get a new release of RoAccess.  This performance option has a cost of higher maintenance.  So unless performance is absolutely critical, ignore the "monolithic" modules.

     

    Running Multiple Versions of RoAccess

    You may have specially tailored versions in addition to the latest release. You may want to have several versions of RoAccess available at the same time. One could be configured one way, with another Version configured differently. So you can have multiple versions of RoAccess all pointing to the same or different databases. You would then access them as perhaps: http://your_host/roaccess_production, http://your_host/roaccess_test, and http://your_host/roaccess_development. Then you can switch between them merely by entering a different URL.

    Create a new directory tree for each version, do an install, and copy the AConfig.pl file to cgi-bin. Then point your WEB server to these directories, giving then different logical names.

    If you have questions about this, give tech support a call.

     

    File Permissions

    The WEB server will run with the permissions of whatever user you select. On Unix machines, the files must as a rule have either world read or be readable by the WEB server effective user. The RoAccess configuration files, AConfig.pl, no_echo.cli and ro-access.ini must be readable by the WEB server user. Ideally the files should be readable ONLY by the WEB user.  

    Performance Discussion

    Performance can vary depending on some options you choose.

    One cannot over-emphasize the importance of the speed of the WEB and Rochade server machines. Most screens come up on UltraSPARC machines in sub second times. If the user is instead only using a 133MHz Pentium, the browser execution and screen drawing may add another 50 to 100%. That is, the WEB server will be finished but the browser is still drawing, making it look like the WEB server is the slowdown, but it is the user's workstation which is adding the extra time to complete.

    You receive two versions of the basic RoAccess applications. The first is the normal, modular system, where each application at run time includes other files as needed. This is flexible because if you are making a change in a shared subroutine, then the next time any application runs that uses it, the latest changes will be seen.

    The second is a monolithic file that has all the subroutines the applications needs all packed into one file. Since the general support subroutine libraries in the ADK, such as common.pl and common2.pl, each contain many functions, each application will not use all of them. So the unused subroutines take up memory and compile time. A single file, having only what it needs takes less time to load and run. So, if you are using a stable, production system, use the monolithic programs. If you are doing development work, then use the modular files.  There are two convenience script to install the monolithic or modular files: install_monolithic.sh and install_modular.sh.  For NT, they are install_modular.bat and install_monolithic.bat.

    Make the network between the various machines 1) as fast as possible with 2) as short ping times as possible. It turns out, the ping times are the most important. If the Rochade and WEB servers are on the same machines, no network is used, and communications between the programs runs a lightening speed. But if you put these two servers on different platforms, the pack round trip times can make a screen operation take 2 or more times as long. A slower network can degrade performance even more. Likewise, the faster the network with the smallest possible ping times between the WEB server and the user's workstation improves this operation. Know in advance what the typical network loading will be on the various segments of your network. If part of the network is heavily used, then tremendous slowdowns can be experienced which will be hard to find. To help track this down, RoAccess has a "server" loading test screen that can let you know if the server or the network is the problem. If the screens are coming up slow, but the loading test screens says the server is unloaded, then it is the network. However, if the Rochade server is on another machine, it is possible that machine may be loaded with a long running Rochade query or other tasks.

    First, make sure your WEB server is as idle as possible. Other users running programs, or having the WEB server also be someone's personal workstation can lead to widely variable access times. Make sure all screen savers are set to a blank screen because screen savers that draw picture steal time from the background processes, like servers.

    Screen load times can be measured by going into the Non-Frames mode, and hitting reload. This works very well with MSIE. However when measuring the access times for a screen, hitting "Reload" in Netscape actually adds about 1/4 second to what it takes if the screen is first brought up or re-run by putting the cursor in the Location field, and hitting Return. So, if you are running on a very fast system, like a Sun UltraSPARC, it can seem to add 25% to the execution. Your particular version of browser may or may not take longer for a "Reload".

    Set your Browser to draw graphic after the text. All graphics are sent to the browser with their dimensions in advance, so the browser knows how much room to leave for the graphics. Since text draws faster then graphics, you will see the text first, and while you look at the text, the graphics will complete if they have not already.

    Processor speed vs. Process Creation Time:

    If you look at the typical server loading measurements from the Server Load Test screen, you will notice that a 133MHz Pentium has almost the speed of an UltraSPARC. However, the actual end-to-end time for an UltraSparc system will be a fraction of that of a Win95/NT system. This is because process startup times are extremely faster on Unix and very slow on Windows. So the program while running fast on Win95, takes much longer to be started and then exit, so the processor speed of the Pentium is misleading.

    If possible, use a multi-processor server. For instance, RoAccess was tested on a 10 processor UltraSPARC. 8 users could be added before any slowdown was detected with sub-second response. For multiple users, on a single processor server, they all have to wait for the CPU to become free. WinNT and higher can have multiple processors but Win95 cannot.

    Have as much memory as you can. When a user runs a screens the following processes will be active: the WEB server, the Rochade server, the Rochade client and the RoAccess program. Measure the memory requirements for each, and this much free memory is what you should have as a minimum. If other programs are running, they will need memory, too. If you do not have enough RAM, they you system will start using virtual memory, which uses a tremendous amount of disk I/O, and you response times will degrade dramatically.

    If you are running a Win95/NT server, you should use the PerlIS, ISAPI filter rather than running the standard perl interpreter. PerlIS is a pre-loaded perl that is then mapped to and shared in the memory spaces of the processes. This cut 2 seconds off the load time on a 133 MHz Pentium Win95 server.

    AutoDisplay Images:

    Item Types that have binary attributes containing pictures have two options: merely display an Icon representing the graphic that needs to be clicked on to display the picture, or it can AutoDisplay the image as the screen is drawn. While having graphics display on the screen really look great it takes longer. This may influence how you choose whether to use AutoDisplay.   To enable AutoDisplay, just put the word "AutoDisplay" in the description of the graphics file when you upload it into RoAccess.

     

     

    Information Useful no Longer Current

    The following information may be useful if you have really old equipment or software.  It is kept only as a service to "hackers" and those with really unusual needs. 

    Installing a Windows 95/98/NT Server in General