Passing Data to a RealWeb Subroutine

A RealWeb subroutine can accept no parameters, so any input data must be included in the URL. This can be done in the following ways:

• You can append a search (query) string and/or an anchor to the URL
• You can append additional path elements to the URL.

The Structure of a URL

A URL Uniform Resource Locator - a web address.  has the following general format:

protocol://hostname:port/pathname?search#hash

• The only part of a URL that is mandatory is pathname.
• The search portion of a URL provides a way of embedding arguments in the URL. Arguments are passed as name=value pairs, with multiple arguments separated by ampersands (&).

  These arguments can be processed in a RealWeb subroutine (by using the RW_GET_PARAM API Application Programming Interface - a set of functions that you can use in your programs to work with a component.  call) or, if included in the URL of a page displayed in the browser, by client-side code written in JavaScript A programming language supported by most web browsers. Client-side JavaScript allows executable content to be included with web pages.  or VBScript A programming language that allows executable content to be included with web pages. VBScript is supported only by Microsoft Internet Explorer. .

• The hash portion of a URL specifies a bookmark (anchor) within the web page.

For example:

http://www.foo.com/servlet/reality/hotelConnect/HOTEL/room?number=21#facilities

In the above, "HOTEL" is the name of a RealWeb subroutine and "room" is a parameter passed as an additional path element. In addition, the value 21 for parameter "number" is passed as a search string and the "facilities" anchor is specified.

Getting the Passed Data

The RW_GET_PARAM routine provides access to the various parts of the URL. You must specify the name of the parameter you require and a variable in which to return its value:

• Parameters passed as name=value pairs in search strings are accessible by name. For example, if the URL includes the name=value pair number=21, running

  CALL RW_GET_PARAM("number", RESULT)

  will set the RESULT variable to 21.

  Note: A parameter passed in this way can be changed and the new value passed on to another RealWeb subroutine; see Passing on Data to another Subroutine below.

• Parameters passed as additional path elements can be obtained by specifying "__page" as the parameter name (see RW_GET_PARAM for details).
• To obtain an anchor name, you must use the parameter name "__url" to obtain the full URL and then extract the anchor using DataBasic. For example:

  CALL RW_GET_PARAM("__url", RESULT)
  ANCHOR = GROUP(RESULT, "#", 2, 1)

Refer to the description of RW_GET_PARAM for details of other parameter names you can use.

Passing on Data to another Subroutine

If required, your RealWeb subroutine can call another RealWeb subroutine; any parameters passed to the original subroutine are passed on and can be accessed with RW_GET_PARAM.

The RW_SET_PARAM routine allows you to modify or add search string parameters. For example:

CALL RW_SET_PARAM("location", "annex")
CALL RWSubroutine2()

sets the "location" parameter to the value "annex" and then calls the subroutine RWSubroutine2.