Home | WebSiphon | Learning Resources WebSiphon Developer Central

WebSiphon Fundamentals:

Built-in Variables
by Nathan Nunn

August 2003

What are Built-in Variables?
Built-in variables are special runtime instance variables which are created automatically by WebSiphon each time a page request is received. These variables describe the user's web browser (the user agent), the HTTP request, and other special runtime information used for things like error handling.

Using these valuable built-in variables customized HTML output can be produced depending on conditions of your choosing. This type of conditional logic-based HTML output is called a dynamic publishing system.

These same built-in variables form the basis for more complex, session-based web systems that offer a much more interactive user experience not unlike traditional software applications. As such, these types of systems are named web applications.

Though pre-defined by WebSiphon, built-in variables are not constant. These values are mutable as with any other SiphonScript variable. Note however there are few scenarios where it would be advisable to modify these values and it is not advised, as doing so would deviate from the default WebSiphon environment and potentially confuse others who use your server.

Classes of Built-in Variables
The sections below offer a description of the different types of built-in variables defined by WebSiphon, each organized into the class of data each variable represents. The scripting examples found at the end of each class below include actual values generated when this template was served - in other words, this article was dynamically published on-demand and served to you.

When working with WebSiphon the term template is used to describe a file which contains both blocks of SiphonScript and HTML output. A script is an arbitrary block of SiphonScript statements, which may or may not be associated with a physical file on disk.

File Paths and Template Info
This class of built-in variables describe the currently executing template, or script.

Direct CGI Parameters and the HTTP Request
This class of built-in variables describe the HTTP request that triggered the current runtime execution and are vital for most methods of session management and other user-centric, specialized services. Some of these variables are provided by the web server daemon process when it calls on WebSiphon to execute a template or script.

The WebSiphon Environment
This class of built-in variables describe the WebSiphon environment itself. They are useful when you need to build a reliable file path outside of a web request, or access internal runtime engine settings. Also helpful if you are writing reusable frameworks or other libraries which require a specific add-on or feature to operate correctly.

Error Handling
These variables are created when a runtime error occurs. These built-in values used in conjunction with try/catch statements enable scripts to react when an error condition occurs, rather than display a frightening error message to the user.

For further information on the different types of SiphonScript variables and their usage, see the WebSiphon User Guide.

File Paths and Template Info

Built-in Name Description
template_name the currently running template's file name
template_path the full path to running template
this_template the template's complete file path (concatenated template_path and template_name)
site_path the full path to web site root
template_uri the URI portion of the HTTP request (URI path to this template)
template_mod_date the template's modification date
template_mod_date_secs the template's modification date, as seconds since Jan 1, 1904
Scripting Examples
print template_name;
print template_uri;
→ builtinvars.ws
print template_path;
print site_path;
→ Saraswati:www-prime:vhosts:purity.com:html-www:websiphon:learn:
print template_mod_date;
print template_mod_date_secs;
→ 9/12/03 0:26:33

CGI Parameters and the HTTP Request

Built-in Name Description
action_name web server action name for CGI process
action_path web server CGI action path
cgi_connection_id unique ID used by web server to identify the TCP/IP connection
cgi_host_name HTTP host as defined in client request
client_accept accept as defined in HTTP request
client_accept_language accept language as defined in HTTP request
client_accept_encoding accept encoding as defined in HTTP request
client_address reverse-lookup Internet name of remote client (if enabled on web server)
connection_type connection type as defined in HTTP request
content_type MIME type associated with POST arguments, if there are any
client_ip_address machine IP address of remote client
full_client_request the entire HTTP request as sent by the client web browser (example shows only excerpt, too long to display in full)
http_method the HTTP method (GET, POST, etc.)
http_version HTTP version specified by the client web browser
password HTTP authenticated password, provided only if user has logged into a realm using the client web browser
path_arguments URL arguments following a $ character
post_arguments POST data resulting from an HTML form submission
referer the URL that referenced this request (where page was linked from)
script_name URI name for executing script
user_agent identification string sent by the client web browser
user_agent_cpu client CPU type as sent by the client web browser (not always supplied or available)
user_agent_os client OS as sent by the client web browser (not always supplied or available)
search_arguments URL arguments following a ? character
server_name Internet host name or IP address of web server
server_port TCP/IP port number being used for current request
username HTTP authenticated username, provided only if user has logged into a realm using the client web browser
Scripting Examples
print client_ip_address;
print referer;
print user_agent;
→ CCBot/2.0 (https://commoncrawl.org/faq/)
print server_name & ":" & server_port;
→ 206-126-49-30.static.nstci.net:80

The WebSiphon Environment

Built-in Name Description
siphon_os operating system version string
siphon_version WebSiphon version string
siphon_sapi WebSiphon API version string
siphon_prefs_index_file default index filename, when requests point to a directory
siphon_prefs_error_file default error filename, served when request not found (404)
siphon_prefs_no_access_file default noaccess filename, served when HTTP authentication fails
siphon_data_path full path to the WebSiphon Data folder
siphon_templates_path full path to the Templates folder
siphon_startup_path full path to the Startup folder
siphon_libraries_path full path to the Libraries folder
siphon_lib_data_path full path to the Library Data folder
Scripting Examples
print siphon_os ", " siphon_version;
→ Mac OS, 2.0.9
print siphon_prefs_index_file;
→ index.ws

Error Handling

Some values may not be set depending on conditions surrounding the runtime error.

Built-in Name Description
siphon_error_message textual error string (if available)
siphon_error_number error number
siphon_error_source_file the SiphonScript file which produced the error
siphon_error_file_path the full path to file which produced the error
siphon_error_line_number approximate line number where error occurred
siphon_error_uri the URI which produced the error
siphon_error_full_request full headers from request which produced the error

Pure code for pure minds; live to love and learn.
Copyright © 1995-2022 Purity Software. All rights reserved worldwide.
Purity Software® is a registered trademark of Nathan Nunn.