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 four primary methods: function callouts, in-line scalars, 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 via /session/login (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.

User Logins & Variable Types
After logging in, a server-side USER structure is maintained for the user and re-attached to the client on each request based on the cookie set at login. Of the three variable types in the scripting interface, two are specific to logged-in users:

• RC$ variables exist for the period of the template. All arguments passed to the URL are available as RC$ variables. These variables go away as soon as the page request is completed.
• RCS variables are user "state" variables that are stored in the server-side USER structure. These variables are stored in-memory and go away as soon as the user logs out, the login times out, or the server shuts down.
• RCP variables are user "profile" variables. These are stored in a flat-file (profiles/<username>). These variables are available between logins and are meant to be used for saving preferences.

System Comments
Comments between <!--- and ---> (note the three dashes (-) are stripped from the .stm file prior to it being returned to the use. This can be useful for commenting your scripted code. (Note: It does not affect the RCredirect method as regular comments that are returned to the client do; the header information is not written to the client when these comments are seen.)

<!-- This text shows up -->

<!--- This does not --->

Escaping quotes and tag terminators
Occasionally, the need arises to escape tag terminator (>) so it can be used within a string assignment, i.e. <RC$foo = where x \> 22>. The backslash (\) can be used in any template tag to escape the next character.

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. Important: When assigning values to variables, there must be a space between the variable name and the equals sign (=) or the assignment will not be properly parsed. The following example illustrates how to set a variable and then use it as another script argument:

  <RC$where = /index.htm>
where variable is: <RC$where>
<RCinclude RC$where>


  The assignment of a variable can be an expression if all tokens in the expression are numeric values. For example:

  <RC$result = 1.3 * (RC$foo + RCDresult.1) + 5.5>

  The above (rather complex) assignment expression will yield a numeric if RC$foo and RCDresult.1 are both be numeric values. All tokens in the expression must be operators, numeric constants (i.e. 1.3) or RC values that evaluate to numeric values. If the expression is malformed (i.e. invalid operators) or an RC value evaluates to NULL (is unset) or a non-numeric, the expression is disregarded and the assignment is treated as a string. Note: Expressions may only be used in assignments, they cannot be used in if/then conditional expressions. The following operators are supported:

  operator	description	precedence
  (		Lowest
  )		Hightest
  +	addition	Low
  -	subtraction	Low
  *	multiplication	Medium
  /	division	Medium
  %	modulus	High
  ^	exponential	High

  When multiple parameters of the same name are passed into the template for processing (i.e. < SELECT NAME=foo MULTIPLE >), the individual parameters can be retrieved by appending a parameter number. For example, <RC$foo.2> would retrieve the second "foo" parameter. To retrieve the number of parameters corresponding to the same element name, you can use the special hash (#) argument, for example: <RC$foo.#>

  For convenient passing of arguments from one page to another (as well as debugging), the special argument: <RC$*> can be used to return an http-escaped parameter list of all known variables (truncated at 2K).

• 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 (this RPC is only available to the system administrator). The Show RPCs on the System Administrator page displays all registered RPC methods. User-defined RPCs can be registered using the sa_cmd_init interface.

• RC@scalar
  Execute a Server in-line scalar function.
  For example, the tag RC@length(RC$foo) returns the length of the variable RC$foo. The Show In-Line Scalars on the System Administrator page displays all registered scalar functions. User-defined scalars can be registered using the sa_scalar_init interface.

• 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.

• RCJservlet
  If the JavaEngine is enabled, servlets can be included withing a scripted page. Important! Servlet names are case sensitive; make sure the servlet name matches the Java class name. Parameters can be passed as name/value pairs just as with RCX, RCC, and RCW commands. In addition, all parameters available in the script (i.e. parameters passed in via GET or POST, or parameters explicity set) are available to the servlet.

• RCinclude /url
  Include the specified file/ISAPI/template within the template. Paths specified must specify a "valid" URL and must begin with a leading slash (/). Examples:

  <RCinclude /index.htm>
  <RCinclude /search.dll?query=Sambar>
  

  Note: If no arguments are provided to the include script (as in the first example, /index.htm). The subsequent include file will have access to all variables passed to the original script. If arguments are passed (as in the second example, /search.dll?query=Sambar), these arguments will over-ride any arguments passed to the original script.

• RCredirect location
  Redirect to the specified location. This directive can only be used if no other text has been returned on the page.

• RCexit
  Exit the script processing immediately. This directive allows the user to terminate the processing of the template script at an arbitrary point; for example, upon reaching a particular if/then condition. Only the current script is terminated. In the case of a login script, SSI or RCinclude script inclusion, the calling script continues to execute. Use RCterminate to stop all execution.

• RCterminate
  Terminate all script processing immediately.

• 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. Conditions cannot presently contain expressions; condition tags are limited to single elements: RC$, RCS, RCP, RCE, RCD, and RC@. The output of a scalar (RC@) may be used as condition elements; the scalar RC@expr(expression) can further be used to evaluate expressions in if/then statements, for example: <RCif RC@expr(1 + 2 + 3) > 3>
  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>
  Case-insensitive comparisons can be performed by using the tilde (~) symbol in place of the equality (=) symbol: <RCif RC$var ~ ReD OR RC$var ~ BluE>
  With either the equality or case-insensitive comparisons, the star (*) wildcard symbol may be used: <RCif RC$var ~ red* OR RC$var ~ Blue*>

Valid equality/inequality expressions are:

Comparison	Description	Example
=	Equality	<RCif RC$var = red>
!	Inequality	<RCif RC$var ! red>
>	Greater Than	<RCif RC$var > 125>
<	Less Than	<RCif RC$var < 125>
~	Case-insensitive Equality	<RCif RC$var ~ red>

Note: When a Sambar scripting tag appears insied another Sambar scripting tag (as RC$var does in the if/then example above), the embedded tag should not appear in angle brackets.

.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.

Quick How-To
Bernhard provided this quite "how-to" guide to coming up to speed quickly on scripting.

RC$variablename = variables (like form variables/parameters), available on the current page.

<RC$textfield> <RC$button1> <RC$sum = RC$value1 + RC$value2>
As the above illustrates, you can calculate and assign values to these variables, and their assignments last until the page is changed.

<RCSlogintime = 10:00> <RCSlogindate = 13.05>
You can save data on the current session of that user.

<font size=<RCPfontsize>>
The values set with these variables can be used to set preferences like the font size, and they are available again on every login of that user.

<RC$var1=1> will not work
<RC$var1 = 1> will work
<RCif RC$var=1> is correct when comparing values

Today is: <RCEday>lt;RCEmonth>lt;RCEyear> the time is: <RCEhour>:<RCEminute>:<RCEsecond>
Your username is <RCEusername> your IP is <RCEhostname>.
A full list of environment variables can be found on your server at http://localhost/sysadmin/reports/envt.stm

MOTD: <RCVmotd>

RCXserverRPC = pre-defined functions.

RC@scalar executes an in-line scalar function.

RCQquery executes an SQL query against any declared database. This can be a MS Access database, Oracle, MS SQL or any database that you have an ODBC driver for.

<RCQmyaccessdb sql="select name, username from allusers" format="<tr><td>%s</td><td>%s</td></tr>">

The above command will run a query against an ODBC database defined as myaccessdb in both the 32-bit ODBC manager and the dbconfig.ini of the Sambar Server.

There are also flow-control functionality to assist in basic page scripting.

<RCif> <RCelse> <RCelseif> <RCendif>

<RCwhile> <RCendwhile>

Examples:

<RCif RCPgender=m>
Good morning, Mr <RCPsurname>
<RCelseif RCPgender=f>
Good morning, Ms <RCPsurname>
<RCelse>
Good morning, <RCPfirstname>
<RCendif>

<RCif RC@length(RC$parameter)> 0>
You passed a parameter
<RCelse>
You did not pass a parameter
<RCendif>

On a page called by: http://www.yourserver.com?name=Tod&occupation=programmer you refer to the parameters by: Hello <RC$name>, are you happy in your job as <RC$occupation> ?