home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _81a9545b716b27ed1567bac1af7c018d < prev    next >
Text File  |  2004-06-01  |  44KB  |  918 lines
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  2.  
  3. <html>
  4.  
  5. <head>
  6. <title>Active Server Pages</title>
  7. <link rel="STYLESHEET" href="../Active.css" type="text/css">
  8. </head>
  9.  
  10. <body>
  11.  
  12. <table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EAE2BB">
  13. <tr> 
  14. <td width="57"><a target=_blank href="http://www.ActiveState.com/ActivePerl/">
  15. <img src="../images/activeperl_logo.gif" width="57" height="48" border="0" alt="ActivePerl"></a></td>
  16. <td><div align="center" class="heading">ActivePerl User Guide</div></td>
  17. <td width="112"><a target=_blank  href="http://www.ActiveState.com">
  18. <img src="../images/AS_logo.gif" width="112" height="48" border="0"  alt="ActiveState" /></a></td>
  19. </tr>
  20. <tr>
  21. <td class="lineColour" colspan="3"></td>
  22. </tr>
  23. </table>
  24.  
  25. <h1>Active Server Pages</h1>
  26.  
  27. <ul>
  28.   <li><a class="doc" href="#introduction">Active Server Pages</a>
  29.     <ul>
  30.       <li><a class="doc" href="#thescriptdelimiters">The Script Delimiters</a></li>
  31.       <li><a class="doc" href="#thescriptinghost">The Scripting Host</a></li>
  32.       <li><a class="doc" href="#aquickexample">Creating An ASP Page</a></li>
  33.     </ul>
  34.   </li>
  35.   <li><a class="doc" href="#asp_api">The ASP Interface</a>
  36.     <ul>
  37.       <li><a class="doc" href="#theaspobjects">The ASP Intrinsic Objects</a></li>
  38.       <ul>
  39.         <li><a class="doc" href="#application">The Application Object</a></li>
  40.         <li><a class="doc" href="#asperror">The ASPError Object</a></li>
  41.         <li><a class="doc" href="#objectcontext">The ObjectContext Object</a></li>
  42.         <li><a class="doc" href="#request">The Request Object</a></li>
  43.         <li><a class="doc" href="#response">The Response Object</a></li>
  44.         <li><a class="doc" href="#server">The Server Object</a></li>
  45.         <li><a class="doc" href="#session">The Session Object</a></li>
  46.       </ul>
  47.     </ul>
  48.   <li><a class="doc" href="#aspsamples">Active Server Pages Samples</a>
  49.     <ul>
  50.       <li><a class="doc" href="#hw">Say "Hello World!"</a></li>
  51.       <li><a class="doc" href="#sv">Accessing HTTP Server Variables</a></li>
  52.       <li><a class="doc" href="#qs">Reading the QueryString</a></li>
  53.       <li><a class="doc" href="#wf">Interactive Web Forms</a></li>
  54.       <li><a class="doc" href="#dc">Database Connections (ADO and ASP)</a></li>
  55.     </ul>
  56.   <li><a class="doc" href="#bindata">Variants and Binary Data</a>
  57.     <ul>
  58.       <li><a class="doc" href="#readblob">To Read And Display Binary Large Objects (ADO and
  59.         ASP)</a></li>
  60.     </ul>
  61.   <li><a class="doc" href="#appa">Appendix A</a>
  62.     <ul>
  63.       <li><a class="doc" href="#appasysdsn">How To Set Up A System DSN</a>
  64.       <li><a class="doc" href="#appanosysdsn">Why Not To Use A System DSN</a>
  65.       <li><a class="doc" href="#appaoledb">How To Use The Native OLE DB Provider</a>
  66.     </ul>
  67.   <li><a class="doc" href="#appb">Appendix B</a>
  68.     <ul>
  69.       <li><a class="doc" href="#appbbook">Book Resources</a>
  70.       <li><a class="doc" href="#appbonline">Online Resources</a>
  71.     </ul>
  72.   <li><a class="doc" href="#author and copyright">AUTHOR AND COPYRIGHT</a></li>
  73. </ul>
  74.  
  75. <h2><a name="introduction">Active Server Pages (ASP)</a></h2>
  76. <p>Introduced in 1996, Active Server Pages (ASP) is an easy to learn server-side
  77. technology from Microsoft that has taken the web by storm. ASP is implemented as
  78. a set of objects with built-in features for fast and simple access to common
  79. services provided by the web-server for the Internet. As we will see, there are
  80. versatile reasons for using ASP as a server-side technology with ActivePerl.</p>
  81.  
  82. <p>To begin, if you in general are unfamiliar with server-side technologies, let's
  83. start at the core by describing the need-to-know about ASP. ASP is a feature
  84. that installs with Microsoft's Internet Information Services (IIS) web-server.
  85. No special interaction or configuration is needed afterwards, and it should run
  86. out of the box just as easily as IIS. Fundamentally, a server-side technology
  87. such as ASP puts no requirements on the client or browser, and, as a result, no
  88. browser-compatibility issues will ever occur, no browser plug-ins have to be
  89. installed, and the client does not need a local installation of ActivePerl.</p>
  90.  
  91. <p>Since there are no client requirements for ASP, it needs something on the
  92. server-side that tells it what to do with its features. A special implementation
  93. of a scripting language is therefore installed on the server and used in order
  94. to control and program ASP; PerlScript, which installs with ActivePerl, is
  95. suitable for the role as scripting language because it brings the power of Perl
  96. into the environment of ASP and there merges it with the services provided by
  97. ASP. There are only two things that you either may already know or will need to
  98. learn while using PerlScript:</p>
  99. <ul>
  100.   <li>The Active Server Pages Object Model
  101.   <li>How Perl Works with Objects
  102. </ul>
  103. <p>On the Internet, ASP serves documents of its own filetype as opposed to
  104. familiar document types like HTML documents. This is so that the ASP document
  105. can be processed on the server side before returned to the client's browser. An
  106. ASP document has the file extension .asp, and it provides both existing features
  107. derived from ASP and the ability to execute script commands within the document.
  108. The file extension is by the webserver recognized in a special way which results
  109. in the underlying technology executing script commands that are within the file
  110. and treat other markup such as HTML in a standard fashion. The source code of
  111. your saved file's PerlScript script commands will by default never be available
  112. to the user when choosing to view the document source in the browser, so any
  113. script that you write can not be copied. The reason for this is because
  114. everything is processed on the server side and what is returned to the browser
  115. is a standard format such as HTML.</p>
  116.  
  117. <p>For a closure, it deserves to be repeated that if you are unfamiliar with
  118. object-oriented programming in Perl, it is strongly recommended that you
  119. sometime browse the Perl documentation on object-oriented programming to get a
  120. basic understanding of the aspects of an object and its origin. Next up, let's
  121. look at how to embed PerlScript commands within an ASP document.</p>
  122.  
  123.  
  124. <h2><a name="thescriptdelimiters">The Script Delimiters</a></h2>
  125. <p>To successfully execute the script commands within an ASP file, you must specify
  126. what scripting language ASP should use to interpret the script commands. You can
  127. do this within the .asp document by either setting a default scripting language
  128. in which all script commands within the script-delimiters <% and %>    will be
  129. executed by the specified scripting language. Either you can apply that setting
  130. within the Microsoft Management Console's IIS snap-in or you can use what
  131. ASP recognizes as a page command, which is indicated by the special directive @.
  132. The following example is for illustrational purposes only and it shows you how
  133. to set the default scripting language for the ASP file to PerlScript; as a
  134. result, all commands will be treated by the PerlScript engine; however, please
  135. note that no actual output or result is being displayed by the script, so if you
  136. run the code shown in the example below, you won't see an output although the
  137. code is being executed and interpreted.</p>
  138. <ul>
  139.   <code><br>
  140.   <%@ Language=PerlScript %><br>
  141.   <%<br>
  142.   for($i=0; $i<=10; $i++) {<br>
  143.   #<br>
  144.   # Your Perl code here<br>
  145.   #<br>
  146.   }<br>
  147.   %></code>
  148. </ul>
  149.  
  150. <p>In addition to page-commands, you can set the scripting language for a defined
  151. scope by using the <code><SCRIPT Language=PerlScript RUNAT=Server></code>
  152. and <code></SCRIPT></code> delimiters. This results in the scripting
  153. language only executing the code within the <script> elements regardless
  154. of what the default scripting language is set to for a language by the webserver
  155. or by an ASP page command for the current document.</p>
  156. <ul>
  157.   <code><br>
  158.   <SCRIPT Language=PerlScript RUNAT=Server><br>
  159.   for($i=0; $i<=10; $i++) {<br>
  160.   #<br>
  161.   # Your Perl code here<br>
  162.   #<br>
  163.   }<br>
  164.   </SCRIPT></code>
  165. </ul>
  166.  
  167. <h2><a name="thescriptinghost">The Scripting Host</a></h2>
  168. <p>When Active Server Pages acts as the scripting host for PerlScript, it is
  169. initalized as a host first when an ASP file on the web-server is requested by
  170. the way of a URL (such as http://www.domain.com/home.asp). The web-server
  171. locates the file, and the scripting host locates the script commands that are
  172. within the script delimiters. The chunks of code found within the delimiters are
  173. passed on to PerlScript, which creates a Perl interpreter that treats the code.
  174. Afterwards, it returns to the scripting host, which waits for the next incoming
  175. call. Certain rules apply to when you write code to interact with scripting
  176. hosts such as ASP, and let's look at one of those necessary things to know by
  177. illustrating it as a parallel to writing a command-line Perl script. When you
  178. began programming Perl, among the first things you probably learned was how to
  179. print text to the screen, and it is not unusual that such a script looks as
  180. follows.</p>
  181. <ul>
  182.   <code>print "Hello World";</code>
  183. </ul>
  184.  
  185. <p>As seen, the <code>"print()"</code>-function of Perl outputs the
  186. string "Hello World" to what is known as the Standard Output.
  187. PerlScript, too, will send any output to what it knows as Standard Output, and
  188. when executed within the ASP scripting host, the PerlScript engine will use the
  189. features of the host's object-model in order to reach the standard output.
  190. Essentially, the host provides a set of features, and you pick the scripting
  191. language in which you wish to write your application to interact with the host.
  192. In ASP, you need to know the host because it decides what method and what object
  193. you need to deploy of the host's in order to output a string. A scripting
  194. language would become extremely bloated if it had to keep track of all those
  195. things. In contrast, the scripter needs to keep track of such features. :-) To
  196. send "Hello World" to the client's browser by using ASP, you call the
  197. "<code>Write()</code>"-method of the Response object as in the next
  198. example.</p>
  199. <ul>
  200.   <code>$Response->Write("Hello World");</code>
  201. </ul>
  202.  
  203. <p>In essence, it is of most importance that you know the object-model of the ASP
  204. scripting host within which you use PerlScript so that you know what object to
  205. call and how to get the best performance out of your application.</p>
  206.  
  207. <h2><a name="aquickexample">Creating An ASP Page</a></h2>
  208. <p>When looking back, the little we've seen about ASP so far is that it contains a
  209. set of objects that you can use for your programming. It also requires a
  210. scripting language that is used to access these objects, and for that purpose,
  211. PerlScript can be used to execute Perl commands that are mixed and embedded
  212. within the HTML of your Active Server Pages document. Lastly, the ASP document
  213. has its own file extension .asp which is recognized by the web server as a
  214. document parsed for first script commands and then HTML tags.</p>
  215. <ul>
  216.   1) Create a file named PerlScript.asp<br>
  217.   2) Edit it and enter "<code><HTML> Hello World </HTML></code>"<br>
  218.   3) Save the file where you can access it by a URL such as <i>http://localhost/</i>.
  219.   On IIS, the following path is often valid <i><device>:\inetpub\wwwroot\</i>
  220.   where <device> is a hard-disk such as C:\ or D:\<br>
  221.   4) Run the file in your browser by entering the URL pointing to PerlScript.asp;
  222.   for example, <i>http://localhost/PerlScript.asp</i>
  223. </ul>
  224.  
  225. <p>If it instead of finding the file reports an error such as "File Not
  226. Found," you need to open Windows Explorer and reassure yourself of that the
  227. file is saved with the .asp file-extension and in the correct physical location
  228. for being accessible by the browser. If the browser finds the file and
  229. "Hello World" is outputted, you can place a few script commands in the
  230. file and rest assured that ASP will execute everything as for which it was
  231. built. Edit the file so that is looks as follows.</p>
  232. <ul>
  233.   <code><%@Language=PerlScript%><br>
  234.   <HTML><br>
  235.   <TITLE> PerlScript Test </TITLE><br>
  236.   <%<br>
  237.   for($i=0; $i<=10; $i+=2) {</code>
  238.   <ul>
  239.     <code>$Response->Write("<FONT SIZE=$i COLOR=#000000>");<br>
  240.     $Response->Write("Hello World! </FONT> <BR>");</code>
  241.   </ul>
  242.   <code>}<br>
  243.   %><br>
  244.   </HTML><br>
  245.   </code>
  246. </ul>
  247.   
  248. <p>The script shown is used only to output HTML and text. Essentially, the Response
  249. object's "<code>Write()</code>"-method sends the HTML and variable
  250. value of <code>$i</code> to the browser. However, <code>$i</code> is a part of
  251. the HTML Font element, so the result is that the font size is increased by 2 for
  252. each time "Hello World" is sent to the client's browser. You could
  253. also write the script this way:</p>
  254. <ul>
  255.   <code><HTML><br>
  256.   <TITLE> PerlScript Example </TITLE><br>
  257.   <script language=perlscript runat=server><br>
  258.   for($i=0; $i<=10; $i+=2) {</code>
  259.   <ul>
  260.     <code>$Response->Write("<FONT SIZE=$i COLOR=#000000>");<br>
  261.     $Response->Write("Hello World! </FONT> <BR>");</code>
  262.   </ul>
  263.   <code>}<br>
  264.   </script><br>
  265.   </HTML><br>
  266.   </code>
  267. </ul>
  268.  
  269. <p>A closure to this example, there is a shorthand for writing <code>$Response->Write($variable)</code>,
  270. and it is not available when already within script delimiters; however, to
  271. easily mix variables with HTML you can automatically call the mentioned method
  272. by <code><%=$variable%></code> where the equal-sign automatically
  273. translates into <code>$Response->Write()</code>. For example:</p>
  274. <ul>
  275.   <code><HTML><br>
  276.   <TITLE> PerlScript Example </TITLE><br>
  277.   <% @Language=PerlScript %><br>
  278.   <% for($i=0; $i<=10; $i+=2) {<br>
  279.   %><br>
  280.   <FONT SIZE=<%=$i%> COLOR=#000000><br>
  281.   Hello World!<br>
  282.   </FONT><br>
  283.   <BR><br>
  284.   <% } >%<br>
  285.   </HTML><br>
  286.   </code>
  287. </ul>
  288.   
  289. <h2><a name="asp_api">The ASP Programming Interface</a></h2>
  290. <p>Providing an interface to common tasks for a web programmer, ASP simplifies
  291. web-programming by making the simple tasks even easier. The features of ASP are
  292. implemented and exposed as objects, and, in addition, a scripting language is
  293. enabled to not only use those features of the ASP host, the language can
  294. certainly use its own features, too.</p>
  295.   
  296. <h2><a name="theaspobjects">The ASP Intrinsic Objects</a></h2>
  297. <p>In object-oriented programming as we know it, the programmer is required to
  298. create an instance of the object she wishes to use. The ASP objects, on the
  299. other hand, are "intrinsic", which means that they are already
  300. instantiated and available to your scripting language engine. No pre-work at all
  301. is associated with these objects and you can access them at any time. Now, each
  302. object encapsulate a set of very specific services and provides shorthand access
  303. to common tasks for the web developer such as reading the data submitted from a
  304. web-form, reading and writing cookies, redirecting the client's browser, and
  305. also extended functionality such as the ability to identify each user as a
  306. unique client and associate private server-side variables with her. Before
  307. diving into the syntax, these are the objects as of ASP 3.0:</p>
  308.  
  309. <h3><a name="application">Application</a></h3>
  310. <p>The Application Object an object that is a place-holder for global variables
  311. stored on the server side. A global variable in this sense is a variable that is
  312. global to what is known as the IIS application. The IIS application defines the
  313. physical space of a webserver such as the range on the hard disk for the URL
  314. http://members.someperlsite.com/. A webserver can have more than one IIS
  315. application, but there is only one ASP application object per IIS application.
  316. Confused? Hang on a minute. The Application object, like the Session object, has
  317. what is called a collection. The collection contains variables created by you.
  318. Whenever you want to create a variable, the variable must be put on the contents
  319. collection, and the following is one way of doing it.
  320. <ul>
  321.   <code># Set an application variable<br>
  322.   #<br>
  323.   $Application->Contents->SetProperty('Item', 'myName', 'Tobias');</code>
  324. </ul>
  325.  
  326. <p>The contents collection can store scalar variables, arrays, or objects that
  327. somehow are associated with all users; for example, a visitor counter or a
  328. connection-string used to connect to a database through the Microsoft universal
  329. ADO application-programming interface. The variable can be accessed easily, too.
  330. <ul>
  331.   <code># Access an application variable<br>
  332.   #<br>
  333.   $Application->Contents->Item('myName');</code>
  334. </ul>
  335.  
  336. <p>However, when you're comfortable within the Microsoft Management Console and can
  337. set and define your own IIS applications, you will notice that there is only one
  338. ASP Application object per IIS Applcation and the variables placed in the
  339. Contents colleciton are only available within that IIS application and no other.
  340. If it's a bit confusing, it's guaranteed to have cleared out after playing
  341. around with this for a while. It's the most abstract part about ASP if you are
  342. not used to defining IIS applications. On the downside, Personal Web Server does
  343. not enable you to define more than one IIS application.</p>
  344.  
  345. <h3><a name="asperror">ASPError</a></h3>
  346. <p>The ASPError object is the only new object that shipped with ASP 3.0. It
  347. contains detailed information about an error which occured during the processing
  348. of an ASP page. Unless told otherwise by the administrator, ASP 3.0 redirects
  349. the client to a page named 500-100.asp when an error occurs, and in that page,
  350. the ASPError object is deployed to show detailed descriptions about the error.
  351. You can with PerlScript easily also extend the use the 500-100.asp page to
  352. perform custom tasks such as emailing you a formatted page of the contents of
  353. the ASPError object on an arror or writing it to a special log. Some of its
  354. useful properties include: SourceCode for returning the source code of the part
  355. of a script that generated the error, Category for tracking down the categoru of
  356. the error to ASP, scripting language, or an object, File for the name of the
  357. file processed when error was generated, and Description to return a description
  358. of the error; however, please note that ASPError objects are only returned by
  359. the Server object's GetLastError method.</p>
  360. <ul>
  361.   <code><br>
  362.   # Return the ASPError object<br>
  363.   #<br>
  364.   $ASPError = $Server->GetLastError();<br>
  365.   <br>
  366.   # Output the error's description<br>
  367.   #<br>
  368.   $Response->Write( $ASPError->{Description} );</code>
  369. </ul><br>
  370.  
  371. <h3><a name="objectcontext">ObjectContext</a></h3>
  372. <p>The ObjectContext object is used for a page that is run as a transaction. This
  373. object enables you to commit or abort a transaction, which is an important
  374. functionality for deployed business applications. Its only methods are SetAbort()
  375. and SetComplete(). They are used to commit or abort the transaction. Before this
  376. can be used, your page must include a <code>@TRANSACTION</code> page command in
  377. the page, whereas you are enabled only to define @ once per file; however, you
  378. can use multiple directives within the @ such as <code><%@directiveA=something
  379. directiveB=somethingelse%></code>. If you use PerlScript a lot, you are
  380. better off setting it as the default language in the Microsoft Management
  381. Console. Setting the default language in the MMC is unfortunately not an option
  382. for Personal Web Server. PWS is good for practicing a scripting language and
  383. ASP, but it is not good for tailormaking your webservice in terms of IIS
  384. applications and other tasks that are administrative. For example, it does not
  385. have the Microsoft Management Console. What PWS mainly does is to allow you to
  386. publish and develop Active Server Pages within reson while it hides the
  387. administrative tasks.</p>
  388.  
  389. <h3><a name="request">Request</a></h3>
  390. <p>For good reason, the Request object is a widely used object. It contains a
  391. collection of information such as form-data or cookies gathered from the client.
  392. With this object you can gather the contents submitted from any type of
  393. web-form, read server variables or the contents of a digital client certificate.
  394. You can also read binary data such as an uploaded file by first determining the
  395. number of bytes sent with the <code>TotalBytes</code>-property and then read it
  396. with the <code>BinaryRead($bytes_to_read)</code> method.</p>
  397. <ul>
  398.   <code><br>
  399.   # Get the number of total bytes in the request<br>
  400.   #<br>
  401.   $bytes_to_read = $Request->{TotalBytes};<br>
  402.   <br>
  403.   # Read and return a variant array of type VT_U1<br>
  404.   #<br>
  405.   $read_bytes=$Request->BinaryRead( $bytes_to_read );</code>
  406. </ul>
  407.  
  408. <p>In the Request object, collections that you can read includes <code>ClientCertificate</code>
  409. for digital certificated, <code>Cookies</code> for cookies sent with the HTTP
  410. request, <code>Form</code> for data posted by a web form using the POST method, <code>QueryString</code>
  411. for data passed with the QueryString or GET method from a web form, and <code>ServerVariables</code>
  412. for HTTP environment variables such as the server software or the users browser.</p>
  413. <ul>
  414.   <code># Let's see what's in the ALL_HTTP variable<br>
  415.   #<br>
  416.   $Response->Write( $Request->ServerVariables('ALL_HTTP')->Item() );</code>
  417. </ul><br>
  418.  
  419. <h3><a name="response">Response</a></h3>
  420. <p>The Response Object is responsible for sending data from the client to the
  421. server. For example, you can print strings such as HTML or scalar variables, and
  422. you can also print binary data such as images, set cookies, control cache,
  423. character sets, and content-types, plus send the client status headers, append
  424. data to the log, set PICS labels, and see if the client is still connected. A
  425. cookie can contain the attributed Domain, Expires, HasKeys, Path, and Secure,
  426. and you first declare a cookie before setting these attributes.</p>
  427. <ul>
  428.   <code># Ask the client's browser if it wants a cookie</code><br>
  429.   #<br>
  430.   $Response->Cookies->SetProperty(
  431.   <ul>
  432.     <ul>
  433.       <ul>
  434.         <ul>
  435.           <ul>
  436.             <ul>
  437.               <code>'Item',<br>
  438.               'someCookie',<br>
  439.               'Hi! This is a cookie!'<br>
  440.               );
  441.             </ul>
  442.           </ul>
  443.         </ul>
  444.       </ul>
  445.     </ul>
  446.   </ul>
  447.   <br>
  448.   <br>
  449.   # ==================================================<br>
  450.   # Let's set some attributes of the cookie!<br>
  451.   # ==================================================<br>
  452.   <br>
  453.   # This is the domain that can read the cookie; to specify it further,<br>
  454.   # use the Path-attribute to define a more complete URL<br>
  455.   #<br>
  456.   $Response->Cookies('someCookie')->{Domain} = 'somesite.com';<br>
  457.   <br>
  458.   # The expiration date for the cookie<br>
  459.   #<br>
  460.   $Response->Cookies('someCookie')->{Expires} = 'January 1, 1999';<br>
  461.   <br>
  462.   # Not a secure cookie; 1 defines it as secure<br>
  463.   #<br>
  464.   $Response->Cookies('someCookie')->{Secure} = 0;</code>
  465. </ul>
  466. <br>
  467.  
  468. <h3><a name="server">Server</a></h3>
  469. <p>The Server object provides certain server-side functions. Its only property is <code>Timeout</code>
  470. which defines for how many seconds a script should try executing before
  471. returning an error. This setting can also be set in the Microsoft Management
  472. Console. In terms of methods, you can create instances of COM objects in your
  473. page, encoding HTML and URL's, mapping the physical path to a file by providing
  474. its URL, execute other .asp files, and seamlessly transfer the client to a new
  475. page while maintaining the state of the current ASP objects, which means that
  476. any form data that was gathered can be transferred between pages.</p>
  477. <ul>
  478.   <code># Open the file in the virtual path /scripts/forum.asp/<br>
  479.   #<br>
  480.   open( FILE, $Server->MapPath('/scripts/forum.asp') );</code>
  481. </ul>
  482.  
  483. <p>You can use <code>CreateObject('ProgID')</code> to return a valid COM object to
  484. the Active Server Page. For example, to instantiate an ADO object, you'd do the
  485. following:</p>
  486. <ul>
  487.   <code># Create an ADO Connection object<br>
  488.   #<br>
  489.   $ADOConnObj = $Server->CreateObject('ADODB.Connection');</code>
  490. </ul>
  491.  
  492. <p>When using strings, <code>HTMLEncode($string)</code> encodes charaters such as
  493. greater than and less than into its valid character represenation within an HTML
  494. page. This prevents, for example, users to post HTML to a chatroom or
  495. messageboard. The <code>URLEncode($string)</code>-method encodes a string for
  496. valid represenation as a URL. New in IIS 5, you can <code>Execute('/scripts/page.asp')</code>
  497. ASP scripts in other files, and to transfer the user without losing the state of
  498. the Request object's existing variables such as the contents of the
  499. Form-collection you can use the Transfer-method.</p>
  500. <ul>
  501.   <code># Transfer the user to a different page<br>
  502.   #<br>
  503.   $Server->Transfer('/step2.asp');</code>
  504. </ul>
  505. <p>Worth noting about the transfer method is that it takes place on the server
  506. side. There is never a request sent to the users browser telling the browser to
  507. redirect, thus a roundtrip is spared.</p>
  508.  
  509. <h3><a name="session">Session</a></h3>
  510. <p>The Session object enables you to associate variables with each unique client
  511. and keep the variables stored until she leaves the domain. It has the same
  512. abilities as the Application object, but with the important difference that
  513. these variables will only be available to the single user and the script engine, making it
  514. ideal for applications such as shopping carts. The syntax is the same as the
  515. Application object in terms of adding entities to the Contents collection. In
  516. addition, you can set the <code>Timeout</code>-property to the number of minutes
  517. that you wish the Session to last before it is ended or you can deliberately end
  518. the Session by calling the <code>Abandon</code>-method and then redirect to a
  519. new page. The redirection is very important! Other properties that you can use
  520. is <code>CodePage</code> which is used for Symbol Mapping, <code>LCID</code> for
  521. the locale identifier, and <code>SessionID</code> which uniquely identifies the
  522. client.</p>
  523.  
  524. <p>For both the Session and Application object, the Contents collections contain a <code>Remove()</code>
  525. and <code>RemoveAll()</code> method. <code>Remove()</code> takes either an index
  526. or a keyname for the variable in the Collection to remove, and <code>RemoveAll()</code>
  527. removes all variables stored in the collection. In example, consider that you
  528. have stores a property called "myName" in the Session s Contents
  529. collection, you would remove it as follows:</p>
  530. <ul>
  531.   <code>$Session->Contents->Remove('myName');</code>
  532. </ul>
  533.  
  534. <p>Earlier than IIS 5, <code>Remove()</code> and <code>RemoveAll()</code> are not
  535. available, so you will have to use the Perl built-in function <code>undef()</code>,.
  536.  
  537. <h2><a name="aspsamples">The Active Server Pages Samples</a></h2>
  538. <p>The following examples are taken from the \eg\aspsamples\ directory, which will
  539. be installed on your machine if you installed the example files with ActivePerl.
  540. In addition to these examples, there are useful and advanced examples in the \eg\aspsamples\
  541. directory.</p>
  542.  
  543.  
  544. <h2><a name="hw">Say "Hello World!"</a></h2>
  545. <h3>File Location: [\eg\aspsamples\hello.asp]</h3>
  546. <p>In this example, a for-loop is used to print a series of "Hello
  547. World!" strings of increasing font-size. Notice the <code><%=$i%></code>
  548. call, which is shorthand for writing $Response->write($i).</p>
  549. <ul>
  550.   <code><br>
  551.   <%<br>
  552.   for ($i = 3; $i < 8; $i++) {<br>
  553.   %><br>
  554.   <font size=<%= $i %>><br>
  555.   "Hello World!"<br>
  556.   </font><br>
  557.   <BR><br>
  558.   <%<br>
  559.   }<br>
  560.   %>
  561.   </ul>
  562. </code>
  563. <br>
  564.  
  565. <h2><a name="sv">Accessing HTTP Server Variables</a></h2>
  566. <h3>File Location: [\eg\aspsamples\srvvar.asp]</h3>
  567. <p>The HyperText Transfer Protocol (HTTP) variables that are sent with each request
  568. can be retrieved from the Request object. You need to specify that you want the
  569. server variables, and then call a method named "Item" in order to
  570. return the value.
  571. <ul>
  572.   <code><%= $Request->ServerVariables('SERVER_SOFTWARE')->Item() %></code>
  573. </ul>
  574.  
  575.  
  576. <h2><a name="qs">Reading the QueryString</a></h2>
  577. <h3>File Location: [\eg\aspsamples\qstring.asp]</h3>
  578. <p>The QueryString can be either manufactured by handcoding it, or it is
  579. automatically generated for form-fields if you use a HTML form that uses the GET
  580. method for submitting its data. The following is one way you can use it.</p>
  581. <ul>
  582.   <code>
  583.   <a class="doc" href="<%=$Request->ServerVariables('PATH_INFO')->item()%>?Size=Medium&Color=Yellow"><br>
  584.   This link will demonstrate the Request object's QueryString collection.<br>
  585.   </A><br>
  586.   <br>
  587.   The current value of Size is<br>
  588.   <%= $Request->QueryString('Size')->item() %><br>
  589.   <br>
  590.   <BR><br>
  591.   <br>
  592.   The current value of Color is<br>
  593.   <%= $Request->QueryString('Color')->item() %>
  594.   </ul>
  595. </code>
  596.  
  597. <h2><a name="wf">Interactive Web Forms</a></h2>
  598. <h3>File Location: [\eg\aspsamples\wform.asp]</h3>
  599. <p>In this example, the POST method is used to submit a form. The Request object
  600. gathers data by calling the Form-element by its name in <code>$Request->Form('name')->Item()</code>
  601. instead of in <code>$Request->QueryString('name')->Item()</code> as it is
  602. passed when the method is GET.</p>
  603.  
  604. <p>Once fetched, the "<code>$Server->HTMLEncode()</code>"-method is
  605. called to correctly translate HTML tags into proper encoding so that no HTML
  606. tags can be submitted.</p>
  607. <ul>
  608.   <code>
  609.   <%<br>
  610.   my($name) = $Request->Form('Yourname')->Item();<br>
  611.   $name = $Server->HTMLEncode($name);<br>
  612.   %><br>
  613.   <br>
  614.   <%<br>
  615.   if($name eq 'Enter Your name here') {<br>
  616.   $Response->Write("Please type your name in the box below and then
  617.   press the button");<br>
  618.   }<br>
  619.   else {<br>
  620.   $Response->Write("Hello $name");<br>
  621.   }<br>
  622.   %><br>
  623.   <br>
  624.   <CENTER><br>
  625.   <FORM ACTION="wform.asp" METHOD="POST"><br>
  626.   <INPUT TYPE="Textfield" NAME="Yourname" MAXLENGTH="30"
  627.   VALUE="Enter Your Name Here"><br>
  628.   <INPUT TYPE="SUBMIT" VALUE="Click Me"><br>
  629.   </FORM><br>
  630.   </CENTER></code>
  631. </ul>
  632.  
  633. <h2><a name="dc">Database Connections (ADO and ASP)</a></h2>
  634. <h3>File Location: [\eg\aspsamples\ado1.asp]</h3>
  635. <p>This database example requires the ActiveX Data Objects from the Microsoft Data
  636. Access Components, available at <a class="doc" href="http://www.microsoft.com/data/">http://www.microsoft.com/data/</a>.<br>
  637. <br>
  638. <ul>
  639.   <code>
  640.   <%<br>
  641.   # Create an instance of the ADO Connection object<br>
  642.   #<br>
  643.   $Conn = $Server->CreateObject("ADODB.Connection");<br>
  644.   <br>
  645.   # Open a system DSN<br>
  646.   #<br>
  647.   $Conn->Open( "ADOSamples" );<br>
  648.   <br>
  649.   # Execute an SQL Query<br>
  650.   #<br>
  651.   $RS = $Conn->Execute( "SELECT * FROM Orders" );<br>
  652.   <br>
  653.   # Read a property to get the number of columns<br>
  654.   # present in the Recordset returned from the<br>
  655.   # query.<br>
  656.   #<br>
  657.   $count = $RS->Fields->{Count};<br>
  658.   <br>
  659.   # Print out the names of each column<br>
  660.   #<br>
  661.   for ( $i = 0; $i < $count; $i++ ) {<br>
  662.   $Response->Write( $RS->Fields($i)->Name );<br>
  663.   $Response->Write("<BR>");<br>
  664.   };<br>
  665.   <br>
  666.   # Loop the Recordset until there are no more records<br>
  667.   #<br>
  668.   while ( ! $RS->{EOF} ) {<br>
  669.   for ( $i = 0; $i < $count; $i++ ) {<br>
  670.   $Response->Write(" ");<br>
  671.   $Response->Write($RS->Fields($i)->{Value});<br>
  672.   $Response->Write("<BR>");<br>
  673.   };<br>
  674.   <br>
  675.   # Move to the next record<br>
  676.   #<br>
  677.   $RS->MoveNext();<br>
  678.   };<br>
  679.   <br>
  680.   # Close the Recordset<br>
  681.   #<br>
  682.   $RS->Close();<br>
  683.   $Conn->Close();<br>
  684.   %></code>
  685. </ul>
  686.  
  687. <p>As an important note, the ActiveX Data Objects is an easy-to-use and
  688. easy-to-learn set of objects that provides universal data access. Regardless of
  689. what language you use ADO from within, the application-level programming
  690. interface of ADO remains the same.</p>
  691.  
  692. <p>Moreover, not only can you access relational databases such as MS Access, SQL
  693. Server, or Oracle with these components, you can access non-relational data such
  694. as video, filesystems, and email systems -- all from one single interface. It is
  695. the post-ODBC industry standard for accessing data stores, and a fast and
  696. powerful way to get your databases out on the Internet.</p>
  697.  
  698. <h2><a name="bindata">Variants and Binary Data</a></h2>
  699. <p>At times, you will be working with binary data that is passed to PerlScript
  700. from a COM object or passed from PerlScript to a COM object. In Windows Script,
  701. the data comes in a data type called a Variant. The Variant resembles Perl's
  702. scalar variables because it was designed for holding most types of data. And
  703. most of the time, Perl is able to determine what type of Variant that is being
  704. returned to it from a COM object; however, with binary data, it sometimes
  705. becomes necessary to define what the variant is exactly for a type, so the
  706. "<code>Win32::OLE::Variant</code>"-module provides functionality for
  707. this conversion and much more. For example, if you have a GIF image stored in
  708. the variable <code>$image</code>, and you want to output it to the screen by
  709. using the Response object's "<code>BinaryWrite()</code>"-method, you
  710. must convert it to a VT_UI1 variant before it is passed to the "<code>BinaryWrite()</code>"-method
  711. simply because a VT_UI1 variant is expected by the method.<br>
  712. <ul>
  713.   <code>use Win32::OLE::Variant;<br>
  714.   <br>
  715.   # Tell the browser a GIF image is on its way<br>
  716.   #<br>
  717.   $Response->{ContentType} = "image/GIF";<br>
  718.   <br>
  719.   # Send the GIF as a VT_UI1 Variant<br>
  720.   #<br>
  721.   $Response->BinaryWrite(Win32::OLE->Variant(VT_UI1, $image));<br>
  722.   </code>
  723. </ul>
  724. <p>An issue of needing to convert to the accurate type of Variant occurs most of
  725. the time when working with binary data; two concrete examples are binary large
  726. objects (BLOBs) returned from SQL Server and binary data being output through
  727. the ASP Response object's "<code>BinaryWrite()</code>"-method. The
  728. "<code>BinaryWrite()</code>"-method expects a Variant of the type
  729. VT_UI1, and that is the same type which is returned when reading a BLOB from SQL
  730. Server. However, as the variant is returned to PerlScript, it converts it into
  731. the type of scalar that most resembles the variant, and although that is an
  732. accurate conversion for use in Perl, you will need to convert data if it's used
  733. in a VT_UI1 context.</p>
  734.  
  735. <h2><a name="readblob">To Read And Display Binary Large Objects (ADO and ASP)</a></h2>
  736. <p>The following example will demonstrate how ADO can be used to read a Binary
  737. Large Object from SQL Server, and how ASP is used to output the BLOB as an
  738. image.
  739. <ul>
  740.   <code><%@Language=PerlScript%> <%<br>
  741.   use Win32::OLE::Variant;<br>
  742.   <br>
  743.   # One note, 40 as bytes to read per GetChunk()-call is not<br>
  744.   # a good number to choose for a real application. I emphasize<br>
  745.   # _not_. Instead, whatever you choose depends much on your<br>
  746.   # system and the power of it; however, 4000 is a much more<br>
  747.   # realistic real-world number compared to 32.<br>
  748.   #<br>
  749.   my($blob_size, $read_size, $bytes_to_read) = (0, 0, 32);<br>
  750.   <br>
  751.   # Let's create the Connection object used to establish the connection<br>
  752.   #<br>
  753.   $conn = $Server->CreateObject('ADODB.Connection');<br>
  754.   <br>
  755.   # Open a connection using the SQL Server OLE DB Provider<br>
  756.   #<br>
  757.   $conn->Open(<<EOF);<br>
  758.   Provider=SQLOLEDB;<br>
  759.   Persist Security Info=False;<br>
  760.   User ID=sa;Initial Catalog=pubs<br>
  761.   EOF<br>
  762.   <br>
  763.   # Execute the query which returns the BLOB from our database<br>
  764.   #<br>
  765.   $rs = $conn->Execute("SELECT logo FROM pub_info WHERE pub_id='0736'");<br>
  766.   <br>
  767.   # Get the size of the BLOB<br>
  768.   #<br>
  769.   $blob_size = $rs->FieldS('logo')->{ActualSize};<br>
  770.   <br>
  771.   # And here's the routine for reading in the blob. Alternatively you can<br>
  772.   # make a control statement that says if the $blob_size is less than<br>
  773.   # 4096, it should just swallow it in one chunk, but the routine below<br>
  774.   # is good to have handy<br>
  775.   #<br>
  776.   while($read_size < $blob_size) {</code>
  777.   <ul>
  778.    <code> $buffer .= $rs->Fields('logo')->GetChunk($bytes_to_read);<br>
  779.     $read_size += $bytes_to_read;<br>
  780.     if($read_size+$bytes_to_read > $ blob_size) {
  781.     <ul>
  782.       $bytes_to_read = $blob_size - $read_size;
  783.     </ul>
  784.     }
  785.   </ul>
  786.   }<br>
  787.   <br>
  788.   # Make a VT_UI1 variant of the retrieved Chunks<br>
  789.   #<br>
  790.   $image = new Win32::OLE::Variant(VT_UI1, $buffer);<br>
  791.   <br>
  792.   # Tell the browser that the content coming is an image of the type GIF<br>
  793.   #<br>
  794.   $Response->{ContentType}="image/gif";<br>
  795.   <br>
  796.   # Do a binarywrite of the VT_UI1 variant image<br>
  797.   #<br>
  798.   $Response->BinaryWrite($image);<br>
  799.   %></code>
  800. </ul>
  801.  
  802.  
  803. <h2><a name="appa">Appendix A</a></h2>
  804.  
  805. <h3><a name="appasysdsn">How To Set Up A System DSN</a></h3>
  806. <p>The System Data Source Name is information stored in the Windows-registry.
  807. The information is used by your application to connect to a database. To create
  808. a SystemDSN you must have a database ready to be used by your application and
  809. know the path to the database. When the information above is gathered you open
  810. "32 Bit ODBC" from the control-panel andclick on the "SystemDSN"-tab.
  811. Choose to "Add" a new SystemDSN and select the driver for your
  812. database. Enter the "Data Source Name" that you will call on the
  813. database by from your application, then click on the "Select"-button
  814. and browse to your database-file. Okay everything, then close the program. You'll
  815. now be able to call on your database by the Data Source Name you entered for it
  816. as follows:
  817. <ul>
  818.   <code>$Conn = $Server->CreateObject("ADODB.Connection");<br>
  819.   $Conn->Open("Name");</code>
  820. </ul>
  821.  
  822. <h3><a name="appanosysdsn">Why Not To Use A System DSN</a></h3>
  823. <p>With the ActiveX Data Objects (ADO), the layer that connectes to a database
  824. is called the OLE DB layer. It is the very closest to the physical database, and
  825. directly connecting to OLE DB is ADO. Most databases will have what is called an
  826. OLE DB Provider, and if you have worked with ODBC, the OLE DB provider is OLE
  827. DB's equivalent of the ODBC driver. In ADO, ideally you should connect via ADO
  828. directly to OLE DB and from OLE DB directly to the physical database or other
  829. data store. A System DSN is for ODBC data sources and it causes OLE DB to wrap
  830. an ODBC driver within itself, which adds an overhead and reduces performance.
  831.  
  832. <h3><a name="appaoledb">How To Use The Native OLE DB Provider</a></h3>
  833. <p>There are a number of things you can do to get the native provider set up.
  834. When you have it set up, you simply replace the name of the system DSN with the
  835. string that has been produced in order to connect to the data store using the
  836. native OLE DB provider. First, try to create an Universal Data Link file by
  837. doing the following:
  838. <ol>
  839.   <li><p>Create a file named connectionstring.udl.</p></li>
  840.   <li><p>Right-click on it.</p></li>
  841.   <li><p>Choose Properties.</p></li>
  842.   <li><p>Choose the OLE DB Provider to use.</p></li>
  843.   <li><p>Define what source to connect to and possibly a username and password.</p></li>
  844.   <li><p>Click "Test Connection".</p></li>
  845.   <li><p>Open the file in "Notepad".</p></li>
  846.   <li><p>Highlight the connectionstring and press CTRL+C to copy it into memory.</p></li>
  847.   <li><p>Paste it into your ADO application by pressing CTRL+V.</p></li>
  848. </ol>
  849. <p>If you are not lucky enough to have .udl, locate a friend who has it or dig
  850. around for the connectionstrings. It is more than feasible that there are texts
  851. on it available on the Internet, too. To give an example, this is what a typical
  852. connectionstring looks like for an Access database:
  853. <ul>
  854.   <code>Provider=Microsoft.Jet.OLEDB.4.0;<br>
  855.   User ID=Somebody;<br>
  856.   Data Source=c:\\access.mdb;<br>
  857.   Persist Security Info=False</code>
  858. </ul>
  859. <p>And here's one for SQL Server:
  860. <ul>
  861.   <code>Provider=SQLOLEDB;<br>
  862.   Persist Security Info=False;<br>
  863.   User ID=sa;<br>
  864.   Initial Catalog=Northwind</code>
  865. </ul>
  866.  
  867. <h2><a name="appb">Appendix B</a></h2>
  868.  
  869. <h3><a name="appbbook">Books Resources</a></h3>
  870. <ul>
  871.   <code>ActivePerl with ASP and ADO:<br>
  872.   by Tobias Martinsson<br>
  873.   ISBN 0471383147<br>
  874.   URL: <a class="doc" href="http://www.wiley.com/compbooks/">http://www.wiley.com/compbooks/</a></code>
  875. </ul>
  876.  
  877. <h3><a name="appbonline">Online Resources</a></h3>
  878. <ul>
  879.   <li><a class="doc" href="http://www.microsoft.com/data/">Microsoft Data Access
  880.   Components</a>; MDAC includes ADO, OLE DB, and every component needed for
  881.   getting your databases out on the Internet.
  882. <li>Windows 95 users will have to download the NT Option Pack from <a class="doc" href="http://www.microsoft.com/">Microsoft</a>
  883.   and install Personal Web Server which ships with it. Win 98 already has it on
  884.   its CD.
  885. <li>The <a class="doc" href="http://www.asplists.com/asplists/aspperlscript.asp">ASP
  886.   PerlScript</a> mailing list is pretty much where the most questions and answers
  887.   on PerlScript and ASP circulate.
  888. <li><a class="doc" href="http://www.deja.com/~perlscript/">PerlScript Community</a> is a
  889.   Deja community for users who want to find users that PerlScript.
  890. <li><a class="doc" href="http://www.fastnetltd.ndirect.co.uk/Perl/perl-win32-asp.html">The
  891.   Perl-Win32-ASP FAQ.</a> Maintained by Matthew Sergeant.</li>
  892. </ul>
  893.  
  894. <h2><a name="author and copyright">AUTHOR AND COPYRIGHT</a></h2>
  895. <p>Copyright (c) 2000 Tobias Martinsson. All Rights Reserved.</p>
  896. <p>When included as part of the Standard Version of Perl, or as part of its
  897. complete documentation whether printed or otherwise, this work may be
  898. distributed only under the terms of Perl's Artistic License. Any distribution of
  899. this file or derivatives thereof <em>outside</em> of that package require that
  900. special arrangements be made with copyright holder.</p>
  901. <p>Irrespective of its distribution, all code examples in this file are hereby
  902. placed into the public domain. You are permitted and encouraged to use this code
  903. in your own programs for fun or for profit as you see fit. A simple comment in
  904. the code giving credit would be courteous but is not required.</p>
  905. <p>Active Server Pages is copyright (c) Microsoft Corporation. All rights
  906. reserved.</p>
  907. <table border="0" cellpadding="0" cellspacing="0" width="100%">
  908.   <tr>
  909.     <td class="block" valign="MIDDLE" width="100%" bgcolor="#cccccc"><strong>
  910.       <p class="block"> Active Server Pages</p>
  911.       </strong></td>
  912.   </tr>
  913. </table>
  914.  
  915. </body>
  916.  
  917. </html>
  918.