Recital Web Getting Started
Contents
Overview
Recital Web is a data centric HTTP Server that incorporates a database engine and 4GL. Using Recital Web you can generate dynamic content web pages with the Recital/4GL. Recital Web can coexist with the existing Web Server on your system, so there is no disruption to your existing web site infrastructure.
RSP Basics
The Recital Web HTTP server handles the generation of dynamic content HTML and sends this back to the browser that requested the page. These pages have a ".rsp" extension (Recital Server Page). Recital Web can serve static html pages, images, and Recital Server Pages (.rsp pages) similar to the way PHP dynamic pages are generated. With Recital Web .rsp pages, you can embed Recital/4GL scripting commands inside HTML documents. Recital Server Pages are really just HTML files with Recital/4GL scripting embedded within them. Any scripting commands that are embedded within the file are executed then removed from the results. All scripting code is hidden from the user viewing your web pages.
Tags
To distinguish the RSP code from the regular HTML inside the .rsp file, RSP code is placed between <% and %> tags. The tag combination notifies the Recital HTTP Server that the code within the <% and %> should be executed by the server and removed from the results. Any output generated by the Recital/4GL code (e.g. using the ? command) will be written to the HTML output that is sent back to the web browser that requested the page.
The following example generates an HTML table that lists all the records in the Suppliers table.
<html> <body> <table> <% open database southwind use suppliers scan ? "<tr>" for f=1 to fldcount() ? "<td>" ? &(field(f)) ? "</td>" next ? "</tr>" endscan use close databases %> </table> </body> </html>
You can also echo the result of inline expressions directly using the <%= and %> tags.
<input type="text" name="customer_name" value="<%= &(field(1)) %>">Recital/RSP also recognizes several directives. These are enclosed within <%@ and %>. The following directives are handled.
<%@ include="xxx" %>This directive allows you to include either other RSP files, JavaScript files or HTML files within your .rsp page. This provides the ability to build library pages that can be reused by many .rsp pages.
<%@ codebehind=".wsp filename" %>This directive allows you to write a .wsp file (Recital program file with a .wsp extension) which can be used to dynamically generate and output the HTML. If you use this approach, it is advisable to keep all of the .wsp files in the scripts subdirectory of webroot. e.g.
<%@ codebehind="scripts/myproc.wsp" %>
Default page
The DB_WWWDEFAULT environment variable can be set to point to a default page that will be referenced if a URL is given which does not have a page specified. If this is not found, then Recital Web will use the page default.rsp. e.g.
http://localhost:8001
Would reference:
http://localhost:8001/default.rsp
By default the Recital web server listens on port 8001 so this must be postfixed to the hostname that it is running on as is specified in the sample code above. You can however configure it to run on port 80 as well, or alternatively use the Apache loadable module (mod_recital) to use the configured Apache port.
Array Variables
Server configuration and request information, including form parameters are accessible from several public arrays that are created automatically by the Recital web server when it is servicing a request for a page. The elements stored in these public arrays can be accessed by name e.g.
// get the hostname for the remote machine requesting the page host = _server["REMOTE_HOST"]
_SERVER[ ] array
The _SERVER[] array can include the following:
| Argument | Description | Example |
|---|---|---|
| SERVER_SOFTWARE | A string that identifies the server | Apache/1.3.22 (Unix) |
| SERVER_NAME | The hostname, DNS alias, or IP address for self referencing URLs | www.yoursite.com |
| SERVER_PROTOCOL | The name and revision of the requested protocol | HTTP/1.1 |
| SERVER_PORT | The server port number to which the request was sent | 8001 |
| REQUEST_METHOD | The method the client used to fetch the document | GET |
| PATH_INFO | Extra path elements given by the client | /list/records |
| PATH_TRANSLATED | The value of the PATH_INFO translated by the server into a full path | /usr/recital/webroot/list/records |
| SCRIPT_NAME | The URL path of the current page | /list/records/customers.rsp |
| QUERY_STRING | Everything after the ? in the URL | count=10&data=true |
| REMOTE_HOST | The hostname of the machine that requested this page | mypc.mydomain.com |
| REMOTE_ADDR | A string containing the IP address of the machine that requested the page | 192.168.0.100 |
| CONTENT_TYPE | The content type of the information attached to queries such as PUT and POST | x-url-encoded |
| CONTENT_LENGTH | The length of the information attached to queries such as PUT and POST | 3866 |
| AUTH_TYPE | The authorization realm | BASIC (This is the only one supported) |
| REMOTE_USERNAME | The username specified after response.authenticate() | johnd |
| REMOTE_PASSWORD | The password specified after response.authenticate() | fd89haIk |
| HTTP_ACCEPT_ENCODING | Acceptable methods of content encoding | gzip, deflate |
| HTTP_UA_CPU | User agent processor type | x86 |
| HTTP_USER_AGENT | Browser id or user-agent string identifying the browser | Mozilla/4.0 (...) |
| HTTP_CONNECTION | Connection type | Keep-Alive |
| HTTP_CACHE_CONTROL | Client cache instructions | no-cache |
| HTTP_REFERER | URL of referring document | http://www.yoursite.com:8001/default.rsp |
_GET[ ] and _POST[ ] arrays
It is easy to process forms in Recital/RSP as the forms parameters are available in the _GET[ ] and _POST[ ] arrays. Use these arrays to access form parameters from your Recital/4GL code in the Recital/RSP page. The key to the arrays elements are the parameter names and the values are the values of those parameters.
_COOKIE[ ] array
This array contains all of the cookies that are sent from the client browser when a page is requested. You reference these by cookies name. You can send cookies to the client browser (session state can be saved and restored) using the response.addcookie() method call. (See the response object below for further details).
_ARGS[ ] array
You can reference the value of any arguments passed to the Recital/RSP page by referencing them by name in the _ARGS[ ] array.
Request Object
When a web page is requested, along with the HTTP request, information such as the URL of the web page request and the format of the data requested is also passed. It can also contain the name and contents of form variables on the user's form that requested the page. The response object allows you to control the way the server interacts with the browser.
The methods that can be specified are as follows:
| Argument | Description | Example |
|---|---|---|
| WRITE | Writes a string of text | response.write("<table>") |
| REDIRECT | Redirects to another URL | response.redirect("http://www.recital.com") |
| WRITEFILE | Writes out the contents of a file. Note: the path is relative to DB_WWWROOT | response.writefile("/temp/myreport.html") |
| APPENDTOLOG | Writes a line of text to the Recital system log | response.appendtolog("opening database southwind") |
| FLUSH | Flushes out the buffers and sends to the browser | response.flush() |
| CLEAR | Clears (resets) the output buffer | response.clear() |
| ADDHEADER | Sends response headers | response.addheader("Content-Type", "text/plain") |
| ADDCOOKIE | Sends a cookie to the browser | response.addcookie("my_cookie_name", "my_cookie_value") |
| AUTHENTICATE | Causes the browser to prompt for a username/password | response.authenticate() |
| IMPERSONATEUSER | Impersonates the specified user. This is used to handle file permissions for accessing pages. | response.impersonateUser("username","password") |
Special note: When sending response headers or cookies, these must be sent before any text that is output. Cookie data is automatically converted to a string value when stored, but can only be retrieved as a string.
Example of response.addcookie()
<%@ Language="Recital" %> <% // get the hostname for the remote machine requesting the page host = _server["REMOTE_HOST"] %> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <% response.addcookie("foo","bar") %> <title>Recital Request Object</title> </head> <body> <% ? date() ? time() ? "<br><br>" cc=len(_COOKIE) if cc > 0 ? "Active session Cookies ("+alltrim(str(cc))+")" for i = 1 to cc ? "<br> &i " ? _COOKIE[&i] next else ? "There are no active session cookies." endif ? "<br><br>Press the refresh key." %> </body> </html>
