A First RealWeb Subroutine

The majority of the routines in the RealWeb API Application Programming Interface - a set of functions that you can use in your programs to work with a component.  are used to construct an HTML page that is returned for display in the browser. This is done by adding code to to the appropriate RealWeb output buffer, depending upon the type of HTML output; see RealWeb Buffers. The contents of the output buffers are returned to the reality servlet A server-side Java program that services HTTP requests and returns HTTP responses.  when the subroutine completes.

In order to construct a valid HTML document, the routines must be called in the correct order. The minimum necessary to construct an empty document is a call to RW_START_HTML_PAGE, followed by a call to RW_END_PAGE; for example:

SUBROUTINE EMPTY_PAGE()
    INCLUDE #RW.INCLUDE.DEFS FROM /SYSFILES/REALWEB,BP
    CALL RW_START_HTML_PAGE("My Page", "", "", "", "")
    CALL RW_END_PAGE
RETURN

This creates an empty document with the title "My Page". Other calls can be made between RW_START_HTML_PAGE and RW_END_PAGE to construct the document. Note that the subroutine does not accept any parameters and that the #RW.INCLUDE.DEFS item is included.

RW_START_HTML_PAGE and RW_END_PAGE must always be used as a pair. Several other API routines must also be used together; this is indicated in the Dependencies section on the individual pages.

Note that, if the HTML you require cannot be created using the RealWeb API , you can write your own and append it to the output buffer using RW_PUT. Alternatively, you can save the HTML in a REALITY item and insert it using RW_INSERT_ITEM.

The following example extends that shown above by including the text "Hello World" on the page:

SUBROUTINE HELLOWORLD
     * Display the text 'Hello World'
     * Include the RealWeb definitions
     INCLUDE #RW.INCLUDE.DEFS FROM /SYSFILES/REALWEB,BP
     * Start the HTML page.
     *   Display the text 'Hello World' in the browser's title bar.
     CALL RW_START_HTML_PAGE("Hello World", "", "", "", "")
     * Start a paragraph.
     CALL RW_START_PARA("", "")
     * Insert the required text.
     CALL RW_PUT("Hello World")
     * End the paragraph.
     CALL RW_END_PARA
     * Complete the page.
     CALL RW_END_PAGE
RETURN

Enabling your RealWeb Subroutine

Before a RealWeb subroutine can be called by the reality servlet , it must be enabled. This ensures that inappropriate subroutines are not called accidentally or otherwise.

To enable a subroutine, create an item with the same name in the file REALWEB.SECURITY in the RealWeb account concerned. The item-id must be the same as that of the subroutine and the item should have a single attribute containing the letter V.

Failing to create an item in REALWEB.SECURITY will result in the error "Subroutine not allowed"  being displayed when the subroutine is accessed via a URL.

See also RealWeb Security.