C Server Pages user Guide. V2.1

What's new or improved at release 2.1


C Server Pages are distributed as binaries for Linux Systems. Binary versions for Solaris and HP UX and Windows NT are comming soon.

Installing from Binary distribution

Unpack the zipped tar file and extract in any directory where you have write permissions. Normally it is done
at /usr/local on unix filesystems :

cd /usr/local
gzip -d CserverPages-b-1.0.gz
tar xvf CServerPages-b-1.0.tar


It is possible to have several instances of C Server Pages in the same machine. Each instance has its own configuration file called manager.conf in the etc. directory. In order to be found by the servers the environment variable TOMANAGER_CFG has to be set and contain the full path for the configuration file.

ksh > export TOMANAGER_CFG=/export/home/....../manager.conf
csh> setenv TOMANAGER_CFG /export/home/....../manager.conf

the start shell script "toinit" at bin directory gives a default value to this variable.

You need to determine
        The server and port where the session router is going to serve (6500 as default).
        The number of session servers you are going to run (For developing one is ok, for production environments you may need more)
        The machine or machines names and port where the session managers (TO_imanager) are going to serve (the localhost and port 6502 as default)
        The directory where you are going to place the Dynamic Elements binary files (the objects directory as default)
        The directory where you are going to place the templates pages (the templates directory as default)
        The directory where you are going to place the Server Pages binary files (the cspages directory as default)

When you have this information edit the file manager.conf and give values to the variables:

components_directory : directory for Dynamic Elements binary files
templates_directory: templates root directory
c_pages_directory:directory for C Server Pages binary files
cache_c_pages : (yes/no) when no, flush and load the dynamic pages with each query, interesting for developing
time_out_template: template to execute when the session has time-out
route_server_log_file : file for routeserver tracing (not yet active, using stderr)
route_server_log_level : Log level for routeserver 1 to 3
routes_timeount_minutes: time-out in minutes for session routes in routeserver in the routeserver routetable
timeout_minutes : time-out in minutes for sessions in the session manager TO_imanger
online_servers : Active session manager (TO_imanager) server for this instance (look at etc/manager.conf file)
port_base : the first port for this set of session servers
server_name : server name where this set of server is going to run
server_IP : Ip address for the machine where this set of servers is going to run
num_servers : number of session managers (engines) for this set of servers. The engines take successive ports.
startup_page : This is a page which will be executed when the session manager TO_imanager starts. The page cannot use the Session or Request objects.
start_session_page : This page, if set, is executed automatically just after creating a new session. All the standar objects are availables at this page. The standar object Response is redirected to the TO_imanager standar output.
end_session_page : This page, if set, is executed automatically just before the session is destroyed because of the expiring session timeout. The standard object are availables except Request. The Response objects is redirected to the TO_imanager standard output.

The default values may be good in many cases.


Copy the executable TOCgi to the cgi-bin directory of your web server
Execute toinit from the bin directory (your terminal  will hang while the service is running until you press Ctr-C to finish.

A message like this must appear :

Route 1  Host: tgonzale_ptl     Port: 6502      Max_Sessions: 120
Routeserver Listening at port 6500
Registering Dynamic Class Dyn_Counter
Registering Dynamic Class Dyn_Date
Registering Dynamic Class Dyn_GetSession
Registering Dynamic Class Dyn_Href
Registering Dynamic Class Dyn_PrintAll
Registering Dynamic Class Dyn_Session
Registering Dynamic Class Dyn_SetSession
Registering C Page CSPage_add_options
Registering C Page CSPage_hello
Registering C Page CSPage_hello_world
Registering C Page CSPage_if
Registering C Page CSPage_menu
Registering C Page CSPage_tabla
Listening at port 6502

At this point you can ask your browser to show the C Server Pages welcome


and enjoy it.

TOCgi must know which machine and port the routeserver is running. First TOCgi look at the environment variables TO_ROUTE_SERVER and TO_ROUTE_PORT If they are not set, it takes "localhost" as server and "6500" as port.
If you do not use the default values, be sure that TOCgi reach those environment variables. For example, using apache web server and with routeserver running at host venus and port 1700, you have to insert in the httpd.conf file the following directives :


Please check your web server documentation for details.

Running the Servers

CSPages include two different servers: the routeserver and the session manager server TO_imanager.

Routeserver is responsible for assigning new sessions identifiers and the session manager which is going to manager that new session. It takes in mind the number of sessions of each alive session managers and the max. number of sessions that each session manager can manage.

The session manager process TO_imanger is responsible for running the application (C Server Pages and templates with dynamic elements). Each session manager can manage a number of sessions given through the configuration file. You can balance the load, assigning different number of sessions to different session manager in different machines, taking in mind for example the machine capacity.

Both processes use the same configuration file, determined by the environment variable TO_MANAGERCFG . In the distribution this file is called manager.conf and is located in the CserverPages etc directory.

To run the routeserver you have to give the service port as parameters. By default it begins to run in the 6500 port.

To run in the port 7001 start routeserver as follow :

routeserver 7001

This server load a route table with information about the session managers services, it is, at which machines and ports are they running.

After the routeserver has this information is necessary to run as many session managers as said to the routeserver.

To run the session managers call run as many TO_imanagers as you needs putting the service port as parameter. Example, to run a session manager serving in the 7002 port :

TO_imanager 7002

You can specify the server alias in order to take one special configuration for that server from the configuration file :

TO_imanager 7002 SERVER1

Configuration of Several Applications

Several instances of cserverpages can be running identified by the cgi name. To do that, you have to use a different routeserver and an set of TO_imanager processes. The environment variables which say the routeserver server and port are :

<appname>_TO_ROUTE_SERVER and


You have to put this environment variables to the new cgi program, inserting a couple of lines in your http server configuration file.

For example, consider to have two different applications in the same machine called shopA and shopB.

Make a copy of CserverPages directory and configure the manager.conf file at each copy of CserverPages. Update also the file toinit in the bin directory, to start routeserver and TO_imanager processes at the right servers and ports.

Insert the rigth enviroment variables in your httpd configuration files. I.E. In the Apache web server :

SetEnv shopA_TO_ROUTE_SERVER serverA
SetEnv shopA_TO_ROUTE_PORT portA

SetEnv shopB_TO_ROUTE_SERVER serverB
SetEnv shopB_TO_ROUTE_PORT portB

When access from the browser you can distinguish one application from annother changing the cgi at the URL level i.e :

http://venus.domain.com/cgi-bin/shopA/main.csp or

means the main.csp page of the application one (shopA) or the main.csp page of the application two (shopB).

Diferent applications means that it is not possible to access both from the same user session.

Distributing C Server Pages Applications:

The binary files TOCgi, routeserver and TO_imanager with the configuration file, constitutes
the C Server Pages engine for C Server Pages and Templates. To distribute applications is enough to
distribute this binaries with the actual application, constituted by a set of C Server Pages, a set of
Dynamics Elements and a set of Templates.