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