Two ways to Build your HTML
The RealWeb Buffers
When your RealWeb subroutine completes, the contents of four buffers are used to construct the web page that is returned to the browser. These buffers are as follows:
RWC.OUTBUF This is the normal target of
API
routines that generate HTML directly. Note, however, that many routines write to
or modify the contents of a string variable (see Subroutine Types below).
RWC.HEADBUF Routines that require HTML to be placed within the
<head> section of the HTML
document append their output to this buffer. These include style definitions and imported
stylesheets.
RWC.JSBUF Routines that directly generate
JavaScript code, or import items that
contain such code, append their output to this buffer so that all of this code can be grouped together in the final HTML document. When the HTML
document is opened, the code in RWC.JSBUF is placed in suitable script
tags and are copied into the <head> section of the document along with the
contents of RWC.HEADBUF.
RWC.ERRORBUF If errors are encountered at runtime during the execution of any of the RealWeb API routines, error messages may be generated. These messages are appended to RWC.ERRORBUF. The RWS_GET_BUFroutine allows the application to examine and modify the contents of any of the RealWeb buffers before it terminates. This gives you an opportunity to pick up any errors that may have occurred and to substitute standard error handling HTML pages as required.
Subroutine Types
The destination of the output from an API routine is determined by the type of the output and the type of the subroutine:
- Where the name of a routine begins with RW_ the routine outputs to the appropriate RealWeb buffer (RWC.OUTBUF in most cases).
- String routines, where the routine name is prefixed by RWS_, take a string variable as an extra parameter, change this in some way and return the modified string.
- Append routines, where the routine name is prefixed by RWA_, take a string variable as an extra parameter and append the generated HTML to this string rather than to one of the RealWeb buffers.
If you use the RWS_ and RWA_ routines to construct your HTML, you must use the RW_PUT routine to copy it to the output buffer. If another buffer would be more appropriate, use RW_PUT_EX and specify the buffer you require.
For example:
PARA = "Hello World!" CALL RWS_PARA(PARA, "", "") CALL RW_PUT(PARA)
This sets the PARA variable to the string "Hello World!", then formats it as an HTML paragraph and copies it to the output buffer.
Alternatively, you could use the following:
CALL RW_START_PARA("", "")
CALL RW_PUT("Hello World!")
CALL RW_END_PARA
In this case, the HTML to start a paragraph (<p>) is appended
to the output buffer, followed by the text and then the end-of-paragraph tag (</p>).
These examples produce an identical result, but the first one would allow you to carry out further processing if required before committing the HTML to the output buffer.