Description

Runs when ColdFusion receives the first request for a page in the application.

Syntax

<cffunction name="onApplicationStart" returnType="boolean">
    ...
    <cfreturn Boolean>
</cffunction>

See also

onApplicationEnd, Method summary, "Managing the application with Application.cfc" in he ColdFusion Developer's Guide

Returns

A Boolean value: True if the application startup code ran successfully; False, otherwise. You do not need to explicitly return a True value if you omit the cffunction tag returntype attribute.

Usage

Use this method for application initialization code; for example, use it to set Application scope variables, to determine whether a required data source or other resource is available, or to log the application start. You do not have to lock the Application scope if you set Application variables in this method, and you can reference Application scope variables as you normally do; for example, as Application.myVariable.

This method can access the requested page's Variables scope only if the Application.cfc file includes an onRequest method that calls the page.

If you call this method explicitly, ColdFusion does not start the application; it does execute the method code, but does not lock the Application scope while the method executes.

If this method throws an uncaught exception or returns False, the application does not start and ColdFusion does not process any pages in the application. In this case, ColdFusion will run the onApplicationStart method the next time a user requests a page in the application.

Example

The following example tests for the availability of a database. If the database is not available it reports and logs the error, and does not start the application; if it is available, the method initializes two Application scope variables.

<cffunction name="onApplicationStart">
    <cftry>
        <!--- Test whether the DB is accessible by selecting some data. --->
        <cfquery name="testDB" dataSource="cfdocexamples" maxrows="2">
            SELECT Emp_ID FROM employee
        </cfquery>
        <!--- If we get a database error, report an error to the user, log the
                error information, and do not start the application. --->
        <cfcatch type="database">
            <cfoutput>
                This application encountered an error<br>
                Please contact support.
            </cfoutput>
            <cflog file="#This.Name#" type="error" 
                text="cfdocexamples DB not available. message: #cfcatch.message# 
    Detail: #cfcatch.detail# Native Error: #cfcatch.NativeErrorCode#" >
            <cfreturn False>
        </cfcatch>
    </cftry>
    <cflog file="#This.Name#" type="Information" text="Application Started">
    <!--- You do not have to lock code in the onApplicationStart method that sets
            Application scope variables. --->
    <cfscript>
        Application.availableResources=0;
        Application.counter1=1;
    </cfscript>
    <cfreturn True>
</cffunction>