Documentation Comments

Use this form to comment on this topic. You can also provide any general observations about the Online Documentation, or request that additional information be added in a future release.

RealityV15.1Online Documentation (MoTW) Revision 7

A First RealWeb Subroutine (RealWeb) (first.htm)

To	Reality
Version
Topic
Submitted by
Company
Location
Email address
Comment

A First RealWeb Subroutine

The majority of the routines in the RealWeb API Closed 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 Closed when the subroutine completes.

Note: Once the HTML has been placed in the output buffer, it cannot be changed. Many RealWeb routines (those with names beginning RWS_ and RWA_) allow you to construct your HTML in a string, so that you can process it further before copying it to an output buffer.

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.