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.