Mbedthis Home |  Documentation Home |  Administration |  Programmers Reference
AppWeb Documentation > Programmers Reference >

ESP JavaScript API

Detailed Description

Documentation for the Embedded Server Pages (ESP) JavaScript API.

Overview:
ESP provides each HTTP request its own JavaScript context so that computations for each request are protected from access or modification by other requests. This means each request has its own local variables and global variables store can can create variables without fear of name conflicts with other requests.

ESP defines a set of standard procedures and variables that provide access to server and request details including cookies, request headers and session state data.


Functions
function  Array (var elt1, var elt2,...)
function  Array (var size)
function  assert (var condition)
function  createSession (var timeout)
function  destroySession ()
function  eval (var script,...)
function  exit (var status)
function  include (var path)
function  Object ()
function  print (var string,...)
function  println (var string,...)
function  printVars (var v,...)
function  redirect (var url, var code)
function  refCount (var v)
function  setHeader (var header, var allowMultiple)
function  trace (var message)
function  useSession (var timeout)
function  write (var expr,...)

Variables
var  application []
  Stores application global data.

var  cookies []
  Stores Client cookie state information.

var  false
  False value.
var  files []
  Stores uploaded files information.

var  form []
  Stores the form client data.

var  global []
  Store all global variables.

var  headers []
  Stores the request headers.

var  Infinity
  Floating number set to Infinity.
var  local []
  Store all local variables.

var  Nan
  Floating variable set to "Not a number".
var  null
  Defined variable set to Null.
var  request []
  Stores per-request information.

var  server []
  Stores server related request information.

var  session []
  Stores session state information.

var  true
  true value
var  undefined
  Variable set to the Undefined value.

Function Documentation

function Array (  var  elt1,
var  elt2,
... 
) 
 

Synopsis:
Constructor for an Array object
Overview:
Create an Array object using the supplied elements. The array object will have a length property defined that will be set to the number of elements currently in the array.
Parameters:
elt1  Element one
elt2  Element two
Returns:
Returns the constructed array object
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, println, printVars, refCount, trace

function Array (  var  size  ) 
 

Synopsis:
Constructor for an Array object
Overview:
Create an Array object. An empty array object will be created with size initial elements. These elements will be named "0", "1", "2" etc. The value of these elements will initially be the undefined value.

The array object will have a length property defined that will be set to the number of elements currently in the array. The array will grow on demand as new elements are added to the array.

Arrays inherit all the standard properties and methods from EJS Objects.
Parameters:
size  Initial number of elements in the array
Returns:
Returns the constructed array object
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, println, printVars, refCount, trace

function assert (  var  condition  ) 
 

Synopsis:
Assert a condition is true
Overview:
This call tests if a condition is true by testing to see if the supplied expression is true. If the expression is false, the interpreter will throw and exception and abort processing the current script.
Parameters:
condition  JavaScript expression evaluating or castable to a boolean result.
Library:
libejs, libappWeb
See also:
Array, Object, eval, exit, print, println, printVars, refCount, trace

function createSession (  var  timeout  ) 
 

Synopsis:
Create a session
Overview:
This call creates a session state store for the current client. If a session already exists, it is used and this call has no effect. The session[] array global object is created for all HTTP requests servicing this client. A cookie containing a session ID is automatically created and sent to the client on the first response after creating the client.

If SessionAutoCreate is defined in the configuration file, then sessions will automatically be created for every ESP request and your ESP pages do not need to call createSession.
Remarks:
Multiple requests may be sent from a client's browser at the same time. ESP will ensure that accesses to the sesssion[] array are correctly serialized. useSession is also an alias for this command.
Parameters:
timeout  Optional timeout for the session in seconds. If ommitted the default timeout is used. In AppWeb, this is set via the SessionTimeout configuration directive.
Returns:
Returns the Session ID string
Library:
libejs, libappWeb
See also:
useSession, destroySession, include, redirect, setHeader, write

function destroySession (   ) 
 

Synopsis:
Destroy a session
Overview:
This call destroys the session state store that is being used for the current client. If no session exists, this call has no effect.
Library:
libejs, libappWeb
See also:
useSession, include, redirect, setHeader, write

function eval (  var  script,
... 
) 
 

Synopsis:
Evaluate a script
Overview:
This call evaluates the given JavaScript script in the current context. It provides a feature to dynamically modify the code executed by the interpreter. It is also useful to evaluate the value of complex expressions as the call will return the value of the last expression evaluated.

The script is executed with the current local and global variables. No new local variable stack frame is created.
Parameters:
script  JavaScript to execute
Returns:
Returns the value of the last expression evaluated.
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, println, printVars, refCount, trace

function exit (  var  status  ) 
 

Synopsis:
Exit a script
Overview:
This call immediately exits the current script. This call is useful when you immediately want to exit a script. ESP pages use this to terminate processing the current ESP page in the case of a web page redirect.
Parameters:
status  Numeric status code. This code is retrievable via the ejsGetExitCode API.
Library:
libejs, libappWeb
See also:
Array, Object, assert, print, println, printVars, refCount, trace

function include (  var  path  ) 
 

Synopsis:
Include an JavaScript file
Overview:
This call includes a JavaScript at the point of the include statement. The effect is as though the text from the included file were pasted into the original file. The script executes with the context of the original file and uses its local and global variables.
Parameters:
path  Path name of file to be included.
Library:
libejs, libappWeb
See also:
useSession, destroySession, redirect, setHeader, write

function Object (   ) 
 

Synopsis:
Constructor for an object
Overview:
Create a new object. JavaScript objects can contain data properties and function methods. All objects contain a toString method that by default returns "[object name]". This method may be replaced by assigning a function to the toString property.
Returns:
Returns the constructed array object
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, println, printVars, refCount, trace

function print (  var  string,
... 
) 
 

Synopsis:
Print the arguments to the standard output
Overview:
This call evaluates the arguments, converts the result to strings and prints the result to the standard output. Arguments are converted to strings using the normal JavaScript conversion rules. Objects will have their toString methods called to get a string equivalent of their value.
Parameters:
string  String to print
Library:
libejs, libappWeb
See also:
Array, Object, assert, assert, exit, println, printVars, refCount, trace

function println (  var  string,
... 
) 
 

Synopsis:
Print the arguments to the standard output with a new line
Overview:
This call evaluates the arguments, converts the result to strings, appends a new line character and prints the result to the standard output. Arguments are converted to strings using the normal JavaScript conversion rules. Objects will have their toString methods called to get a string equivalent of their value.
Parameters:
string  String to print
string  JavaScript to execute
Returns:
Returns the value of the last expression evaluated.
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, printVars, refCount, trace

function printVars (  var  v,
... 
) 
 

Synopsis:
Print the contents of a variable to the standard output
Overview:
This call prints the contents of variables to the standard output. Unlike print and println that convert objects to strings, printVars will enumerate objects and recursively print their contents. printVars is most useful to examine the contents of objects.
Parameters:
v  Variable to print
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, println, refCount, trace

function redirect (  var  url,
var  code
) 
 

Synopsis:
Redirect the client to a new URL
Overview:
This call redirects the client's browser to a new location specified by the url. Optionally, a redirection code may be provided. Normally this code is set by ESP to be the HTTP code 302 which means a temporary redirect. A 301, permanent redirect code may be explicitly set.
Parameters:
url  Url to redirect the client to
code  Optional HTTP redirection code
Library:
libejs, libappWeb
See also:
include, useSession, destroySession, redirect, setHeader, write

function refCount (  var  v  ) 
 

Synopsis:
Get the reference count for an object
Overview:
This call returns the count of users of an object by returning the objects reference count.
Parameters:
v  Object to examine for its reference count.
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, println, printVars, trace

function setHeader (  var  header,
var  allowMultiple
) 
 

Synopsis:
Set a HTTP response header
Overview:
This call defines a HTTP response header. The value argument should contain a string of the format "keyword: value". If a header has already been defined and allowMultiple is false, the header will be overwritten. If allowMultiple is true, the new header will be appended to the response headers and the existing header will also be output. NOTE: case does not matter in the header keyword.
Parameters:
header  Header string
allowMultiple  If false, overwrite existing headers with the same keyword. If true, all headers are output.
Library:
libejs, libappWeb
See also:
createSession, destroySession, include, redirect, write

function trace (  var  message  ) 
 

Synopsis:
Output trace to the web server log
Overview:
This call outputs the given message to the web server log. An optional numeric trace log level between 0 and 9 may be given as the first argument (not shown).
Parameters:
message  Message to log
Library:
libejs, libappWeb
See also:
Array, Object, assert, exit, print, println, printVars, refCount

function useSession (  var  timeout  ) 
 

Synopsis:
Use a session
Overview:
This call is identical to createSession. It will ensure that the ESP page uses session handle. See createSession for full documentation.
Parameters:
timeout  Optional timeout for the session in seconds. If ommitted the default timeout is used. In AppWeb, this is set via the SessionTimeout configuration directive.
Returns:
Returns the Session ID string
Library:
libejs, libappWeb
See also:
createSession, destroySession, include, redirect, setHeader, write

function write (  var  expr,
... 
) 
 

Synopsis:
Write text to the client
Overview:
This call writes the arguments back to the client's browser. The arguments are converted to strings before writing back to the client.

Text written using write, will be buffered by ESP up to a configurable maximum. This allows text to be written prior to setting HTTP headers with setHeader.
Parameters:
expr  JavaScript expression or variable to write to the client.
Library:
libejs, libappWeb
See also:
createSession, destroySession, include, redirect, setHeader, write

Variable Documentation

var application[]
 

Stores application global data.

Overview:
The application array provides a means to store persistent information to be shared across all requests and virtual hosts within a server. Objects and variables stored in the application array will live until either explicitly deleted or the web server exits. The application array does not persist over system reboots.
Elements:
User defined

var cookies[]
 

Stores Client cookie state information.

Overview:
The cookie array will be created automatically if the Client supplied cookies with the current request.

Cookies are used to specify the session state. Thus when sessions are being used, a cookie will be sent to and from the browser with each request.
Elements:
Elements are user defined.

var files[]
 

Stores uploaded files information.

Overview:
The files array will be created automatically if the request includes uploaded files.

Sessions are shared among requests that come from a single client. This may mean that multiple requests access the same session concurrently. ESP ensures that such accesses are serialized.
Elements:
For each uploaded file, an object is created in files[]. The name of the object is given by the upload field name in the ESP page.
  • CLIENT_FILENAME - Name of the uploaded file given by the client.
  • CONTENT_TYPE - Type of the encoded data.
  • FILENAME - Local name of the temporary file in the upload directory.
  • SIZE - Size of the uploaded file in bytes.

var form[]
 

Stores the form client data.

Overview:
The form array stores the posted data variables and query request data.
Elements:
The names of the elements are the names of the form fields.

var global[]
 

Store all global variables.

Overview:
The global array stores all global variables and provides a consistent means to enumerate and explicitly access global variables.
Elements:
The following elements are defined in the global array:
  • local - Array of local variables
  • Nan - Not a number constant
  • Infinity - Infinity constant
  • null - Null constant
  • undefined - Undefined variable constant
  • true - True boolean constant
  • false - False boolean constant
  • server - Array of server variables
  • session - Array of session variables
  • request - Array of request variables
  • headers - Array of header variables
  • cookies - Array of cookie variables
  • files - Array of uploaded files
  • form - Array of form data
  • application - Array of application global variable

var headers[]
 

Stores the request headers.

Overview:
The request array stores all the HTTP request headers that were supplied by the client in the current request.
Elements:
The following elements are usually supplied by the Client. However the Client may supply any headers that they choose.
  • HTTP_ACCEPT - The Accept header. Specifies the content types that are acceptable to the client.
  • HTTP_ACCEPT_CHARSET - The character set header. Specifies the character sets that are acceptable to the client.
  • HTTP_CONNECTION - Connection header. Specifies how the connection should be managed by the server. This headers is used to specify HTTP/1.1 Keep-Alive.
  • HTTP_HOST - Destination host. This is used when virtual hosts are served by a single web server.
  • HTTP_REFERER - Name of the referring URL.
  • HTTP_USER_AGENT - Name of the Client browser software.
  • and any other custom headers

var local[]
 

Store all local variables.

Overview:
The local array stores all local variables and provides a consistent means to enumerate and explicitly access local variables.
Elements:
The following elements are defined in the local array:
  • global - Point to the global variables array.
  • this - When inside a function, if an object method has been called. this will be set to point to the object.

var request[]
 

Stores per-request information.

Overview:
The request array holds the primary request information.
Elements:
The request array holds the following elements:
  • AUTH_TYPE - The authorization type (basic or digest) if authorization is being used.
  • CONTENT_LENGTH - The length of any posted reqeust content.
  • CONTENT_TYPE - The mime type of any posted content.
  • QUERY_STRING - The request query string.
  • PATH_INFO - The portion of the path after the script name if extra path processing is being used. See the ExtraPath directive.
  • PATH_TRANSLATED - The physical path corresponding to PATH_INFO.
  • REMOTE_ADDR - The IP address of the Client issuing the request.
  • REMOTE_HOST - The host address of the Client issuing the request.
  • REMOTE_USER - The user name of the Client issuing the request. Rarely supplied.
  • REQUEST_METHOD - The HTTP request method (GET|HEAD|OPTIONS|PUT|TRACE)
  • REQUEST_URI - The request URL portion after the site name with the query stripped off.
  • SCRIPT_FILENAME - The physical path name for SCRIPT_NAME.
  • SCRIPT_NAME - The name of the script in the URL.
  • SESSION_ID - Session state unique identifier

var server[]
 

Stores server related request information.

Overview:
The server array stores information that typically does not vary from request to request. For a given virtual server, these data items will be constant across all requests. Users should NOT store custom information in this array as it will probably be made read-only and shared among host requests in the future.
Elements:
Elements of the server[] array include:
  • DOCUMENT_ROOT - Set to the server's document root
  • GATEWAY_INTERFACE - Set to the version of the CGI Gateway Interface
  • SERVER_ADDR - Set to the Server TCP/IP address
  • SERVER_PORT - Set to the Server TCP/IP port
  • SERVER_NAME - Set to the name of Server or Virtual Host
  • SERVER_PROTOCOL - Set to the HTTP protocol version in use
  • SERVER_SOFTWARE - Set to the version of the HTTP server
  • SERVER_URL - Set to the home URL of the server
  • UPLOAD_DIR - Set to the directory path storing uploaded files.

var session[]
 

Stores session state information.

Overview:
The session array will be created automatically if SessionAutoCreate is defined or if a session is started via the useSession() or createSession() JavaScript functions.

Sessions are shared among requests that come from a single client. This may mean that multiple requests access the same session concurrently. ESP ensures that such accesses are serialized.
Elements:
Elements are user defined.

See Also

API Overview
C++ API
C API
JavaScript API
Class List
File List

© Mbedthis Software LLC, 2003-2004. All rights reserved. Mbedthis is a trademark of Mbedthis Software LLC.