Executing Scripts

A script is simply another resource on the web server which you can access using the HTTP control. Scripts may be complete programs written in a language like Perl, or they may be scripting code intermixed with HTML, such as with ASP and PHP. In most cases, the scripts either generate HTML output which is typically displayed in a browser or XML which will be parsed by the client.

The two most common ways to execute a script is to use either the GetData or PostData methods. In the examples that we'll be using the script will be written in Perl, however this information applies to ASP and PHP as well. Executing a script that does not require any input is as simple as retrieving an HTML document:

Dim strOutput As String
Dim nError As Long

HttpClient1.URL = "http://sockettools.com/cgi-bin/test.cgi"

nError = HttpClient1.Connect()
If nError = 0 Then
    nError = HttpClient1.GetData(HttpClient1.Resource, strOutput)
    HttpClient1.Disconnect
End If

In this example, the script /cgi-bin/test.cgi is executed on the server, and the HTML output that it generates is returned to the program in the strOutput variable. The the first few lines of HTML returned by the script looks like this:

<html>
<head>
<title>Test Script</title>
<meta http-equiv="pragma" content="no-cache">
</head>
<body>
<h3>Query Parameters</h3>
No query parameters were passed to this script<br>
<h3>Form Variables</h3>
No form variables were passed to this script<br>
<h3>Environment Variables</h3>
<b>DOCUMENT_ROOT</b> = "/var/www/html"<br>
<b>GATEWAY_INTERFACE</b> = "CGI/1.1"<br>

Note that near the beginning, there are the lines "No query parameters were passed to this script" and "No form variables were passed to this script". This is because this test script is also capable of displaying any data passed to the script in the form of parameters or form variables. These are the two methods that can be used by a client to provide a script with additional information. The way that the script processes that information, and which method is used, is determined by how the script is written. This is an important point when developing client applications that interact with web scripts. As the client, you need to know what data the script expects and how it expects that data to be passed to it, either as one or more parameters or as form data which would typically be entered using a web browser.

Query Parameters

A script can have data passed to it through one or more parameters which are provided along with the name of the script to be executed. For example, if you wanted to pass two parameters to our test script named "param1" and "param2" with the values of "value1" and "value2" respectively then the URL would look like this:

http://sockettools.com/cgi-bin/test.cgi?param1=value1&param2=value2

The question mark separates the name of the resource from its arguments. Each argument consists of a name-value pair, separated by an equal sign. If there is more than one name-value pair, then they are separated by an ampersand. If we modify the example above to use this URL with the query parameters, the first few lines of output returned by the script now looks like this:

<html>
<head>
<title>Test Script</title>
<meta http-equiv="pragma" content="no-cache">
</head>
<body>
<h3>Query Parameters</h3>
<b>param1</b> = "value1"<br>
<b>param2</b> = "value2"<br>
<h3>Form Variables</h3>
No form variables were passed to this script<br>
<h3>Environment Variables</h3>
<b>DOCUMENT_ROOT</b> = "/var/www/html"<br>
<b>GATEWAY_INTERFACE</b> = "CGI/1.1"<br>

You'll notice that the Query Parameters heading now lists the two arguments with their name-value pairs. Passing query parameters to a script is the easiest method a client can use to provide information to that script. However, most servers have a limit on the maximum length of a URL including any parameters; that value is typically around 8,192 bytes, however it can vary from server to server. Although query parameters are convenient when the script does not require a lot of data, there needs to be a method where larger amounts of data can be provided. This is where form data comes in.

Form Data

When an HTML page presents a form to the user with text boxes, dropdown lists and so forth, that data is typically submitted to a script that is specified by the <form> element. For example, let's consider a simple HTML form:

<form action="http://sockettools.com/cgi-bin/test.cgi" method="post">
  <input type="text" name="data1" value=""><br>
  <input type="text" name="data2" value=""><br>
  <input type="submit">
</form>

The <form> element provides you two very important pieces of information. The first is the name of the script that will process the data entered by the user. This is specified by the action attribute. The second is how the data will be passed to the script, and that's specified by the method attribute. If the form uses the "get" method, then you'll want to use the control's GetData method as described in the previous section. However, if the form uses the "post" method, then you'll need to use the control's PostData method instead.

In the HTML form, there are two text input fields named "data1" and "data2". For the next example, let's say that you want to write a program that submits data to the script as though the user entered the string "testing1" in the first text box, and "testing2" in the second and then clicked the submit button.

Dim strOutput As String
Dim strFormData As String
Dim nError As Long

HttpClient1.URL = "http://sockettools.com/cgi-bin/test.cgi"
strFormData = "data1=testing1&data2=testing2"

nError = HttpClient1.Connect()
If nError = 0 Then
    nError = HttpClient1.PostData(HttpClient1.Resource, strFormData, strOutput)
    HttpClient1.Disconnect
End If

You'll notice that the code is substantially similar to the example that uses GetData, with the exception that the form data is passed as a separate argument to the PostData method. The same convention applies, with the name-value pairs be separated by an equal sign, and multiple pairs being separated by an ampersand. When the PostData method is used, the first few lines of output that would be returned would look like this:

<html>
<head>
<title>Test Script</title>
<meta http-equiv="pragma" content="no-cache">
</head>
<body>
<h3>Query Parameters</h3>
No query parameters were passed to this script<br>
<h3>Form Variables</h3>
<b>data1</b> = "testing1"<br>
<b>data2</b> = "testing2"<br>
<h3>Environment Variables</h3>
<b>CONTENT_LENGTH</b> = "29"<br>
<b>CONTENT_TYPE</b> = "application/x-www-form-urlencoded"<br>
<b>DOCUMENT_ROOT</b> = "/var/www/html"<br>
<b>GATEWAY_INTERFACE</b> = "CGI/1.1"<br>

Now, instead of there being query parameters, the script reports that there are two form variables, "data1" and "data2" and it displays their values. This is the same output that you would get from clicking on the submit button in the HTML form.