<html>
<head>
<title>Preprocessing Directives</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div id="Description">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">Preprocessing Directives</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description">





<p><!--<primary>preprocessing
directives</primary>-->Active Server Pages provides
<firstterm>preprocessing directives</firstterm> similar to the
compiler directives in C and similar languages. Like these
precompilation directives, ASP directives instruct the web server to
perform a function before the script is completed and sent to the
client. The web server performs the other directives before
interpreting the script itself. ASP directives, with the exception of
<span class="LITERAL">&lt;%=</span> <var class="replaceable">expression</var>
<span class="LITERAL">%&gt;</span>, must appear on the first line of a script
and cannot be included using a Server-Side Included file. The format
for these directives (with the aforementioned exception of the
<span class="LITERAL">&lt;%=</span> <var class="replaceable">expression</var>
<span class="LITERAL">%&gt;</span> directive) is the following:</p>




<span class="PROGRAMLISTING"><pre><!--<primary sortas="öleft@percent@at">directive syntax</primary>-->&lt;%@ DIRECTIVE=<var class="replaceable">Value</var>%&gt;</pre></span>




<p>where <span class="LITERAL">DIRECTIVE</span> is one of the ASP directives
listed in this section and <var class="replaceable">Value</var> is a
valid value for the directive. Note that you must include a space
between the <span class="LITERAL">@</span> character and the directive. Also
note that the preprocessing directive must be placed within
<span class="LITERAL">&lt;%...%&gt;</span> delimiters.</p>




<p>The valid ASP preprocessing directives are listed as follows and are
explained in depth later in this chapter:</p>




<ul>

<li>CODEPAGE</li>

<li>ENABLESESSIONSTATE</li>

<li>LANGUAGE</li>

<li>LCID</li>

<li>TRANSACTION</li>

</ul>
</td></tr>
</table>
</div>
<div id="PreprocessingDirectivesCommentsTroubleshooting">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Preprocessing Directives: Comments/Troubleshooting</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">




<p><!--<primary>comments and
troubleshooting</primary><secondary>preprocessor
directives</secondary>-->The space between the
<span class="LITERAL">@</span> character and the directive and the requirement
that directives be placed on the first line of a script are
syntactically the most important features of an ASP directive. The
failure to include the space or to include directives on the first
line of a script are the most common errors when using directives.</p>




<p>You may ask yourself how you can have more than one directive in a
script if directives, with the exception of <span class="LITERAL">&lt;%=</span>
<var class="replaceable">expression</var> <span class="LITERAL">%&gt;</span>, must
be placed on the first line of a script. To include more than one
directive, use the following syntax:</p>




<span class="PROGRAMLISTING"><pre>&lt;%@ DIRECTIVE1=<var class="replaceable">Value</var>DIRECTIVE2=<var class="replaceable">Value</var> %&gt;</pre></span>




<p>You must include at least one space between each directive. Also, you
must <em>not</em> place spaces around the equal signs
(=).</p>
</td>
</tr>
</table>
</div>
<div id="CODEPAGE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
CODEPAGE</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2"><span class="LITERAL">&lt;%@CODEPAGE=</span><var class="replaceable">uintCodePage</var><span class="LITERAL">%&gt;</span>
</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">
<p><!--<primary>CODEPAGE directive</primary>-->
<!--<primary>character
sets</primary><secondary>setting</secondary>-->Sets the
character set (or code page) to be used to interpret the script on
the server. Different languages and locales use unique code pages.
This directive provides similar functionality for the interpretation
of scripts on the server as the <!--<primary>CodePage property
(Session)</primary>-->CodePage property of the Session
object provides for client-side interpretation of the HTML sent to
the client. However, it is important to note that the
<span class="LITERAL">CODEPAGE</span> preprocessing directive dictates how the
script itself is interpreted, whereas the CodePage property of the
Session object dictates how the resulting HTML is processed.</p>




</td>
</tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td></tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Parameters</td>
</tr>
<tr>
<td colspan="2" class="description">




<dl>
<dt><var class="replaceable">uintCodePage</var></dt>
<dd><p>An unsigned integer value corresponding to a valid code page for the
web server running the ASP script</p></dd>

</dl>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">




<span class="PROGRAMLISTING"><pre>&lt;%@ CODEPAGE=932%&gt;

' This code sets the code page to OEM 932, which is
' used for Japanese Kanji.</pre></span>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Notes</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>You can have both the <span class="LITERAL">CODEPAGE</span> directive and the
CodePage property for the Session object in the same script. This
results in the server-side script being interpreted using the
unsigned integer set for the <span class="LITERAL">CODEPAGE</span> directive
and the client information being interpreted using the code page set
of the CodePage property of the Session object.</p>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="ENABLESESSIONSTATE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
ENABLESESSIONSTATE</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2"><span class="LITERAL">&lt;%@ ENABLESESSIONSTATE=True|False%&gt;</span>
</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">
<p><!--<primary>ENABLESESSIONSTATE
directive</primary>--> <!--<primary>users,
information on</primary><secondary>enabling storage
of</secondary>--> <!--<primary>storing user
information</primary>--> <!--<primary>user
sessions</primary><secondary>enabling user information
storage</secondary>-->Turns the storage of user-specific
session information on (<span class="LITERAL">True</span>) or off
(<span class="LITERAL">False</span>). This value is <span class="LITERAL">True</span> by
default.</p>




</td>
</tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td></tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Parameters</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>None</p>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">




<span class="PROGRAMLISTING"><pre>&lt;%@ ENABLESESSIONSTATE=False%&gt;

' This code prevents the web server from storing
' user session information.</pre></span>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Notes</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>You also can enable session-state storage using the registry, but
this directive allows significantly more flexibility (and on a
script-by-script basis). If you have used a registry setting to
control session-state information, then using this directive
overrides that setting.</p>




<p>Setting this directive to <span class="LITERAL">False</span> prevents you from
storing any information in session-scoped variables or objects. This
forces you to rely on other methods of maintaining information about
each user, if you need to. However, it does provide some benefits:</p>




<ul><dd><p>	It does not rely on your clients' browsers using cookies.</p></dd><dd><p>It increases the speed with which your server scripting is processed
by the web server.</p></dd></ul>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="LANGUAGE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
LANGUAGE</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2"><span class="LITERAL">&lt;%@ LANGUAGE=</span><var class="replaceable">ScriptingEngine</var><span class="LITERAL">%&gt;</span>
</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">
<p><!--<primary>LANGUAGE directive</primary>-->
<!--<primary>scripting languages</primary><secondary>setting
default for processing</secondary>-->Sets the default
scripting engine the web server will use to process the script in
your ASP. This is set to VBScript by default.</p>




</td>
</tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td></tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Parameters</td>
</tr>
<tr>
<td colspan="2" class="description">




<dl>
<dt><var class="replaceable">ScriptingEngine</var></dt>
<dd><p>A valid scripting engine recognized by Internet Information Server.
The valid scripting engines include VBScript, JScript, PerlScript,
Python, and REXX.</p></dd>

</dl>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">




<span class="PROGRAMLISTING"><pre>&lt;%@ LANGUAGE="JScript"%&gt;

' This code sets the language for the current page to
' JScript, Microsoft's interpretation of the JavaScript
' scripting language. All script on this page will be 
' interpreted using the JScript DLL.</pre></span>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Notes</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>Setting the <span class="LITERAL">LANGUAGE</span> directive does not prevent
you from using other scripting engines on your script page. It only
sets the default scripting engine for interpretation of script on the
current page. The following example shows how you can set the default
scripting engine for the page to JScript and still use VBScript for a
specific procedure:</p>




<span class="PROGRAMLISTING"><pre>&lt;%@ LANGUAGE="JScript"%&gt;
&lt;SCRIPT LANGUAGE="VBScript" RUNAT="Server"&gt;
Sub ShowReport( )
	' This script will be interpreted using the VBScript 
	' scripting engine. 
End Sub
&lt;/SCRIPT&gt;</pre></span>




<p>Furthermore, setting the <span class="LITERAL">LANGUAGE</span> directive value
has no effect on the scripting engine used on the client side. Even
if you set the <span class="LITERAL">LANGUAGE</span> of the server-side script
to PerlScript, for example, you can still set the <span class="LITERAL">LANGUAGE</span>
attribute of the client-side <span class="LITERAL">&lt;SCRIPT&gt;</span> tag to
JScript, as in the following example:</p>




<span class="PROGRAMLISTING"><pre>&lt;%@ LANGUAGE="PerlScript"%&gt;

&lt;%
' All server-side script is interpreted using the PerlScript
' scripting engine.
%&gt;

HTML here...
&lt;SCRIPT LANGUAGE="JScript"&gt;
function btnReport_onClick
    ' This script will be interpreted using the JScript 
    ' scripting engine.
End Sub
&lt;/SCRIPT&gt;</pre></span>


<p>Note that only the VBScript and
JScript scripting engines are included with IIS. All other scripting
engines must be obtained and installed separately.</p>
</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="LCID">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
LCID</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2"><span class="LITERAL">&lt;%@ LCID=</span><var class="replaceable">dwordLCID</var><span class="LITERAL">%&gt;</span>
</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">
<p><!--<primary>LCID directive</primary>-->
<!--<primary>locale</primary><secondary>setting identifier
for</secondary>-->Sets a valid locale identifier for a given
script. This directive specifies various formats (such as dates and
times) to use for data on the server side.</p>




</td>
</tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td></tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Parameters</td>
</tr>
<tr>
<td colspan="2" class="description">




<dl>
<dt><var class="replaceable">dwordLCID</var></dt>
<dd><p>A DWORD (32-bit unsigned) value that represents a valid locale ID.</p></dd>

</dl>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">




<span class="PROGRAMLISTING"><pre>&lt;%@ LCID=1036%&gt;

' This code sets the locale ID for the server-side
' script to that for French.</pre></span>





</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Notes</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>Just as setting the <span class="LITERAL">CODEPAGE</span> directive has no
effect on the CodePage property of the Session object and what
character set is used on the client side, setting the
<span class="LITERAL">LCID</span> directive has no effect on the
<!--<primary>LCID property (Session)</primary>-->LCID
used on the client side. However, it is important to note that the
LCID preprocessing directive dictates how the script itself is
interpreted, whereas the LCID property of the Session object dictates
how the resulting HTML is processed.</p>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="TRANSACTION">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
TRANSACTION</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2"><span class="LITERAL">&lt;%@</span> <span class="LITERAL">TRANSACTION=</span><var class="replaceable">strValue</var><span class="LITERAL">%&gt;</span>
</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">
<p><!--<primary>TRANSACTION directive</primary>-->
<!--<primary>transactional
scripts</primary>-->Instructs the web server to treat the
entire script as a single transaction. If you set the script as
requiring a transaction, the web server uses Microsoft Transaction
Server to ensure that the entire script is processed as a single unit
(or transaction) or not at all. Currently, only database manipulation
is available in transactions.</p>




</td>
</tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td></tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Parameters</td>
</tr>
<tr>
<td colspan="2" class="description">




<dl>
<dt><var class="replaceable">strValue</var></dt>
<dd><p>The possible values for the <var class="replaceable">strValue</var>
parameter are as follows:</p></dd>




<dt><span class="LITERAL">Required</span></dt>
<dd><p>Instructs the web server that the current script requires a
transaction</p></dd>




<dt><span class="LITERAL">Requires_New</span></dt>
<dd><p>Instructs the web server that the current script requires a new
transaction</p></dd>




<dt><span class="LITERAL">Supported</span></dt>
<dd><p>Instructs the web server <em>not</em> to start a
transaction</p></dd>




<dt><span class="LITERAL">Not_Supported</span></dt>
<dd><p>Instructs the web server <em>not</em> to start a
transaction</p></dd>

</dl>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example</td>
</tr>
<tr>
<td colspan="2" class="description">




<span class="PROGRAMLISTING"><pre>&lt;%@ TRANSACTION=Required%&gt;

' This code instructs the web server to start a new
' transaction for the current script.</pre></span>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Notes</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>Note that the value for the <span class="LITERAL">TRANSACTION</span> directive
is not a string. For this reason, you must use an underscore for
those values that contain a space (<span class="LITERAL">Requires_New</span>
and <span class="LITERAL">Not_Supported</span>). As discussed in <link linkend="ch06-1-fm2xml">Chapter 6</link>, only a single script can be encapsulated in a
transaction. You must ensure that the <span class="LITERAL">TRANSACTION</span>
directive is the first line in a transactional script. Otherwise, it
will result in an error. Finally, you cannot encapsulate the
<filename>GLOBAL.ASA</filename> code in a transaction.</p>




<p>If an error occurs in a script encapsulated in a transaction,
Microsoft Transaction Server will roll back any actions that support
transactions. Currently, only database actions support transactions.
For example, not all disk activity is supported by MTS-based
transactions and must be rolled back manually.</p>



</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
</body>
</html>