Templates are a generalization of HTML documents. In addition to static HTML, a template can contain other instructions. These instructions are interpreted by the interpreter when the document is requested by a Web client, and the client sees not the embedded instructions, but the results of those instructions.

The Sambar Server interpreter handles several kinds of embedded instruction. It interprets SQL statements by executing them against a database, interprets scripts internally, and can use conditional logic and text replacement and server variables to enhance client/server interactions.

To enable real interaction between a Web client and the Web server, an action at the client must send information to the Web server, and this information must be used by the Sambar Server in generating its response. The Sambar Server supports this function using three methods: function callouts, text substitution macros and server variables.

You can include a macro in an HTML template at any place in the content. This macro is expanded by the interpreter when the template is processed, being replaced by its value.

The value of a macro is defined in the URL when the page is accessed. The following example shows how text substitution works.

A user at a Web client fills out an HTML form to subscribe to a service. The form includes fields for their first and last name.

When the form is sent to the Web server, the user's entry is sent along with the request in the URL. The standard form for such an inclusion is as in the following example:

http://www/template-name.stm?firstname=Jane&lastname=Smith

In the HTML template, the symbol <RC$firstname> is replaced by Jane and the symbol <RC$lastname> by Smith wherever they appear. For example, a returned acknowledgment may include the text:

Dear Jane Smith,
Thank you for your registration. Your registration number is 123-456.

The RC$ tag is used to identify all FORM parameters. That is, variables that are available for text substitution and/or use in conditional logic.

/session Identifier
The Sambar Server scripting files (*.stm) have a reference to a /session directory. For example, the following tag is used to login the user "guest" into the magazine demo:

<A HREF="/session/login?RCuser=guest&RCpage=/magazine/welcome.stm">

The /session directive indicates that a DLL function is being requested. In the above example, /session/login corresponds with the internal "login" function. Once the /session function is executed, if an RCpage is specified and no HTML was generated by the function, the page is displayed. In the above example, /session/login attempts to login the user "guest", assuming the function returns SA_SUCCEED, then the magazine welcome page is output.

Another option to the RCpage directive is the RCredirect option. This argument functions similarly to the RCpage argument except that the client browser is redirected to the specified location. This is useful in two instances: 1) You wish to redirect the user to another site after the /session function is executed, or 2) The page you wish to direct the client to has relative paths (links not beginning with a slash (/)) -- the redirect is necessary because the browser assumes the client is in the fictitious /session directory.

The /session/login function expects the argument RCuser and an option RCpwd (password parameter). If no RCpwd argument is provided, a password of NULL is expected. /session/login then attempts to login (see config/passwd) the user, sets a cookie for the user for future authentication, and creates a "state" structure associated with the user and maintained by the server.

So as long as the user is logged in (logins timeout after a period of inactivity), any values set with RCS flags (state flags) will be maintained by the server. This is how the demo maintains user information/preferences etc. accross pages -- the demo gets and sets state variables.

There is a second type of variable appropriate for users called profile variables (RCP arguments). This feature is not presently available in the public version of the sambar server. The RCP variables all you to persistently store attributes of a user so that when they login again, the RCP attributes are retrieved from disk (and can be get/set just like RCS attributes). This interface will probably expose this (and document it) in the 4.1 release.

There is a /session/logout function for logging out and releasing the state information held by the server.

System-defined Tags
The categories of system-defined tags include:

• RCPattribute
  Client profile attribute tag.
  For example, the tag RCPname specifies the "name" attribute from the client profile.
  The user-defined PROFILE event handler is called to fulfile profile requests. Profile attributes are only available for logged in users, and can be used within conditional logic (see below) or for display purposes.

  Example:
  HTML content might be displayed if RCPage > 16 and RCPsex = "M"

• RCSstate-variable
  Client state variable tag.
  For example, the tag RCSpagetype specifies the "pagetype" state variable from the client's current session.
  State variables are dynamic and extensible; application programmers can both define state variables and assign values to those variables at any time.

  Example:
  An advertisement for golf clubs might be displayed if RCSprevtype = "Sports" and RCPhobby = "Golf"

• RC$form-variable
  FORM variable tag.
  For example, the tag RC$pagetype specifies the "pagetype" FORM variable from the GET or POST arguments. These temporary arguments can also have values assigned to them for later use within the script. For example, <RC$foo = RCDtest.1> assigns the database query result from column one to the script variable foo.

• RCEenvironment-variable
  Server environment variable tag.
  For example, the tag RCEdatetime specifies the current date and time.
  The System Administration forms contains a page with all of the system defined environment variables.
  Example:
  A Christmas advertisement might be displayed if RCEmonth = "12"

• RCVvariable
  Server variable tag.
  For example, the tag RCVcreator displays the creator of the application. All variables are defined in the sysvars.ini configuration file. Using the system administration forms, variables can be changed without restarting the server.

• RCZmacro
  Server macro definition.
  For example, the tag RCZFINANCE_FOOTER displays the footer string associated with the FINANCE_FOOTER definition found in the macros.ini configuration file. Macros are loaded at system startup and can only be modified by restarting the server.

• RCXmethod
  Execute a Server RPC.
  For example, the tag RCXhelp lists all user-defined RPCs registered in the system.

• RCCcgi
  Execute a Server CGI application.
  For example, the tag RCChello.bat foo=111 bar=222 executes the hello.bat CGI application, passing the foo and bar arguments and returns the results of the script in the HTML file in place of the tag. Note: Only arguments provided with the scripted RPC (foo and bar in the above example) are passed to the CGI application.

• RCWwincgi
  Execute a Server WinCGI application.
  For example, the tag RCWhello.bat foo=111 bar=222 executes the hello.bat WinCGI application, passing the foo and bar arguments and returns the results of the script in the HTML file in place of the tag. Note: Only arguments provided with the scripted RPC (foo and bar in the above example) are passed to the CGI application.

• RCOobservation-string
  Log the observation string to the observation file.

• RCQcache.query
  Execute a SQL command against the specified database connection/cache. See the DBMS Tutorial for more details on usage.

• RCFcache
  Fetch a row from a currently executing SQL database connection/cache. See the DBMS Tutorial for more details on usage.

• RCDcache.col#
  Retrieve the data associated the specified column number for the SQL database connection/cache stream. See the DBMS Tutorial for more details on usage.

• RCinclude /uri
  Include the specified file within the template. Paths specified must specify the entire path to the file and must begin with a leading slash (/).

• RCifcondition
  RCelse
  RCelseifanother-condition
  RCendif
  Condition tags.
  These tags enable dynamic evaluation of one or more pre-defined conditions. If the condition is found to be TRUE, the code that follows is executed. This can be used, for example, to determine which choices to display to a particular user. As an example, a visitor to your site might be shown more limited options than might a registered user. Condition tags enable you to evaluate a client's status and take varying actions based upon the result of the evaluation.
  To test for a NULL condition, that is, the absense of a parameter for example, you can test against the built-in NULL element: <RCif RC$var = NULL>
  If/then logic can be combined with the keywords AND or OR, however, AND and OR keywords cannot be combined in the same expression: <RCif RC$var = red OR RC$var = blue>
  

.stm files
The above scripting language may only be used in files that are identified as Sambar Server Scripted files. By default, the .stm extension indicates that the file contains Sambar Server Scripting. Upon seeing this extension, the server parses the content looking for the scripting tokens/actions defined above.

Sessions and State
Web connections are typically sessionless - from your web client, you can jump from one web site to another (and back) at any time. If you jump away from a given web site, you may jump back in two minutes or two days (or never). Unlike conventional desktop applications, the web site can never know exactly when you've ended your "session" with it.

It is desirable, though, to maintain some concept of a session between the Web client and the Web site. If you, as the web site, set up a welcome page that asks the user to log in with a name and password, each of the pages that you then make available to them must "know" somehow that the user has already logged in. If, however, they haven't logged in (or haven't logged in recently - say, within the last hour), the site needs a way of detecting this to force them to log in again.

Duration

The Sambar Server login and adminlogin RPCs provide a way of initiating a session and result in a session object being associated with the client (using cookies) that persists for the duration of this particular client-to-site connection. Because there is typically no explicit end to a session, the duration of the connection must be decided arbitrarily (Note: a logout method is available to explicitly end the session.)

By default, the Sambar Server considers a session to last five minutes from the time of the user's last action at a given Web site (this default duration can be changed in the config.ini file). For the duration of a session, the site can maintain information about the user's connection - a login name, state and profile information, or whatever other information the site requests from the client.

The site stores this session information in a session object - one object for each client. A session object is accessible to all template pages in the site, so they can check its status as they require. After the specified duration elapses (or times out), the session object associated with the client is released.