ASPC directives

ASPC supports a set of directives which can be useful to control the compilation process and certain characteristics of the produced code.

All the directives supported in the current version are supported outside any function/sub or class declaration. They all take effect over the next statement only (With statements are treated as a single statement - They begin with the With keyword and end with End With). Every directives is applicable for some types of declarations or statements. the compiler will issue an warning if a directive is unexpected to remind you.

Directive syntax is:

'#! <Keyword> [<parameter>]

They must be on a single line immediately before the affected statement/declaration. Parameter is required for some of them (see below) - the others end with the keyword - which is the keyword used by the compiler to recognize the directive. '#I .is treated as comment by the VBScript and VB thus the directives will not change your code functionality and are ignored by the VBScript and VB language parsers. 

Directives:

AutoVariables
Should be put in the ASP pages outside any class or Sub/Function. When found all the undeclared variables are made class members and are not treated as local variables for the current routine. In most cases ASP applications built without Option Explicit and not using VBScript classes will benefit of this directive. The reason behind the scene is that in VBScript the undeclared variables are assumed global while in VB they are assumed local. This often leads to functionality errors if the "undeclared variable" warnings are ignored by the developer. Using this directive will adjust the behavior of the compiled application in manner close to the VBScript and will automatically solve any such problems in about 90-95% of the ASP/VBScript applications where no VBScript Class-es are used. In case of Class usage we recommend reviewing your code and declaring all the variables - because such applications have more complex structure and correct automatic determination of a variable scope is not always possible.

Sample:
'#! AutoVariables

DLLGlobal 
Next statement will be placed in the global VB module - one module for all the instances of the components contained in the DLL. ASPC automatically places all the global constants there, but the other statements can be placed in the global .bas module only in some certain situations which cannot be determined only by the programmer. 

Can be used before: global Dim statements and global Sub and Function declarations.

A Sub or a Function can be declared DLLGlobal if they do not use any variables which are not declared DLLGlobal, no variables defined in the script outside their body and no external namespaces (for example in ASP - Request, Response etc).

Sample:
'#! DLLGlobal
Dim g_MyGlobalVariable

Discard
Next statement will not be compiled. Can be placed before With blocks, usual statements (not Dim-s).

It is most useful to discard some code not applicable for the compiled component. For example you may want to set some global variables in your ASP page and you did it in the script. If you want to be able to change their values in the compiled version without recompiling the component you are able to declare them public (default) and use them as properties. Thus you are able to set their values before executing the component in the script that creates it. In most cases discarded statements will cause runtime errors when the component is executed if these properties are not set. Thus ASPC places some comments about every discarded statement into the loader file in order to remind you to edit this file and set them..

Sample:
'#! Discard
strCompanyName = "ACME Inc."

Creatable
This directive is applicable only for VBScript class declarations. It instructs the ASPC to make the class public and createable. Which means the class can be created using the CreateObject in external applications and scripts.

Usage of this directive can be useful in rare cases and will not cause useful results if the class affected depends on the variables defined in the global part of the script. See also Program IDs and  Execution contexts.

The directive is intended for use by the developers who want to build COM libraries with utility objects. 

Sample:
'#! Createable
Class MyClass
' ... Class body
End  Class

Public
This directive like the previous is applicable for the VBScript classes only. It can be used safely in many cases and especially if you are building components which can be used in other environments - for example for HTML generation in a VB program.

The directive makes the objects of this class available for the external applications if they are obtained somehow from a property or function declared in the global part of the script. For example an ASP include file can be converted to a set of utility classes. The global part of it will be used for initialization purposes but you are able to define functions which create and return some of the VBScript classes defined in the file and use them for the real work in another ASP pages compiled  or not). See the ASPC samples if you are interested in such usage.

'#! Public
Class MyClass
' ... Class body
End  Class

ClassName
This directive overrides the default behavior of the ASPC concerning the class name creation of the VB class created from your script/page. By default ASPC generates unique name for the project combining a suffix and part of the file name. If you are just converting a page it will be enough but if you want to use the resulting component for other purposes you will want to set a meaningful name for the class - which will be easy to remember and use. 

The full syntax is:
'#! ClassName SomeName

SomeName can be any acceptable name for VB/VBScript identifier. It can contain alphanumeric characters and "_" but it must begin with alphabetic character.

DbgTrace
Marks the next statement as applicable only for the debug builds. Corresponds to the Debug build option in the project settings dialog. If the project is build with this option unchecked these statements will be discarded. Can be used in function/sub/property bodies but cannot be used to mark entire class or class members.

Sample:
'#! DbgTrace
dbg.Msg "This is after initialization"

Samples

Keep in mind - if you just want to use ASPC to convert your ASP pages or other scripts and use them instead of the original scripts, then you don't need to use any directives. Optionally you are able to make your pages configurable using the Discard directive, but the other directives are for the developers who want to do more than replacing the script with DLLs.

Sample 1:

Making an ASP page configurable.

Suppose you have a page which uses a company name to determine which table from the DB will be used. If you want to deploy copies of this page without compiler you may just copy it in several directories/sites and modify it. But with ASPC you will need to create a set of components for every copy - there is much more convenient way. If the mentioned code looks like this:

Dim strCompany, dbConn, rst
' Some code that creates ADO connection and so on
strCompany = "ACME"
Set rst = dbConn.Execute("SELECT * FROM " & strCompany)
' code to display the results

Now you want to compile this. In the DLL the value for the strCompany will be hard coded as "ACME". This will not be convenient if you ant to use the same page for other companies. Then you should modify the above code by adding the discard directive:

Dim strCompany, dbConn, rst
' Some code that creates ADO connection and so on
'#! Discard
strCompany = "ACME"
Set rst = dbConn.Execute("SELECT * FROM " & strCompany)
' code to display the results

Now this line will not be included in the compiled code. But without setting the variable your component will raise error because the query sent to the DB is not correct. Thus you will need to modify the loader page and set there the strCompany value from the outside. Loader page generated in the output directory tree will look like this:

<%
Dim proc
Set proc = Server.CreateObject("PrjName.cls0page_asp")
Set proc.Application = Application
Set proc.Request = Request
Set proc.Response = Response
Set proc.Server = Server
Set proc.Session = Session
proc.ASPCExecuteClass
%>

You will need to add a line to set strCompany in it:

<%
Dim proc
Set proc = Server.CreateObject("PrjName.cls0page_asp")
Set proc.Application = Application
Set proc.Request = Request
Set proc.Response = Response
Set proc.Server = Server
Set proc.Session = Session
proc.strCompany = "SerendipityInc"
proc.ASPCExecuteClass
%>

Now this page will cause your component to use SerendipityInc for the table name. And you are able to make as many copies as you need and modify this setting in every copy but using only one compiled component - not filling your system with hundreds of DLLs with only difference between each other in several characters defining values of certain variables.

Sample 2:

Creating a library of utility classes which will be used instead of includes in another ASP pages.

Suppose you want to use part of your code in many projects/sites and it is enough universal and can be used partially. Usually you will do so by placing it in include files accessible or copied in all these projects. Include files used as libraries have a "bad habit" to grow too much and step by step they are lowering the performance of your applications because IIS needs to process them in every page where they are included.

It is simple to use an include that is collection of functions as library - you will need just to compile it and include the code from the loader file in every page where these routines will be used. Then you will need to call them as members of the created component. But we will present a most complicated case here - in which you want to expose entire VBScript classes and not just functions.

<%
Class MyClass
  ' some class variables
  Public Property Get MyProperty
    ' body
  End Property
  Public Sub Init(a_arameter)
    ' class initialization
  End Sub
End Class
Function CreateMyClass
  Dim o
  Set o = New MyClass
  ' probably some code that determines
  ' how to initialize the object
  o.Init value_for_the_parameter
  CreateMyClass = o
End Function
' other coed
%>

Now suppose you want to obtain instances of the class from the above code in another ASP pages (probably not compiled) and use it. The Function CreateMyClass is intended to create and initialize it. Thus you will compile this file (probably used as include file in the original pages) and as it was mentioned above you will use the code from the loader page in the pages in another pages and you will call this function to obtain an object and you will use it further in your code. There is one problem - all the VBScript classes are by default private and can be used only into the DLL. thus you will need to place Public directive just before the Class declaration - this will allow its usage outside in any other application.

It is recommended to review the samples and see more detailed example on how to do so. Converting your code to a library will not need rewriting, but you still need to take a look and probably make some corrections in order to make it independent of a particular page or application.