Preprocessing Directives |
Active Server Pages provides preprocessing directives 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 <%= expression %>, 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 <%= expression %> directive) is the following:
    <%@ DIRECTIVE=Value%>
where DIRECTIVE is one of the ASP directives listed in this section and Value is a valid value for the directive. Note that you must include a space between the @ character and the directive. Also note that the preprocessing directive must be placed within <%...%> delimiters.

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

- CODEPAGE
- ENABLESESSIONSTATE
- LANGUAGE
- LCID
- TRANSACTION

Preprocessing Directives: Comments/Troubleshooting |
The space between the @ 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.

You may ask yourself how you can have more than one directive in a script if directives, with the exception of <%= expression %>, must be placed on the first line of a script. To include more than one directive, use the following syntax:

    <%@ DIRECTIVE1=ValueDIRECTIVE2=Value %>

You must include at least one space between each directive. Also, you must not place spaces around the equal signs (=).

CODEPAGE |
<%@CODEPAGE=uintCodePage%>
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 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 CODEPAGE preprocessing directive dictates how the script itself is interpreted, whereas the CodePage property of the Session object dictates how the resulting HTML is processed.
Parameters

uintCodePage

  An unsigned integer value corresponding to a valid code page for the web server running the ASP script

Example
    <%@ CODEPAGE=932%>

    ' This code sets the code page to OEM 932, which is
    ' used for Japanese Kanji.
Notes
You can have both the CODEPAGE 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 CODEPAGE directive and the client information being interpreted using the code page set of the CodePage property of the Session object.

ENABLESESSIONSTATE |
<%@ ENABLESESSIONSTATE=True|False%>
Turns the storage of user-specific session information on (True) or off (False). This value is True by default.
Parameters
None
Example
    <%@ ENABLESESSIONSTATE=False%>

    ' This code prevents the web server from storing
    ' user session information.
Notes
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.

Setting this directive to False 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:

  It does not rely on your clients' browsers using cookies.

  It increases the speed with which your server scripting is processed by the web server.

LANGUAGE |
<%@ LANGUAGE=ScriptingEngine%>
Sets the default scripting engine the web server will use to process the script in your ASP. This is set to VBScript by default.
Parameters

ScriptingEngine

  A valid scripting engine recognized by Internet Information Server. The valid scripting engines include VBScript, JScript, PerlScript, Python, and REXX.

Example
    <%@ LANGUAGE="JScript"%>

    ' 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.
Notes
Setting the LANGUAGE 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:
    <%@ LANGUAGE="JScript"%>
    <SCRIPT LANGUAGE="VBScript" RUNAT="Server">
    Sub ShowReport( )
    	' This script will be interpreted using the VBScript
    	' scripting engine.
    End Sub
    </SCRIPT>
Furthermore, setting the LANGUAGE directive value has no effect on the scripting engine used on the client side. Even if you set the LANGUAGE of the server-side script to PerlScript, for example, you can still set the LANGUAGE attribute of the client-side <SCRIPT> tag to JScript, as in the following example:
    <%@ LANGUAGE="PerlScript"%>

    <%
    ' All server-side script is interpreted using the PerlScript
    ' scripting engine.
    %>

    HTML here...
    <SCRIPT LANGUAGE="JScript">
    function btnReport_onClick
        ' This script will be interpreted using the JScript
        ' scripting engine.
    End Sub
    </SCRIPT>
Note that only the VBScript and JScript scripting engines are included with IIS. All other scripting engines must be obtained and installed separately.

LCID |
<%@ LCID=dwordLCID%>
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.
Parameters

dwordLCID

  A DWORD (32-bit unsigned) value that represents a valid locale ID.

Example
    <%@ LCID=1036%>

    ' This code sets the locale ID for the server-side
    ' script to that for French.
Notes
Just as setting the CODEPAGE directive has no effect on the CodePage property of the Session object and what character set is used on the client side, setting the LCID directive has no effect on the 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.

TRANSACTION |
<%@ TRANSACTION=strValue%>
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.
Parameters

strValue

  The possible values for the strValue parameter are as follows:

Required

  Instructs the web server that the current script requires a transaction

Requires_New

  Instructs the web server that the current script requires a new transaction

Supported

  Instructs the web server not to start a transaction

Not_Supported

  Instructs the web server not to start a transaction

Example
    <%@ TRANSACTION=Required%>

    ' This code instructs the web server to start a new
    ' transaction for the current script.
Notes
Note that the value for the TRANSACTION directive is not a string. For this reason, you must use an underscore for those values that contain a space (Requires_New and Not_Supported). As discussed in Chapter 6, only a single script can be encapsulated in a transaction. You must ensure that the TRANSACTION directive is the first line in a transactional script. Otherwise, it will result in an error. Finally, you cannot encapsulate the GLOBAL.ASA code in a transaction.

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.