Include Files - Write Once, Use Many Times (ASP)

Written by RobWoz published 8th Mar 2006 | Comment on this article

As you may know, it is possible in ASP to include one file within another. There are two ways to do that - one of which has potential pitfalls.

Include Files - Write Once, Use Many Times

As you may know, it is possible in ASP to include one file within another. The benefit of doing this is that you can put common code routines into a single file and then include that file in any other code files that need to use it. This means that you can have a central code library and you don't have to keep replicating subs and functions all over the place (in the different files that need to use them).

Imagine I've now written all my common string handling routines into StringRoutines.asp and placed that file in a special folder (off the web root) called 'common'. I would typically do this because there are other common files I might want to write later (such as EmailRoutines.asp, and DatabaseRoutines.asp etc). But for now I just have StringRoutines.asp - so how do I make use of it from within other ASP files such as the default.asp file for example?

Very simple - you place a statement in the default.asp file that tells IIS to include StringRoutines.asp, and then later on down in default.asp, you can just call any of the subs and functions that are contained in StringRoutines.asp. Note: Although I said 'later on down', you can place the call to a sub/function either above or below the include statement. But you will help IIS compile the page faster if you make sure that subs and functions that are going to be called by other code appear in the file higher up from where they are called.

There are two different include statements that you can use. They are slightly different from one another, but one of them has potential pitfalls.

First, there is this way...

<!--#Include File ="common\StringRoutines.asp"-->

IIS will look for a folder called 'common' on the same level as the script it is about to execute (in this case default.asp) and look for StringRoutines.asp and slap the whole contents of that file right where you put the include statement (the actual physical file is not affected - just IIS's temporary copy). At this point IIS has a big text file with all the code in it, and it proceeds to compile it and send the results to the browser.

This method is OK until you come to wanting to include the file in an ASP page that is inside another folder off the root of the web. Let's say, the ListGuests.asp file in the 'guestbook' folder for example. You will have to remember to change the path to the include such that IIS will find it, otherwise you will get an error.

It would have to look like this...

<!--#Include File ="..\common\StringRoutines.asp"-->

But even if you do remember to set the path correctly, you will soon find that moving an ASP page that uses include files will stop working unless you change the path in the above statement.

Another downside is that if your scripts are executing on a host's server that has the 'no parent paths' security policy switched on (the default on IIS 6) - your include statements that use '..' to access the parent path of the current folder will not work at all.

The answer is to employ the alternative version of the statement that uses the keyword 'Virtual'...

<!--#Include Virtual ="common\routines.asp"-->

This will work no matter where your script is that contains the statement because you are instructing IIS where the common folder is relative to the web root.

It really is worth organising your code in this way, because as your site becomes bigger, the use of 'include files' will help you manage it more efficiently and with less possibility of error on your part.