1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<HTML><HEAD>
<TITLE>CGI Interface -- Input to CGI Programs</TITLE>
<LINK rel=Previous href="cgi-ch3.htm">
<LINK rel=ToC href="toc.htm">
<LINK rel=Index href="master.htm">
<LINK rel=Next href="cgi-ch5.htm">
</HEAD><BODY BGCOLOR="#ffffff"><A NAME="topofpage"></A>
<TABLE WIDTH=100%>
<TR>
<TD ALIGN=LEFT>
<A NAME="topofpage"></A> <IMG SRC="as-c-sm.gif">
</TD>
<TD ALIGN=RIGHT>
<A href="cgi-ch3.htm"><IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm> <IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm> <IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="cgi-ch5.htm"> <IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<A name="7983"> </A>
</TD>
</TR>
</TABLE>
<a name="8692">
</a><h3>Input to CGI Programs</h3>
<p><a name="8697">
</a>CGI programs can get input from these sources:</p>
<ul><li><b>Command line:</b> The only type of input that go to the command line of a CGI program are values typed into an <ISINDEX> field and query strings that do not contain an "=" sign (from a direct link). Forms cannot send variables to the command line.<a name="11900">
</a>
<p><li><b>Environment variables:</b> A number of standard environment variables are always available to the CGI program (see <a href="cgi-ch4.htm#8698">page 108</a>). You can specify additional environment variables in the AOLserver configuration file (see <a href="cgi-ch2.htm#26630">page 105</a>). And, if the METHOD for a form is GET, the field names and values are stored in the QUERY_STRING environment variable (see <a href="cgi-ch4.htm#12719">page 111</a>).<a name="11909">
</a>
<p><li><b>Standard input:</b> If the METHOD for a form is POST, the field names and values are sent to standard input (see <a href="cgi-ch4.htm#12745">page 114</a>).<a name="11910">
</a>
<p></ul><a name="11895">
</a><h4>Accessing Environment Variables</h4>
<p><a name="12082">
</a>Different languages allow you to access environment variables in different ways. Here are some examples:<Table Border = "3">
<tr><td><p><a name="12129">
</a>C or C++</p>
<td><p><a name="12131">
</a><code>#include <stdlib.h></code></p>
<p><a name="12152">
</a>char *browser = getenv("HTTP_USER_AGENT");</p>
<tr><td><p><a name="12137">
</a>Perl</p>
<td><p><a name="12139">
</a><code>$browser = $ENV{`</code>HTTP_USER_AGENT<code>'};</code></p>
<tr><td><p><a name="12145">
</a>Bourne shell</p>
<td><p><a name="12147">
</a><code>BROWSER=$</code>HTTP_USER_AGENT</p>
<tr><td><p><a name="15653">
</a>C shell</p>
<td><p><a name="15655">
</a><code>set BROWSER = $</code>HTTP_USER_AGENT</p>
</Table></p>
<a name="8698">
</a><h4>Standard Environment Variables</h4>
<p><a name="12301">
</a>These standard environment variables are defined for all CGI programs by the AOLserver:</p>
<a name="12709">
</a><h4>AUTH_TYPE: </h4>
<p><a name="13849">
</a>If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user. For CGI programs run by AOLserver, this is always "<code>Basic</code>". </p>
<p><a name="14081">
</a>Example: <code>Basic</code></p>
<a name="12710">
</a><h4>CONTENT_LENGTH:</h4>
<p><a name="14399">
</a>If the CGI program is run by a form with the POST method, this variable contains the length of the contents of standard input in bytes. There is no null or EOF character at the end of standard input, so in some languages (such as C and Perl) you should check this variable to find out how many bytes to read from standard input. (See <a href="cgi-ch4.htm#12719">page 111</a> for details about the format of the contents of standard input and <a href="cgi-ch4.htm#12745">page 114</a> for examples that read from standard input.)</p>
<p><a name="14400">
</a>Example: <code>442</code></p>
<a name="12711">
</a><h4>CONTENT_TYPE:</h4>
<p><a name="13942">
</a>If the CGI program is run by a form with the POST method, this variable contains the MIME type of the information sent by the browser. Currently, all browsers should send the information as <code>application/x-www-form-urlencoded</code>. Other types may be added in the future.</p>
<a name="12712">
</a><h4>GATEWAY_INTERFACE: </h4>
<p><a name="13543">
</a>The version number of the CGI specification this server supports.</p>
<p><a name="13548">
</a>Example: <code>CGI/1.1</code></p>
<a name="12713">
</a><h4>HTTP_ACCEPT:</h4>
<p><a name="13974">
</a>A comma-separated list of the MIME types the browser will accept, as specified in the HTTP header the browser sends. Many browsers do not send complete lists, and the list does not include external viewers the user has installed. If you want to send browser-specific output, you may also want to check the browser name, which is specified by the HTTP_USER_AGENT variable.</p>
<p><a name="14471">
</a>Examples: <code>*/*, application/x-navidoc</code></p>
<pre> <a name="14487"></a> <code>*/*, image/gif, image/x-xbitmap, image/jpeg
</code></pre><p><a name="12714">
</a><h4>HTTP_FROM:</h4>
<p><a name="14510">
</a>This variable <i>may</i> contain the email address of the reader who caused the CGI program to run. However, some browsers do not send the email address for privacy reasons. And, users may enter false email addresses in their preferences settings.</p>
<p><a name="14562">
</a>Example: <code>itsme@mydomain.com</code></p>
<a name="12715">
</a><h4>HTTP_IF_MODIFIED_SINCE:</h4>
<p><a name="14571">
</a>This variable contains a date and time if the browser wants a response only if the data has been modified since the specified date and time. The date is in GMT standard time. Many browsers do not send this information.</p>
<p><a name="14591">
</a>Example: <code>Thursday, 23-Nov-95 17:00:00 GMT</code></p>
<a name="14816">
</a><h4>HTTP_REFERER:</h4>
<p><a name="14817">
</a>This variable contains the URL of the page or other location from which the reader sent the request to run the CGI program. For example, if the reader runs the program from a form, this variable contains the URL of that form.</p>
<p><a name="14818">
</a>Example: <code>http://www.mydomain.com/mydir/feedback.htm</code></p>
<a name="12716">
</a><h4>HTTP_USER_AGENT:</h4>
<p><a name="14042">
</a>This variable tells which browser the reader is using to send the request. Normally, the format is "browser name/version".</p>
<p><a name="28323">
</a>Example: <code>Mozilla/1.2N (Windows; I; 16bit)</code></p>
<a name="12717">
</a><h4>PATH_INFO:</h4>
<p><a name="14681">
</a>This variable contains any extra path information included in the URL sent by the browser. Commonly, this type of URL is used to pass a relative directory location to your program. For example, the following URL runs the <code>listdir</code> program and passes it <code>/misc/mydir</code> as extra path information:</p>
<pre> <a name="14705"></a>
<a name="14704"></a><code>http://www.mysite.com/cgi-bin/listdir/misc/mydir
</code></pre><p><p><a name="14641">
</a>Another use for this type of URL is to pass information to the program without using a form or to pass form-specific variables in addition to the user-specified variables. For example:</p>
<pre> <a name="14723"></a>
<a name="14735"></a><code>http://www.mysite.com/cgi-bin/search/keyword=navigate
</code> <a name="14733"></a>
</pre><p><p><a name="14728">
</a>Examples: <code>/misc/mydir</code></p>
<pre> <a name="14768"></a> <code>/keyword=navigate
</code></pre><p><a name="12718">
</a><h4>PATH_TRANSLATED:</h4>
<p><a name="13706">
</a>This variable translates the relative path from PATH_INFO into the absolute path by prepending the server's root directory for Web documents. This is useful because PATH_INFO, which the reader can view, need not reveal the physical location of your files on the server.</p>
<p><a name="14808">
</a>Example: <code>/</code>AOLserver<code>/pages/misc/mydir</code></p>
<a name="12719">
</a><h4>QUERY_STRING:</h4>
<p><a name="13777">
</a>This variable contains information passed by a form or link to the program. The QUERY_STRING contains information in the following situations:</p>
<ul>
<li>The reader submitted a form that uses the GET method.<a name="14829">
</a>
<p><li>The reader submitted a query in a page with the <ISINDEX> tag. (The text the user types is also decoded and sent to the program's command line in this situation. The QUERY_STRING provides the non-decoded information.)<a name="14831">
</a>
<p><li>A direct link included information after a "?" in the URL.<a name="14856">
</a>
<p></ul>
<p><a name="14830">
</a>The QUERY_STRING is encoded in a format like this:</p>
<pre> <a name="15035"></a><code>
</code> <a name="15058"></a><code>Field1=Value1&Field2=Value2&Field3=Value3
</code></pre><p><p><a name="18746">
</a>Your CGI program should decode the QUERY_STRING. Functions that decode this string are publicly available functions for most languages. (See <a href="cgi-ch7.htm#8724">page 118</a> for a list of Web sites containing such functions.) The string encoding follows these rules:</p>
<ul>
<li>Field name/value pairs are separated by an "&" sign.<a name="14884">
</a>
<p><li>A field's name and its value are separated by an "=" sign. Field names are specified by the NAME attribute. Field values depend on the type of field:<a name="18912">
</a>
<p><dl>
<dt><b>Text field and text area: </b>The value is the text typed into the field. Multiline text is sent as one line with the return character encoded as described below.<a name="18913">
</a>
<p><dt><b>Radio Buttons: </b>The value is the value of the button that is selected. <a name="18914">
</a>
<p><dt><b>Checkbox: </b>The name and value usually appear in the list only if the box is checked. Some browsers may send the name of the checkbox only.<a name="18915">
</a>
<p><dt><b>Selection List: </b>The value of a selection list is the text of the item that is selected. If multiple items can be selected, there is a name/value pair with the same name for each item that is selected.<a name="18916">
</a>
<p><dt><b>Image Field: </b>Two name value pairs are sent. ".x" and ".y" are added to the field name and the values are the x and y coordinates (measured in pixels from an origin at the upper-left corner of the image). For example:<a name="18917">
</a>
<p></dl>
</ul>
<pre> <a name="18918"></a>Figfield.x=185&Figfield.y=37
<dl>
<dt><b>Hidden Fields: </b>You can use hidden fields with fixed values (or values set when a CGI program generated the page). The value is set with the VALUE attribute. Some older browsers make hidden fields visible.<a name="18919">
</a>
<p><dt><b>Range Fields: </b>The value is the numeric value of the field (sent as a string). Some browsers do not support range fields.<a name="18920">
</a>
<p><dt><b>Named Submit Buttons: </b>You can place multiple Submit buttons in a form. If you add a NAME attribute to the Submit button, that name will be sent, along with the label of the button as the value. All the Submit buttons in a form run the same CGI program, but the CGI program can perform different actions based on which button was clicked. Some browsers do not support named submit buttons.<a name="18921">
</a>
<p></dl>
</pre><p><ul>
<li>Spaces are replaced by "+" signs.<a name="14894">
</a>
<p><li>Special characters are replaced by a "%" sign followed by the hexadecimal value of the character. Here are some common characters and their hex values:<Table Border = "3">
<tr><td><p><a name="14926">
</a># -- %23</p>
<td><p><a name="14928">
</a><code>= -- %3D</code></p>
<td><p><a name="14930">
</a><code>/ -- %2F</code></p>
<tr><td><p><a name="14932">
</a>% -- %25</p>
<td><p><a name="14934">
</a><code>: -- %3A</code></p>
<td><p><a name="14936">
</a><code>\ -- %5C</code></p>
<tr><td><p><a name="14938">
</a>& -- %26</p>
<td><p><a name="14940">
</a><code>; -- %3B</code></p>
<td><p><a name="14942">
</a><code>tab -- %0A</code></p>
<tr><td><p><a name="14944">
</a>+ -- %2B</p>
<td><p><a name="14946">
</a><code>? -- %3F</code></p>
<td><p><a name="14948">
</a><code>return -- %09</code></p>
</Table><a name="14903">
</a>
<p></ul>
<a name="12720">
</a><h4>REMOTE_ADDR:</h4>
<p><a name="13818">
</a>The IP address of the machine from which or through which the browser is making the request. This information is always available.</p>
<p><a name="15166">
</a>Example: <code>199.221.53.76</code></p>
<a name="12721">
</a><h4>REMOTE_HOST:</h4>
<p><a name="13792">
</a>The full domain name of the machine from which or through which the browser is making the request. If this variable is blank because the browser did not send the information, use the REMOTE_ADDR variable instead.</p>
<p><a name="15206">
</a>Example: <code>mybox.company.com</code></p>
<a name="13915">
</a><h4>REMOTE_USER:</h4>
<p><a name="15242">
</a>If the server prompted the reader for a username and password because the script is protected by the AOLserver's access control, this variable contains the username the reader provided.</p>
<p><a name="15283">
</a>Example: <code>nsadmin</code></p>
<a name="12723">
</a><h4>REQUEST_METHOD:</h4>
<p><a name="13633">
</a>The method used to send the request to the server. For direct links, the method is "GET". For requests from forms, the method may be "GET" or "POST". Another method is "HEAD", which CGI programs can treat like "GET" or can provide header information without page contents.</p>
<a name="14044">
</a><h4>SCRIPT_NAME:</h4>
<p><a name="13750">
</a>The virtual path to the CGI script or program being executed from the URL used to execute the script. You may want to use this variable if the program generates a page that contains a form that can be used to run the program again -- for example, to search for another string.</p>
<p><a name="15364">
</a>Example: <code>/cgi-bin/search</code></p>
<a name="12725">
</a><h4>SERVER_NAME:</h4>
<p><a name="13505">
</a>The full hostname, domain name alias, or IP address of the server that ran the CGI program.</p>
<p><a name="13503">
</a>Example: <code>www.mysite.com</code></p>
<pre> <a name="15369"></a> <code>128.111.115.9
</code></pre><p><a name="12726">
</a><h4>SERVER_PORT:</h4>
<p><a name="13613">
</a>The server port number to which the request was sent. This may be any number between 1 and 65,535 (that is not already a well-known port). The default is 80.</p>
<p><a name="13617">
</a>Example: <code>80</code></p>
<a name="12727">
</a><h4>SERVER_PROTOCOL:</h4>
<p><a name="13572">
</a>The name and version number of the information protocol used to pass this request from the client to the server. </p>
<p><a name="13581">
</a>Example: <code>HTTP/1.0</code></p>
<a name="13464">
</a><h4>SERVER_SOFTWARE: </h4>
<p><a name="13465">
</a>The name and version number of the server software running the CGI program.</p>
<p><a name="13475">
</a>Example: AOLserver<code>/</code>3.0</p>
<a name="13329">
</a><h4>Other Environment Variables:</h4>
<p><a name="15468">
</a>In addition to the preceding environment variables, the HTTP header lines received from the client, if any, are placed into the environment with the prefix HTTP_ followed by the header name. Any spaces in the header name are changed to underscores (_). The server may exclude any headers it has already processed, such as Content-type, and Content-length.</p>
<p><a name="26701">
</a>Also, you can specify environment variables to be passed to a CGI program in the AOLserver configuration file (see <a href="cgi-ch2.htm#26630">page 105</a>).</p>
<a name="12745">
</a><h4>Accessing Standard Input</h4>
<p><a name="15612">
</a>If a form uses the POST method to send a request, the field names and values are sent to standard input and the length of this string is provided in the CONTENT_LENGTH environment variable. The format of the standard input string is the same as the format of the QUERY_STRING environment variable when the GET method is used (see <a href="cgi-ch4.htm#12719">page 111</a>).</p>
<p><a name="26707">
</a>Different languages allow you to access the standard input in different ways. Here are some simplified examples. Your programs should also do some error checking.<Table Border = "3">
<tr><td><p><a name="26710">
</a>C or C++</p>
<td><pre> <a name="26712"></a>#include <stdio.h>
<a name="26713"></a>#include <stdlib.h>
<a name="26714"></a>#define MAX_CONTENT_LENGTH 10000
<a name="26715"></a>
<a name="26716"></a>char *inputlenstr;
<a name="26717"></a>int inputlen;
<a name="26718"></a>int status;
<a name="26719"></a>char inputtext[MAX_INPUT_LENGTH+1];
<a name="26720"></a>
<a name="26721"></a>inputlenstr = getenv("CONTENT_LENGTH");
<a name="26722"></a>inputlen = atoi(inputlenstr);
<a name="26723"></a>status = fread(inputtext, 1, inputlen, stdin);
</pre><p>
<tr><td><p><a name="26733">
</a>Bourne shell</p>
<td><pre> <a name="26735"></a>read input (reads contents to $input variable)
</pre><p>
</Table></p>
<TABLE BORDER="2" CELLPADDING="1" width="100%">
<TR><TD COLSPAN=3><P ALIGN=Center>
<IMG SRC="bluebult.gif">
<A HREF="#topofpage">
<FONT SIZE=-1>Top of Page</FONT></A>
<IMG SRC="bluebult.gif">
</TD></TR>
<TR><TD COLSPAN=3><P ALIGN=Center>
<A href="cgi-ch3.htm">
<IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm>
<IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm>
<IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="cgi-ch5.htm">
<IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<BR align=center>
<FONT size=-1>Copyright © 1998-99 America Online,
Inc.</FONT>
</TD></TR></TABLE></BODY></HTML>
|
