Request Object

Description

The Request object provides access to the values that the browser passed to the server during an HTTP request.

Syntax

Request.property|method([parameters])

Properties

CurrentChannel The number of the channel serving the current request.
PathInfo Extra path information as given by the client. This parameter mirrors the information passed by the browser in the PATH_INFO server variable.
ProgramPath The directory where the requested script resides.
ProgramRoot The effective program root for the requested server.
ScriptParams The part of the URL that is after the script name, but before the query string.
StartSeconds The number of seconds since midnight from the time the request was received.
StartTime The date and time that the request was received.

Methods

CookieArray Returns an array with all cookies sent by the client. Optionally, it can filter all occurrences of a particular cookie.
CookieCount Returns the total number of cookies, or the total number of occurrences of a single cookie.
Form Returns the content of a form field passed to the server as part of a POST request.
FormArray Returns an array with all POST fields, or all instances of a particular field.
FormCount Returns the total number of POST fields, or the total number of occurrences of a single field.
FormFieldObject Returns an object which contains information about a particular POST field. This function is especially useful when processing uploaded files.
GetCookie Returns the value of a cookie sent by the HTTP client.
Item Searches all browser input (The query string, form variables, cookies and the server variables) for a particular value.
QueryString Returns the content of a field sent by the browser in the Query String portion of the URL.
QueryStringArray Returns an array with all Query String fields, or all instances of a particular field.
QueryStringCount Returns the total number of Query String fields, or the total number of occurrences of a single field.
ServerVariables Returns the content of a Server Variable, sent by the browser, or provided by the Web server.
ServerVariablesArray Returns an array with all Server Variables.
ServerVariablesCount Returns the total number of Server Variables.

CurrentChannel Property

Description

The Request.CurrentChannel property returns the number of the channel serving the current request.

This property is read only.

Syntax

nChannel = Request.CurrentChannel


PathInfo Property

Description

The Request.PathInfo property returns the extra path information as given by the client. This parameter mirrors the information passed by the browser in the PATH_INFO server variable. This property is read/write and can be modified in the FW_ENTER global procedure, in order to redirect FoxWeb to a different script than the one requested by the user.

The PathInfo property can also be used to construct self-referencing URLs in cases where the use of relative URLs is not possible.

This property is read/write.

Syntax

Request.PathInfo = cPath


ProgramPath Property

Description

The Request.ProgramPath property returns the physical directory where the requested script resides.

This property is read only.

Syntax

cPath = Request.ProgramPath


ProgramRoot Property

Description

The Request.ProgramRoot property returns the effective Program Root directory for the requested virtual server.

This property is read only.

Syntax

cPath = Request.ProgramRoot


ScriptParams Property

Description

The Request.ScriptParams property returns the part of the URL that is after the .fwx script name, but before the query string. Some sites (including the FoxWeb Forum) utilize such URLs to create parameterized pages that are indexed by certain search engines that do not support query strings. For example, then URL http://www.mysite.com/MyScript.fwx/011/003302?display=html would cause Request.ScriptParams to be populated with "011/003302". In order to use this URL syntax, the script name in the URL must be followed with ".fwx" (regardless of whether you are calling a .fwx, .prg, or .fxp file).

This property is read only.

Syntax

cScriptParams = Request.ScriptParams


StartSeconds Property

Description

The Request.StartSeconds property returns the number of seconds that have elapsed since midnight from the time that the request was received. This property is populated by calling VFP's SECONDS() function right before starting execution of the requested script. Request.StartSeconds returns a numeric value in decimal format, with a resolution of 1 millisecond. If you are running Windows NT 4.0 or later, resolution is 10 milliseconds.

This property is read only.

Syntax

nSeconds = Request.StartSeconds


StartTime Property

Description

The Request.StartTime property returns the date and time that the request was received. This property is populated by calling VFP's DATETIME() function right before starting execution of the requested script.

This property is read only.

Syntax

tDateTime = Request.StartTime


CookieArray Method

Description

The Request.CookieArray method returns an array with all cookies sent by the client. Optionally, it can filter all occurrences of a particular cookie.

Syntax

nTotCookies = Request.CookieArray(@aCookies[, cCookieVar])

Parameters

aCookies

A two-dimensional array that gets populated with all the cookie pairs. This parameter must be passed by-reference, by preceding its name with the "@" character.

cCookieVar

Optional parameter that contains the name of the cookie whose instances should populate the aCookies array. It is possible for the browser to send multiple instances of a cookie with the same name, if it has received the same cookie with different path designators.

Return Value

Numeric: The number of rows in the output array.


CookieCount Method

Description

The Request.CookieCount method returns the total number of cookies, or the total number of instances of a single cookie.

Syntax

nTotCookies = Request.CookieCount([cCookieVar])

Parameters

cCookieVar

Optional parameter, which contains the name of the cookie whose number of instances should be returned. It is possible for the browser to send multiple instances of a cookie with the same name, if it has received the same cookie with different path designators. If this parameter is omitted then the total number of cookies is returned.

Return Value

Numeric: The total number of cookies, or the number of instances of a particular cookie, sent by the browser.


Form Method

Description

The Request.Form method returns the values of form fields posted to the HTTP request body by a form using the POST method.

Syntax

cFieldValue = Request.Form([cFormVar, [nIndex]])

Parameters

cFormVar

Specifies the name of the form field from which the method is to retrieve values.

nIndex

Optional parameter that contains the desired instance of cFormVar. You can determine the total number of instances of a particular field with the Request.FormCount method. If multiple instances of the same field exist and this parameter is omitted, then the function returns all values, as a comma-delimited string.

Return Value

Character: The value of the specified field.

Remarks

When you use parameters with Request.Form, the Web server parses the HTTP request body and returns the specified data. If your application requires un-parsed data from the form, you can access it by calling Request.Form() without any parameters. If the requested field was not sent by the browser then this method will return an empty string. To distinguish between form fields that contain an empty string and form fields that were not sent use the Request.FormCount method.


FormArray Method

Description

The Request.FormArray method returns an array with all form fields sent by the client. Optionally, it can filter all occurrences of a particular field.

Syntax

nTotFields = Request.FormArray(@aFormFields[, cFormVar])

Parameters

aFormFields

A two-dimensional array that gets populated with all the form elements and their values. This parameter must be passed by-reference, by preceding its name with the "@" character.

cFormVar

Optional parameter that contains the name of the field whose instances should populate the aFormFields array.

Return Value

Numeric: The number of rows in the output array.


FormCount Method

Description

The Request.FormCount method returns the total number of form fields submitted through the POST method, or the total number of instances of a single field.

Syntax

nTotFields = Request.FormCount([cFormVar])

Parameters

cFormVar

Optional parameter, which contains the name of the field whose number of instances should be returned. If this parameter is omitted then the total number of fields is returned.

Return Value

Numeric: The total number of form fields, or the number of instances of a particular field, sent by the browser.


FormFieldObject Method

Description

The Request.FormFieldObject method is similar to Request.Form, but instead of returning just the value of a POST field, it returns an object, which contains extended information. This method is especially useful when processing uploaded files, because it exposes information such as the original file name, the size of the file, its contents and its mime type.

Syntax

oFormField = Request.FormFieldObject([cFormVar, [nIndex]])

Parameters

cFormVar

Specifies the name of the form field.

nIndex

Optional parameter that contains the desired instance of cFormVar. You can determine the total number of instances of a particular field with the Request.FormCount method. If multiple instances of the same field exist and this parameter is omitted, then the function returns all values, as a comma-delimited string.

Return Value

FormField object. The following table describes the properties and methods of FormField objects:

ContentDisposition The value of the ContentDisposition header for the field. This value is only populated for uploaded files.
ContentLength The size of the form field.
ContentStart The field's position in the POST data buffer.
ContentType The field's content type, as provided by the browser.
FileName The uploaded file's original file name, as provided by the browser. This value is only populated for uploaded files.
FieldName The field name.
Value() This method returns the contents of the field.

GetCookie Method

Description

The Request.GetCookie method returns the values of Cookies sent by the browser.

Syntax

cFieldValue = Request.GetCookie([cCookieVar, [nIndex]])

Parameters

cCookieVar

Specifies the name of the cookie whose value we want to retrieve.

nIndex

Optional parameter that contains the desired instance of cCookieVar. It is possible for the browser to send multiple instances of a cookie with the same name, if it has received the same cookie with different path designators. If this parameter is omitted then the instance with the most specific path is returned. You can determine the total number of instances of a particular cookie with the Request.CookieCount method.

Return Value

Character: The value of the specified cookie.

Remarks

When you use parameters with Request.GetCookie, the Web server parses the HTTP_COOKIE Server Variable and returns the specified value. If your application requires un-parsed data, you can access it by calling Request.GetCookie() without any parameters, or Request.ServerVariables("HTTP_COOKIE"). If the requested cookie was not sent by the browser then this method will return an empty string. To distinguish between cookies that contain an empty string and cookies that were not sent use the Request.CookieCount method.


Item Method

Description

The Request.Item method searches browser input for a particular value. The following collections are searched in the order listed:

  1. Query String
  2. Form Variables (POST data)
  3. Cookies
  4. Server Variables

Syntax

cFieldValue = Request.Item([cVarName, [nIndex]])

Parameters

cVarName

Specifies the name of the variable whose value we want to retrieve.

nIndex

Optional parameter that contains the desired instance of cVarName.

Return Value

Character: The value of the specified variable.

Remarks

If a value with the same name exists in more than one collection then the method returns the first instance that it encounters. For improved performance it is recommended that you use a more specific method than Item wherever possible. For example, use Request.ServerVariables("PATH_INFO") instead of Request.Item("PATH_INFO").


QueryString Method

Description

The Request.QueryString method returns the values of the variables in the HTTP Query String. The Query String contains values passed to your script as text following a question mark in the URL. The values can be appended to the URL by using either the HTTP GET method or by manually appending the values to the URL.

Syntax

cFieldValue = Request.QueryString([cQueryStringVar, [nIndex]])

Parameters

cQueryStringVar

Specifies the name of the Query String variable from which the method is to retrieve values.

nIndex

Optional parameter that contains the desired instance of cQueryStringVar. You can determine the total number of instances of a particular variable with the Request.QueryStringCount method. If multiple instances of the same variable exist and this parameter is omitted, then the function returns all values, as a comma-delimited string.

Return Value

Character: The value of the specified variable.

Remarks

When you use parameters with Request.QueryString, the Web server parses the Query String portion of the URL and returns the specified data. If your application requires un-parsed data, you can access it by calling Request.QueryString() without any parameters, or by calling Request.ServerVariables("QUERY_STRING"). If the requested variable was not sent by the browser then this method will return an empty string.


QueryStringArray Method

Description

The Request.QueryStringArray method returns an array with all variables sent in the HTTP Query String sent by the client as part of the URL. Optionally, it can filter all occurrences of a particular variable.

Syntax

nTotVars = Request.QueryStringArray(@aQueryStringVars[, cQueryStringVar])

Parameters

aQueryStringVars

A two-dimensional array that gets populated with all the QueryString variables and their values. This parameter must be passed by-reference, by preceding its name with the "@" character.

cQueryStringVar

Optional parameter that contains the name of the variable whose instances should populate the aQueryStringVars array.

Return Value

Numeric: The number of rows in the output array.


QueryStringCount Method

Description

The Request.QueryStringCount method returns the total number of Query String variables, or the total number of instances of a single variable.

Syntax

nTotVars = Request.QueryStringCount([cQueryStringVar])

Parameters

cQueryStringVar

Optional parameter, which contains the name of the variable whose number of instances should be returned. If this parameter is omitted then the total number of variables is returned.

Return Value

Numeric: The total number of Query String variables, or the number of instances of a particular variable, sent by the browser.


ServerVariables Method

Description

The Request.ServerVariables method returns the values of the environment variables known as HTTP Server Variables. The Server Variables is a collection of values that provides information from the HTTP headers, passed along with a userís request, as well as information provided by the Web server, regarding the current request.

Syntax

cValue = Request.ServerVariables([cServerVariable])

Parameters

cServerVariable

Specifies the name of the Server Variable whose value we are trying to retrieve.

Return Value

Character: The value of the specified variable.

Remarks

Unlike other elements returned by the Request object, there may not be more than one instance of a particular Server Variable. If the requested variable does not exist then this method will return an empty string. Calling Request.ServerVariables() without any parameters will return the buffer that holds all the Server Variables passed on to FoxWeb.

Common Server Variables

Following is a list of most Server Variables with brief descriptions.

Note: Not all variables below will be available to your scripts. The list of variables that are exposed to your scripts will depend on the individual request, the Web server being used, whether you are using the CGI or ISAPI module, and the type of browser that originated the request.


Variable Description
AUTH_PASSWORD The value entered in the client's authentication dialog. This variable is available only if Basic authentication is used.
AUTH_TYPE If execution of the CGI program is protected, this is the protocol-specific authentication method used to authenticate the user.
AUTH_USER If execution of the CGI program is protected, this is the user name (in the indicated realm) that the client used to authenticate for access to the CGI program.
CERT_COOKIE Unique ID for client certificate, returned as a string. Can be used as a signature for the whole client certificate.
CERT_FLAGS bit 0 is set to 1 if the client certificate is present.

bit 1 is set to 1 if the cCertification authority of the client certificate is invalid (it is not in the list of recognized CAs on the server).

CERT_ISSUER Issuer field of the client certificate (O=MS, OU=IAS, CN=user name, C=USA).
CERT_KEYSIZE Number of bits in Secure Sockets Layer connection key size. For example, 128.
CERT_SECRETKEYSIZE Number of bits in server certificate private key. For example, 1024.
CERT_SERIALNUMBER Serial number field of the client certificate.
CERT_SERVER_ISSUER Issuer field of the server certificate.
CERT_SERVER_SUBJECT Subject field of the server certificate.
CERT_SUBJECT Subject field of the client certificate.
CONTENT_LENGTH The length of the POST data as given by the client.
CONTENT_TYPE The data type of the content. Used with queries that have attached information. Example: "application/x-www-form-urlencoded".
GATEWAY_INTERFACE The revision of the CGI specification used by the server. The format is CGI/revision.
HTTP_ACCEPT Returns the value of the Accept header.
HTTP_ACCEPT_LANGUAGE Returns a string describing the language to use for displaying content.
HTTP_USER_AGENT Returns a string describing the browser that sent the request.
HTTP_COOKIE Returns the cookie string that was included with the request.
HTTP_REFERER Returns a string containing the URL of the original request when a redirect has occurred.
HTTPS Returns ON if the request came in through secure channel (SSL) or it returns OFF if the request is for a non-secure channel.
HTTPS_KEYSIZE Number of bits in Secure Sockets Layer connection key size. For example, 128.
HTTPS_SECRETKEYSIZE Number of bits in server certificate private key. For example, 1024.
HTTPS_SERVER_ISSUER Issuer field of the server certificate.
HTTPS_SERVER_SUBJECT Subject field of the server certificate.
LOCAL_ADDR Returns the Server IP Address on which the request came in. This is important on multi-homed machines where there can be multiple IP addresses bound to the machine and you want to find out which address the request used.
LOGON_USER The Windows account that the user is logged into.
PATH_INFO Extra path information as given by the client. You can access scripts by using their virtual path and the PATH_INFO server variable. If this information comes from a URL, it is decoded by the server before it is passed to the CGI script.
PATH_TRANSLATED A physical directory that corresponds to PATH_INFO.
QUERY_STRING The information which follows the (?) in the URL, without any decoding or translation. You can also access information sent in the Query String, using the Request object.
REMOTE_ADDR The IP address of the remote host making the request.
REMOTE_HOST The name of the host making the request. If the server does not have this information, it will either leave this variable empty, or populate it with the IP address. In order to get this variable to return the host name you need to turn on reverse DNS lookups on your server. Note that this may slow the server down under heavy loads. Refer to your Web server's documentation on how to turn reverse DNS lookups on.
REMOTE_USER Unmapped user-name string sent in by the user. This is the name that is really sent by the user, as opposed to the names that are modified by any authentication filter installed on the server.
REQUEST_METHOD The method used to make the request. For HTTP, this is GET, HEAD, POST, and so on.
SCRIPT_NAME A virtual path to the script being executed. This can be used to construct self-referencing URLs.
SERVER_NAME The server's host name, DNS alias, or IP address as it would appear in self-referencing URLs.
SERVER_PORT The port number to which the request was sent.
SERVER_PORT_SECURE A string that contains either 0 or 1. If the request is being handled on the secure port, then this will be 1. Otherwise, it will be 0.
SERVER_PROTOCOL The name and revision of the request information protocol. The format is protocol/revision.
SERVER_SOFTWARE The name and version of the server software that answers the request and runs the gateway. The format is name/version.
URL Gives the base portion of the URL.

ServerVariablesArray Method

Description

The Request.ServerVariablesArray method returns an array with all Server Variables passed on to FoxWeb.

Syntax

nTotVars = Request.ServerVariablesArray(@aServerVars)

Parameters

aServerVars

A two-dimensional array that gets populated with all Server Variables and their values. This parameter must be passed by-reference, by preceding its name with the "@" character.

Return Value

Numeric: The number of rows in the output array.


ServerVariablesCount Method

Description

The Request.ServerVariablesCount method returns the total number of Server Variables passed to FoxWeb

Syntax

nTotVars = Request.ServerVariablesCount()

Return Value

Numeric: The total number of Server Variables.


© Aegis Group