Updated February 2015

xcall CGIUTL, CGIOP_GETPARARY, status, $ary() {,string$}

Opcode 12, CGIOP_GETPARARY, retrieves the entire set of name=value pairs into an ordered map (aka associative array)

Parameters

status  (Num)  [out]

Returns the number of name=value pairs loaded. 0 indicates either that no name=value pairs were passed into the CGI request, or that the version of A-Shell is prior to 6.1.1394 when this function was introduced.

$ary()  (Ordered map)  [out]

An associative array to be loaded with the name=value pairs. It should be declared as follows:

dimx $ary, ordmap(varstr;varstr)

As with other parameters, you can name the array as you like, but you must specify the empty parentheses as in the example. This is special code to the subroutine to treat the parameter as an entire array, rather than as just one element. Also note that any existing contents of the array will not be automatically cleared, although any conflicting name=value pairs will be replaced. If reusing the array for multiple requests, you should probably use the .CLEAR function to clear it.

Note: for a brief period prior to compiler edit 734, it was necessary to use the syntax $ary("") instead of $ary(). That usage is still accepted but deprecated, as it could be too easily confused with a reference to a single element.

string$  (String)  [in]

If specified, the string$ parameter should contain the list of name=value pairs making up the request; see CGIOP_STDIN. Otherwise the request is taken directly from the stdin passed to the program by the web server.

Comments

The form of the request, whether in string$ or in stdin, should be:

name1=value1&name2=value2&...&nameN=valueN

Examples

For example, if assuming string$ = "fromCurrency=US&toCurrency=Euro", the following code...

dimx $req, ordmap(varstr;varstr)

xcall CGIUTL, CGIOP_GETPARARY, status, $req(), stdin$

print "fromCurrency = "; $req("fromCurrency")

will print:

fromCurrency = US

toCurrency = Euro

Or you can use a foreach loop to retrieve all of the name=value pairs without knowing in advance what to expect, i.e.

foreach $$i in $req()

    switch .key($$i)

        case "toCurrency"

            tocurr$ = $$i

            exit

        case "fromCurrency"

            fromcurr$ = $$i

            exit

        ...

    endswitch

next $$i