Difference between revisions of "Recital Web Getting Started"

From Recital Documentation Wiki
Jump to: navigation, search
(→‎Request Object)
 
(34 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{YLM to do}}
 
 
==Overview==
 
==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.
  
−
Recital Web is a data centric HTTP Server that incorporates a Database 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. Using Recital Web, you can generate rich reports that can be integrated in with Recital Mirage .NET applications or Recital Terminal applications.
 
−
 
 
==RSP Basics==
 
==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 Firecat can serve static html pages, images, and Recital Server Pages (.rsp pages) similar to the way PHP dynamic pages are generated. With Recital Firecat .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.
+
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==  
 
==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 Firecat 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.  
+
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.  
 
The following example generates an HTML table that lists all the records in the Suppliers table.  
Line 42: Line 40:
 
</code>
 
</code>
  
−
Firecat/RSP also recognizes several directives. These are enclosed within <%@ and %>. The following directives are handled.
+
Recital/RSP also recognizes several directives. These are enclosed within <%@ and %>. The following directives are handled.
  
 
<code lang="html">
 
<code lang="html">
Line 54: Line 52:
 
</code>
 
</code>
  
−
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. The advantage of using this approach is that you can edit the .wsp file in Recital Enterprise Studio with full color syntax highlighting and IntelliHelp. If you use this approach, it is advisable to keep all of the .wsp files in the scripts subdirectory of webroot. e.g.
+
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.
  
 
<code lang="html">  
 
<code lang="html">  
Line 60: Line 58:
 
</code>
 
</code>
 
   
 
   
−
When you use Recital Enterprise Studio to develop and test your .rsp pages, it will automatically synchronize JavaScript and .wsp files into the wwwscripts directory and images (.gif, .jpg, and .png) into the wwwimages directory.
 
  
−
==Quick Start Guide==
+
==Default page==
−
# Create or add an existing RSP page to your project. To add existing RSP pages to the project, select Project|Add Files To Project... from the Menu Bar .
+
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.  
−
# Test the RSP page by right clicking on it in the "Project Explorer" then choose "Run".  
+
  
−
Tip
+
<pre>http://localhost:8001/recital</pre>
−
If you use the attribute <%@ codebehind="scripts/filename.wsp" %> in the RSP file, you can edit the Recital 4GL code with full syntax color highlighting and IntelliHelp.
+
  
−
# Use the showdocument() function in your server based Mirage application to send the request for an RSP page and for the content to be generated dynamically and then rendered in the browser on the desktop PC.
+
Would reference:
  
−
<code lang="recital">
+
<pre>http://localhost:8001/recital/default.rsp</pre>
−
showDocument("http://" + getLocalHost() + ":8001/myrspfile.rsp", "_blank")
+
−
</code>
+
  
−
Note
 
−
By default the Firecat 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 also, or alternatively use the Recital ISAPI filter on Windows or the Apache loadable module (mod_recital) on Linux/UNIX.
 
  
−
==Default page==
+
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 [[DB_PORT80_ENABLED|configure it to run on port 80]] as well, or alternatively use the Apache loadable module (mod_recital or, for 64-bit, mod_recital64.so) to use the configured Apache port.
−
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 Firecat will use the page default.rsp. e.g.
+
−
http://localhost:8001
+
−
Would reference:
+
−
http://localhost:8001/default.rsp
+
  
 
==Array Variables==
 
==Array Variables==
−
Server configuration and request information, including form parameters are accessible from several public arrays that are created automatically by the Firecat web server when it is servicing a request for a page.
+
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.
 
The elements stored in these public arrays can be accessed by name e.g.
  
Line 94: Line 81:
  
 
===_SERVER[ ] array===
 
===_SERVER[ ] array===
−
The _SERVER[] array can include the following:
+
The _SERVER[ ] array can include the following:
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 146: Line 133:
  
 
===_GET[ ] and _POST[ ] arrays===
 
===_GET[ ] and _POST[ ] arrays===
−
It is easy to process forms in the Firecat/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 Firecat/RSP page. The key to the arrays elements are the parameter names and the values are the values of those parameters.  
+
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===
 
===_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).  
+
This array contains all of the cookies that are sent from the client browser when a page is requested. You reference these by cookie name. You can send cookies to the client browser using the response.addcookie() method call and access the automatic Recital session cookie. (See the response object and example below for further details).
  
−
===_ARGS[ ] array===
+
===_ARGS[ ] and _REQUEST[ ] arrays===
−
You can reference the value of any arguments passed to the Firecat/RSP page by referencing them by name in the _ARGS[ ] array.
+
You can reference the value of any arguments passed to the Recital/RSP page by referencing them by name in the _ARGS[ ] or _REQUEST[ ] arrays.
 +
You can also use the getparameter() function to reference the arguments and set a default value if the argument is not included.
 +
 
 +
<code lang="recital">
 +
// set column width to the 'width'  argument, defaulting to 250 if not set
 +
colwidth = getParameter("width", "250")
 +
</code>
 +
 
 +
===_SESSION[ ] array===
 +
Session information can be stored by adding elements to the _SESSION[ ] array.  (See the response object below for an example).  Sessions are automatically removed when they have been inactive for one hour.
  
 
==Request Object==
 
==Request Object==
Line 187: Line 183:
 
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.
 
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()
+
Example of response.addcookie() and using the _COOKIE[ ], _SERVER[ ] and _SESSION[ ] arrays.
  
−
<code lang="html">
+
<code lang="recital">
 +
<%@ Language="Recital" %>
 +
<% response.addcookie("my_cookie_name","my_cookie_value") %>
 +
<html>
 +
<head>
 +
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
 +
<title>Recital Request Object</title>
 +
</head>
 +
<body>
 +
<%
 
// get the hostname for the remote machine requesting the page
 
// get the hostname for the remote machine requesting the page
−
host = _server["REMOTE_HOST"]
+
? "_SERVER[ ] elements"
−
 
+
foreach _SERVER as name=>value
−
<%@ Language="Recital" %>  
+
  ? "<br>   &name="+etos(value)
−
<html>  
+
next
−
<head>
+
? "<br><br>"
−
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+
? date()
−
<% response.addcookie("foo","bar") %>
+
? time()
−
<title>Recital Request Object</title>
+
? "<br><br>"
−
</head>  
+
cc=len(_COOKIE)
−
<body>  
+
if cc > 0
−
<%
+
? "Active session Cookies ("+alltrim(str(cc))+")"
−
? date()  
+
foreach _COOKIE as name=>value
−
? time()  
+
  ? "<br>  &name="+etos(value)
−
? "<br><br>"  
+
endfor
−
cc=len(_COOKIE)  
+
else
−
if cc > 0  
+
? "There are no active session cookies."
−
  ? "Active session Cookies ("+alltrim(str(cc))+")"  
+
endif
−
  for i = 1 to cc
+
? "<br><br>"
−
    ? "<br>  &i "  
+
ss=len(_SESSION)
−
    ? _COOKIE[&i]
+
if ss > 0
−
   next  
+
? "Active session variables ("+alltrim(str(ss))+")"
−
else  
+
foreach _SESSION as name=>value
−
  ? "There are no active session cookies."  
+
   ? "<br>  &name="+etos(value)
−
endif  
+
next
−
? "<br><br>Press the refresh key."  
+
else
−
%>  
+
? "There are no active session variables."
−
</body>  
+
endif
−
</html>  
+
? "<br><br>Press the refresh key."
 +
_SESSION["time"] = time()
 +
%>
 +
</body>
 +
</html>
 
</code>
 
</code>
  
 +
==Apache Module==
 +
Recital Web can be run as a standalone web server via port 8001 and/or via port 80 with [[DB_PORT80_ENABLED]] set to true.  Alternatively, the Recital module can be used to run Recital ".rsp", ".wsp" and ".prg" scripts via Apache.  During installation of Recital, you are prompted to install the Recital module if Apache is detected.  This installs '''mod_recital.so''' in the Apache ''modules'' directory and the '''recital.conf''' file in the Apache ''conf.d'' directory.
 +
 +
<pre>
 +
# recital.conf
 +
# Recital Firecat is an HTML-embedded scripting language which attempts to
 +
# make it easy for developers to write dynamically generated webpages.
 +
#
 +
LoadModule recital_module    modules/mod_recital.so
 +
#
 +
# Cause the Recital Firecat Server to handle files with a .rsp, .prg or .wsp
 +
# extension.
 +
#
 +
AddHandler recital-handler .rsp
 +
AddHandler recital-handler .wsp
 +
AddHandler recital-handler .prg
 +
</pre>
 +
 +
This is the 32-bit Recital module.  The 64-bit Recital module , '''mod_recital64.so''', is also shipped in the distribution, but not automatically installed.  To install it, copy '''/opt/recital/lib/mod_recital64.so''' into the Apache ''modules'' directory and modify the '''LoadModule''' line in the '''recital.conf''' file in the Apache ''conf.d'' directory as follows.
 +
 +
<pre>
 +
LoadModule recital_module    modules/mod_recital64.so
 +
</pre>
 +
 +
Restart Apache to load the module.
 +
 +
==Virtual Host Support==
 +
Recital Web 10.0.2 and above includes support for virtual hosts, providing the ability to host multiple applications and websites on the same server.
 +
 +
The virtual host is defined in the [[DB_WWWROOT]] environment variable:
 +
 +
<pre>
 +
DB_WWWROOT=/usr/recital/{SERVER_NAME}/webroot/
 +
</pre>
 +
 +
e.g.
 +
 +
<pre>
 +
DB_WWWROOT=/usr/recital/linuxdev_localdomain/webroot/
 +
</pre>
 +
 +
You may also have to create a symbolic link to allow access via the IP address, e.g.
 +
 +
<pre>
 +
/usr/recital/127_0_0_1/webroot
 +
</pre>
 +
 +
Note: '.' is changed to '_'.
 +
 +
The _SERVER[ ] array will return the correct IP address and hostname for the virtual server.
 
[[Category:Recital Web]]
 
[[Category:Recital Web]]

Latest revision as of 12:32, 7 February 2012

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/recital

Would reference: 

http://localhost:8001/recital/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 or, for 64-bit, mod_recital64.so) 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 cookie name. You can send cookies to the client browser using the response.addcookie() method call and access the automatic Recital session cookie. (See the response object and example below for further details).

_ARGS[ ] and _REQUEST[ ] arrays

You can reference the value of any arguments passed to the Recital/RSP page by referencing them by name in the _ARGS[ ] or _REQUEST[ ] arrays. You can also use the getparameter() function to reference the arguments and set a default value if the argument is not included. 

// set column width to the 'width'  argument, defaulting to 250 if not set
colwidth = getParameter("width", "250")

_SESSION[ ] array

Session information can be stored by adding elements to the _SESSION[ ] array. (See the response object below for an example). Sessions are automatically removed when they have been inactive for one hour.

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() and using the _COOKIE[ ], _SERVER[ ] and _SESSION[ ] arrays. 

<%@ Language="Recital" %>
<% response.addcookie("my_cookie_name","my_cookie_value") %>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Recital Request Object</title>
</head>
<body>
<%
// get the hostname for the remote machine requesting the page
? "_SERVER[ ] elements"
foreach _SERVER as name=>value 
   ? "<br>   &name="+etos(value)
next
? "<br><br>"
? date()
? time()
? "<br><br>"
cc=len(_COOKIE)
if cc > 0
 ? "Active session Cookies ("+alltrim(str(cc))+")"
 foreach _COOKIE as name=>value 
   ? "<br>   &name="+etos(value)
 endfor
else
 ? "There are no active session cookies."
endif
? "<br><br>"
ss=len(_SESSION)
if ss > 0
 ? "Active session variables ("+alltrim(str(ss))+")"
 foreach _SESSION as name=>value 
   ? "<br>   &name="+etos(value)
 next
else
 ? "There are no active session variables."
endif
? "<br><br>Press the refresh key."
_SESSION["time"] = time()
%>
</body>
</html>

Apache Module

Recital Web can be run as a standalone web server via port 8001 and/or via port 80 with DB_PORT80_ENABLED set to true. Alternatively, the Recital module can be used to run Recital ".rsp", ".wsp" and ".prg" scripts via Apache. During installation of Recital, you are prompted to install the Recital module if Apache is detected. This installs mod_recital.so in the Apache modules directory and the recital.conf file in the Apache conf.d directory. 

# recital.conf
# Recital Firecat is an HTML-embedded scripting language which attempts to
# make it easy for developers to write dynamically generated webpages.
#
LoadModule recital_module     modules/mod_recital.so
#
# Cause the Recital Firecat Server to handle files with a .rsp, .prg or .wsp
# extension.
#
AddHandler recital-handler .rsp
AddHandler recital-handler .wsp
AddHandler recital-handler .prg

This is the 32-bit Recital module. The 64-bit Recital module , mod_recital64.so, is also shipped in the distribution, but not automatically installed. To install it, copy /opt/recital/lib/mod_recital64.so into the Apache modules directory and modify the LoadModule line in the recital.conf file in the Apache conf.d directory as follows. 

LoadModule recital_module     modules/mod_recital64.so

Restart Apache to load the module.

Virtual Host Support

Recital Web 10.0.2 and above includes support for virtual hosts, providing the ability to host multiple applications and websites on the same server.

The virtual host is defined in the DB_WWWROOT environment variable: 

DB_WWWROOT=/usr/recital/{SERVER_NAME}/webroot/

e.g. 

DB_WWWROOT=/usr/recital/linuxdev_localdomain/webroot/

You may also have to create a symbolic link to allow access via the IP address, e.g. 

/usr/recital/127_0_0_1/webroot

Note: '.' is changed to '_'.

The _SERVER[ ] array will return the correct IP address and hostname for the virtual server.

Retrieved from "https://www.recitalsoftware.com/wiki/index.php?title=Recital_Web_Getting_Started&oldid=16079"