WebSiphon Fundamentals: Built-in Variables

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

/websiphon/learn/builtinvars.ws

print template_path;

print site_path;

→ Saraswati:www-prime:vhosts:purity.com:html-www:websiphon:learn:

Saraswati:www-prime:vhosts:purity.com:html-www:

print template_mod_date;

print template_mod_date_secs;

→ 9/12/03 0:26:33

3.14617e+09

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;

→ 3.234.245.121

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