CgiString Method (RUNTIME)

9.8A

The CgiString method retrieves CGI (Common Gateway Interface) data that is received by the PWS when a PLB program is started. This method fetches the query string found in the HTTP request header. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A RUNTIME object.

return

Optional. A Character String Variable that receives the CGI data from the HTTP Request header fields.

keyname

Required. A Character String Variable or literal that specifies the keyword name string that defines the CGI data to be retrieved.

mask

Required. A Numeric Variable or decimal number that identifies the specific RUNTIME directory type to be returned.

Flags Affected: EOS, OVER, ZERO

Note the following:

1. This method fetches the query string found in the HTTP request header. The full query string data stream can be retrieved or individual keyword named query string parameters can be retrieved. Normal precautions should be used when using CGI data like any other web server environment.

2. The 'PLBWEB_CGI_INFODIR={[path]+prefix}' must be specified in the Plbwebsrv.ini to enable PWS CGI data collecting. If this keyword is not used, there is no CGI data collected by the PWS server and this method returns a NULL data string.

3. The EOS flag is set TRUE if the return variable is too small to receive the browser storage\cookie data string result without being truncated.

4. The ZERO and over flags are always cleared.

5. The *OPTIONS {mask} values are defined as follows:

 

Mask Value	Description
0x0	The default action by this method occurs when the *OPTIONS parameter is set to zero or when this parameter is not used. The default method operation is retrieve the QUERY_STRING or pre-defined HTTP Request header fields. See note (6A.) for more details.
0x1	This bit value causes this method to retrieve the data for a user specified keyword specified in the Query_String. See note (6B.) for more details.
0x2	This bit value causes this method to perform the same operation as described for the '0x0' default operation except all '+' characters are changed to a 0x20 blank character. In addition, al URL encoded character sequences are encoded. See note (7.) for more details.

 

6. When CGI data is being collected by the PWS server, there are two sets of data available to the PLB program that was transferred from the browser to the PWS server:

1. The HTTP Request header fields of the original GET or POST message are captured so the PLB program can retrieve these fields. See the following link for more details on the HTTP header fields:

 

https://en.wikipedia.org/wiki/Common_Gateway_Interface

 

The PWS ONLY supports the following HTTP Request field keywords that can be retrieved using the CgiString method:

 

AUTH_TYPE

CONTENT_LENGTH

CONTENT_TYPE

QUERY_STRING

REMOTE_ADDR

REQUEST_METHOD

REQUEST_URI

SCRIPT_NAME

SERVER_SOFTWARE

SERVER_PROTOCOL

SERVER_PORT

HTTP_ACCEPT

HTTP_ACCEPT_ENCODING

HTTP_ACCEPT_LANGUAGE

HTTP_COOKIE

HTTP_HOST

HTTP_REFERER

HTTP_USER_AGENT

 

2. When the browser performs the initial logon operation, a QUERY_STRING can be added to the URL, a HTML form using a GET or POST request. The QUERY_STRING contains keyword data that can be used by a PLB program. See the following link for more details on a QUERY_STRING:

 

https://en.wikipedia.org/wiki/Query_string

 

7. The QUERY_STRING data can be retrieved either in a raw URL encoded format (i.e., Default behavior) or in a cooked mode (i.e. *OPTIONS=2) where the data is decoded to remove the URL encoding sequences. See the following link for more details on URL Encoding:

 

http://www.w3schools.com/tags/ref_urlencode.asp

 

8. The following examples show CgiString operations that retrieve data when the 'PLBWEB_CGI_INFODIR' keyword is declared in the 'plbwebsrv.ini' configuration file.

 

Example I. - Retrieve QUERY_STRING Raw Encoded Data

 

R RUNTIME //Runtime object Raw Encoded Data

    R.CgiString Giving DATA Using "QUERY_STRING"

 

Example II. - Retrieve QUERY_STRING Decoded Data

 

    R.CgiString Giving DATA Using "QUERY_STRING",2

 

Example III. - Retrieve QUERY_STRING 'Name' Keyword Data

 

    R.CgiString Giving DATA Using "Name",1

 

Example IV. - Retrieve QUERY_STRING 'cmdline' Keyword Data

 

    R.CgiString Giving DATA Using "cmdline",1

 

Example V. - Retrieve HTTP 'REQUEST_URL' Keyword Data

 

    R.CgiString Giving DATA Using "REQUEST_URI"

 

Example VI. - Retrieve HTTP 'HTTP_USER_AGENT' Keyword Data

 

    R.CgiString Giving DATA Using "HTTP_USER_AGENT"

 

9. When a REST API request is accepted by a PWS server, the PWS server extracts the Http header data from the request and stores it into a CGI data file. In this case,the PWS server stores the CGI data into a file based on the PWS keyword named 'PLBWEB_CGI_INFODIR'. Also, the PWS server starts a PL/B runtime including the command line option '-cgi <filename>'.

10. When the PL/B runtime detects the new command line option named '-cgi <filename>', the PL/B runtime preloads the <filename> data so the RUNTIME object 'CgiString' method can access the CGI keyword data. The CGI keywords are the same as described for the 'CgiString' for a PWS server program. After the <filename> data is preloaded, the PL/B runtime deletes the temporary CGI file before the PL/B REST program starts executing.

11. If the CGI 'AUTH_TYPE' keyword has a returned string value of 'Basic', these CGI keywords are available with meaningful data:

 

AUTH_USER

REMOTE_USER

AUTH_DATA

12. This method is not available under Windows CE.

See Also: RUNTIME, RUNTIME Methods, Method Syntax