Request: CONTENT

Syntax

value: request/content/namename : name of an HTTP parameter passed in the request though GET or POST method.

Description

Gives access to the data sent by the HTTP client through a GET or POST request to the server. Values are always returned as string! values. request/content is a simple block! of name/value pairs filled just before the execution of the RSP page, so it can also be processed using a loop.

Note: Trying to use a name that doesn't match any parameter name sent in the request will result in an error!. If you're not sure about the presence of a given parameter in the request, you can use find or select to check its presence in request/content before accessing it.

Request: HEADERS

Syntax

value: request/headers/namename : name of an HTTP header passed in the request.

Description

Gives access to the headers sent by the HTTP client in the request. Values are always returned as string! values. headers is a simple block! of name/value pairs filled just before the execution of the RSP page, so it can also be processed using a loop.

Note: Trying to use a name that doesn't match any parameter name sent in the request will result in an error!. If you're not sure about the presence of a given parameter in the request, you can use find or select to check its presence in request/headers before accessing it.

Request: QUERY-STRING

Syntax

value: request/query-string
returns an string! value.

Description

Returns a re-composed query-string from the request parameters (REQUEST/CONTENT names and values). It you didn't altered the request parameters, it gives you the initial query-string received from the client.

Request: STORE

Syntax

Description

Cheyenne has an efficient way to handle uploaded files or large POSTed data: it streams them to a disk file instead of keeping them whole in memory. So, from the RSP script perpective, the upload file appears as a block! composed of:

the original uploaded filename

the path to a temporary file holding the content

This specification block is accessible through request/content/<param> where param is the name used in the HTML <input type="file"&gt, element and when the form use a enctype="multipart/form-data" encoding type. If no encoding type is provided, the whole data passed as POST or PUT will be streamed to disk and a default file parameter name will be forced by Cheyenne.

So, when a file is uploaded, the file content is saved on disk using a temporary filename (for security concerns). This temporary file is deleted just after the RSP script execution. Request/store gives you an handy way to save this file from deletion, by using a internal "move" method when possible, or using a system call as fallback (the "move" operation is done in constant time whatever the file size is).

The default behaviour is to save the file to its original name in the incoming folder (used for all temporary files). The /as refinement allows you to specify a target folder and, optionaly, a target file name (to override the original file name).

Warning: it's recommended to check the file name suffix for all uploaded files to avoid security breaches, especially if the target file can be run by Cheyenne (like .rsp, .cgi, .php, ...). The best way to protect your site from that risk, is to store the files with server-generated names instead of original ones, and save the old/new names associations somewhere (in a file or database).

Notes:

Cheyenne stores temporary files in a default folder named %incoming/ (so, relative to Cheyenne home folder). This folder can be changed using the config keyword incoming-dir (in domain or webapp config sections of %httpd.cfg file) followed by the path to the new incoming folder.

Cheyenne accepts by default uploaded file size up to 2GB. This can be lowered by the (per domain or webapp) post-max config keyword followed by the maximum POST/PUT accepted data size.

For data sent to Cheyenne without the multipart/form-data encoding, the uploaded data is held in memory until a threshold size is reached, then it is streamed on disk. The default threshold value is 100KB. It can be set to any value up to 2GB using the config keyword post-mem-limit followed by the threshold value.

Session: RESET

Syntax

Description

Reset the session environment in WebApps. session/login? is set to FALSE and the ON-SESSION-START event is called. It's useful for resetting the session variables while maintaining the session.

Note: if it's used outside of a WebApp context, it has no effect.

Example

HTTP request: GET /change-user.rsp

change-user.rsp : <%
session/reset
response/redirect "login.rsp"
%>

Session: END

Syntax

session/end

Description

Destroy the current session if exists. All variables and values associated are lost.

Example

HTTP request: GET /logout.rsp

logout.rsp : <% session/end %>

Session: ACTIVE?

Syntax

value: session/active?
returns a logic!value.

Description

Returns TRUE if a session is currently active for the current user, otherwise FALSE.

Example

HTTP request: GET /test.rsp

test.rsp : <%
if not session/active? [
session/start
]
%>

Session: ADD

Syntax

session/addnamevaluename : new word to add to the session (word!).
value : initial value of the word (any-value!)

Description

Creates a new variable in the session context. This variable and its value will persist while the session is active or until you remove it.
Note: Remember that storing data in sessions takes resources and can have a negative impact on the performances of the RSP pages. Keep it as lightweight as possible.

Example

Session: TIMEOUT

Syntax

value: session/timeoutsession/timeout: new
new : new timeout value for the current session (time!)
returns a time! value.

Description

Sets or returns the session timeout value. This value define the maximum idle time before the session expires (idle time is defined as the time between two requests to the server from the same user).

Note: a session default timeout is defined by the 'timeout keyword in HTTPD.CFG config file in webapp or domain sections. If it's not explicitly defined anywhere, a default value of 20 minutes is used.

Example

Global: INCLUDE

Syntax

includefilename.rspfilename.rsp : RSP file to execute (file!)

Description

Loads and executes an RSP file, the generated output will be append to the current response buffer. This is useful to share common RSP code between several pages. For example, you could include dynamic header and footer with RSP code in all your pages using this function.

Note: you can recursively include a maximum of 5 RSP files, more than that would be insane ;-). This prevents from infinite cycles issues.

Example

Obviously, this is an academic example, it's really useful when you need to share a lot of code.

Global: INCLUDE-FILE

Syntax

include-filefilenamefilename : static file to include (file!)

Description

Loads and includes a static file (usually, it's an HTML file) by appending its content to the response buffer. No processing is done on the file. This is useful to share common HTML parts between several pages. For example, you could include a static header and footer in all your pages using this function.

Description

It's often unsafe to access a request parameter by using the following : request/content/name, if name hasn't been passed in the request, this expression will raise an error!.

The VALIDATE function is a handy way to pre-process the REQUEST/CONTENT block of parameters received from the client. The provided dialect lets you validate parameters by :

Ensuring that the parameter is present (by adding it with none! value, if required)

Casting the parameter to a given datatype

Adding a mandatory attribut

To define the required specs block, list all the parameters names you want to process, then define the target REBOL datatype, and optionally, add a mandatory attribut.

When the validation process is completed, the function returns a none! value indicating that all constraints are fulfilled, or a block! value listing all the parameter names that failed one or several tests.

Note:

The REQUEST/CONTENT values could be modified (converted to the required datatype) in the process, so if you use VALIDATE partially on a few parameters, then later, apply again VALIDATE on the other parameters, be sure to make separated list of parameters, don't validate twice the same parameter, it might generate false validation results.

If a value is use as third argument (with /full refinement), the parameter, if missing, will be set to that default value.

Global: DO-SQL

Syntax

value: do-sqldbquery
value: do-sql/flatdbquerydb : a db connection name defined in the config file (word!)
query : the SQL query or cached query name to execute (string!, block! or word!)
returns a block! or none! value.

Description

Preliminary Notice: The usage of DO-SQL is tight to the databases connections definitions specified in you HTTPD.CFG configuration file. If the databases section is not defined, DO-SQL would be useless. Here's an example of such configuration :

So, DO-SQL is a higher level function allowing you to access your databases in a consistant way, whatever database drivers you're using (from RT, Softinnov, 3rd party...) as long as the driver is embedded in a REBOL scheme handler and supports the basic port operation (open, insert, copy, pick, close).

The main principle of using DO-SQL is that all the connection's opening, re-opening and closing actions are taken in charge by the RSP engine. So, you can assume that all connections are always available and ready to use. DO-SQL will smartly handle the connections so that they will be opened only on the first use. It's all transparent for the RSP developer. By the way, the Cheyenne multi-processes architecture naturally generates a pool of databases connections, so using DO-SQL ensures that you have a clean and scalable database connection model.

Response: BUFFER

Syntax

Description

Directly access the RESPONSE buffer. This buffer is normaly filled by all the HTML template code from the executed RSP and by all the printing REBOL functions used in RSP pages. This property allows you to do any pre or post-processing on the generated page. It also allows you to generate the resulting buffer using other method than executing RSP code.

Setting response/buffer to a file! value is a powerful way to send back a static file to the client as a result of the RSP script without having to load it first in memory. Cheyenne will take care of sending the file in a streamed way to minimize memory usage. Be sure to use an absolute path for the file! value, else Cheyenne might not find it and the clent will get a 404 HTTP code instead. The mime type will be set by Cheyenne depending on the file extension, or you can force it using a content-disposition header.

Response: SET-STATUS

Syntax

response/set-statuscoderesponse/set-status/msgcodemessagecode : HTTP status return code (3 digits integer!).
message : Text message describing the status that will appear in
the first line of the HTTP response. (String!)

Description

Forces the HTTP return code and optionally, specify the text message for the returned status line. Note that, by default, Cheyenne will only use the following return codes : 200, 404, 501. You can override theses codes by using SET-STATUS.

The optional message is mostly useful in case of error codes, it should be displayed the client browser along with the error codes, giving you the opportunity to respond with a more accurate error message than the default one.

Response: SET-HEADER

Syntax

Description

Define HTTP headers' values. Giving a none! value will ensure that the header won't be sent with the response. This can be useful in many cases, like outputting a binary content (Image, PDF,...) instead of HTML content.

Cheyenne defines its own HTTP headers for the response, but the user-defined headers will prevail over Cheyenne's default ones.

Response: REDIRECT

Syntax

Description

Returns a HTTP redirection code 302 to the client asking it to jump to the target URL using a GET or HEAD method.

The /strict option produces a 303 return code, meaning that's a temporary redirection. A GET request will be issued by the client for retrieving the target URL.

The /thru option will return a HTTP code 307 asking the client to use the same HTTP method for requesting the target URL. An initial POST request will result, after the redirection, in a POST request to the target URL (as required by the HTTP v1.1 protocol).

The /last option will return a HTTP code 301 meaning that the resource has moved permanently.

Response: FORWARD

Syntax

response/forwardurlurl : Target URL (url!, string!).

Description

Stops the execution of the RSP and forwards the request to a new URL. RESPONSE/BUFFER will be cleaned before making the jump. The url argument have to be either a full URL with an explicit target or an absolute path to a target within the same host. All initial request parameters passed in GET or content passed in POST and all headers will be also forwarded to the new URL.

Note:

Cheyenne allows a maximum of 3 forwards for the same requests. This is done to avoid being caught in an infinite forwarding loop.

Using FORWARD when the page is in not-buffered mode is forbidden and will raise an error!. Not-buffered mode is entered when RESPONSE/FLUSH is used.

Example

HTTP request: GET /forward.rsp?var=1

forward.rsp :
<% response/forward "/test.rsp" %>
<html>
<body>
This part will never be sent to the client!
</body>
</html>
test.rsp : Result is <%=request/content/var%>
will output : Result is 1

Response: FLUSH

Syntax

response/flush

Description

Sends the current response buffer back to the client. The response buffer is then reset and the RSP execution continues. It's a way to stream data to the client without waiting to end of RSP execution.

Response: NO-LOG

Syntax

Description

By default, all requests generate an entry in the HTTP log file when the response is sent to the client. NO-LOG tells the engine to not write an entry in the log file for the current request only.

Example

HTTP request: GET /test.rsp

test.rsp :
<% response/no-log %>

Response: NO-COMPRESS

Syntax

response/no-compress

Description

By default, RSP response output is compressed (using the deflate algorithm) before being sent back to the client, if the client supports such compression (declared by client using the Accept-Encoding header). NO-COMPRESS tells the engine to not compress output for the current request only.

Event: ON-RSP-END

Syntax

Description

Example

Event: ON-APPLICATION-START

Syntax

Description

This event will only be generated when used in a web application context.

Event called when the web application is first used in a given background process. It's a good place to load application-specific code and data (like a configuration or preferences file).

Example

on-application-start: does [
do %private/config.conf
do %private/helper.r
do %private/captcha.r
captcha/set-fonts-path %private/fonts/
]

Event: ON-APPLICATION-END

Syntax

on-application-end: does [...]
Defined in %www/web-app/app-init.r

Description

This event will only be generated when used in a web application context.

Event called when a background process die. This event allows you to unload, if required, some libraries and free some external dependencies that are specific to your application and usually initialized in ON-APPLICATION-START.

Note: REBOL will free almost all open resources for you, so, you should use this event only for closing or releasing resources that require specific handling.

DB-Cache: INVALID

Syntax

Description

Forces the cache manager to refresh the query (or queries) next time they will be used. The database connection name have to match one of those defined in the "databases" section in the HTTPD.CFG file.

Example

Locale: SET-LANG

Syntax

locale/set-langidid: language identifier (word!)

Description

Defines the current language for translations done by the SAY function or statically embedded using the #[...] notation. The language id format is the standard one used by web browsers and transmitted to servers using the 'Accept-Language HTTP header. These ids are formatted as xx or xx-yy. Examples: fr, en, fr-FR, en-US,...

Note: If this function is not called, the following sequence will be executed to determine the appropriate language :

Use the session/content/lang value if defined

Use the language ID found in the Accept-Language header

Use the default language defined in HTTPD.CFG file

Use 'en (if 'en locale catalog file is not found, no translation will occur)

Description

Changes default settings for debug mode. Lines and colors apply to the trace file display accessible from the debug bar. Error controls if RSP errors are to be displayed inlined in the HTML page flow or in a popup overlay style. The ip option turns on the debug mode only for a given client IP address, allowing the site owner to debug issues on a RSP script in production without disturbing users. Default values are :