ColdFusion Server 4.5
New Features and Enhancements

This page provides details about new features that have been added to ColdFusion Server 4.5. For important information about the current release, including fixed issues and known issues, see the Release Notes.

ColdFusion 4.5 New Features

Change to CFFTP ListDir

CFFtp ListDir now returns a "Mode" column containing an octal string representation of UNIX permissions (e.g., "777"), when appropriate.

New Unsecured tags directory option in the Administrator

The ColdFusion Administrator, Basic Security page contains a new option that allows you to specify a directory from which otherwise blocked tags can be executed. To enable this option, open the Basic Security page in the Administrator and enter a fully qualified path (using forward slashes) in the Unsecured Tags Directory field. By default, this is the directory in which the ColdFusion Administrator is installed.

CreateObject

Allows you to call methods in COM, CORBA, and JAVA objects.

Notes: ColdFusion administrators can disable the CFOBJECT tag in the ColdFusion Administrator Basic Security page, which also disables this function. On UNIX, COM objects are not currently supported by CreateObject.

Refer to the CFML Language Reference for details about CreateObject.

Enhancements to CFCACHE

There are two enhancements to CFCACHE: The ability to use browser-side caching; and the ability to specify an alternate cache directory (when using server-side caching.) In terms of new/changed attributes, it shakes out as follows:

• Two new action attributes: "OPTIMAL" and "CLIENTCACHE"
• One new attribute: CACHEDIRECTORY

CACHEDIRECTORY when specified, causes support files involved in server-side caching to be stored in the specified directory instead of (by default) in the directory where the page you're caching resides. Note: The directory you specify must already exist (or the attribute will be silently ignored.)

Action=CLIENTCACHE tries to use the caching facilities of the browser to avoid regenerating and even retransmitting the page. In this mode server-side caching is off (just as in the default, Action=CACHE, mode client-side caching is off.)

Action=OPTIMAL uses both browser-side and server-side caching to deliver the page as fast as possible. If the page can resolved from the browser's cache it does that first. If that fails, it tries the server's cache. If that fails, it regenerates the page.

New HTTP_IF_MODIFIED_SINCE CGI variable

A new CGI variable is available called "HTTP_IF_MODIFIED_SINCE" which can be accessed in ColdFusion pages via our CGI scope as "CGI.HTTP_IF_MODIFIED_SINCE".

This variable is sent at the discretion of the browser usually in response to the server having sent the LAST_MODIFIED HTTP header. It can be used to take advantage of browser-side caching.

Running scheduled tasks from the Administrator

In the ColdFusion Administrator Scheduler page you can now RUN the scheduled task by clicking the RUN link. The task is submitted immediately. The output also lets you know it completed. However you still need to check the log files or for an output file or sent mail to determine if the execution of the target template was successful.

In addition to the RUN support you can now turn on ColdFusion Executive logging for task scheduling under the scheduled settings entry. When this is checked, CF Executive will write to the schedule log when it is refreshing the schedule list from the registry, listing any changes to already scheduled task and new tasks which have been added.

STRING_NOCASE value for CFGRIDCOLUMN TYPE attribute

The CFGRIDCOLUMN tag now supports an additional value "STRING_NOCASE" for its TYPE attribute. When TYPE="STRING_NOCASE", data in the grid can be sorted by the end user as case insensitive text data like an Excel spreadsheet rather than as case sensitive character text.

New LIST and SEPARATOR attributes for the CFQUERYPARAM tag

The CFQUERYPARAM tag now supports two new attributes:

• LIST=(YES/NO) where NO is the default
• SEPARATOR="separator character" where the default is ",".

If LIST=YES then the <CFQUERYPARAM treats the parameter value as a list of values separated by the SEPARATOR character. If the value is NULL it is treated as a single NULL value. A SQL parameter is generated for each item in the list. Validation is performed on each item. If you specify a MAXLENGTH then this MAXLENGTH is used to validate the length of each item not the length of the entire list. The LIST=YES setting is useful for passing a list of values to an IN clause in a SQL statement. For example - select * from foo where foo_id in ( <CFQUERYPARAM VALUE="10,30," CFSQLTYPE="CF_SQL_INTEGER" LIST=YES> )

New locking features enabled

In previous beta releases, automatic thread locking, a feature available on the locking page of the ColdFusion Administrator, was not yet operational. Automatic locking is now working as intended.

In addition, the single threading option is also working as intended. For more information about locking in ColdFusion, see Locking enhancements later in this document.

CFRETHROW tag

The <CFRETHROW> tag can be used from inside a <CFCATCH> block to re-throw the currently active exception. <CFRETHROW> will preserve the exception’s CFCATCH.TYPE and CFCATCH.TAGCONTEXT information.

CFRETHROW takes no arguments and it can only appear within a CFCATCH block.

Advanced security updates

There are a couple of updates in the Advanced Security section of ColdFusion Administrator.

• On Windows NT only -- sandboxes can now be of type "OS". What this means is that all ColdFusion templates executed within the sandbox will be run with the privileges and restrictions of the NT user specified. This will mean that all OS-level protection to OS-level resources such as files will automatically be enforced.

  Instead of specifying a security context for the sandbox, specify an NT domain. The user whose privileges you want to apply to the sandbox must be a member of that NT domain.

• You can now now have the option of specifying that all resources of protected resource types in a security context be protected by default. If you choose this option no resources of protected types will be authorized for any user unless you create a rule for it and allow access to it to one or more users/groups in a policy. This is different from the default case where a resource is not protected till you create a rule for it.

  Note that protecting *all* resources should only be used as a stopgap measure, for example, while the Admin is implementing an Advanced security framework. It's not advisable to have this setting selected if applications are running against the server.

Basic security enhancements

The new CFAdminSecurity tag as well as another new tag CFExecute have been added to the current list of tags (CFContent, CFDirectory, CFFile, CFObject and CFRegistry) that can be disabled in Basic Security.

CFEXECUTE tag

Enables ColdFusion developers to execute any process on the server machine.

Syntax

<CFEXECUTE NAME=" ApplicationName "
   ARGUMENTS="CommandLine Arguments"
   OUTPUTFILE="Output file name"
   TIMEOUT="Timeout interval in seconds">

NAME

Required. The full pathname of the application that is to be executed.

Note: On Windows systems, you must specify the extension, for example, .exe, as part of the application’s name.

ARGUMENTS

Optional. Any command-line arguments that should be passed to the program.

If ARGUMENTS is specified as a string, it is processed as follows:

• On Windows systems, the entire string is passed to the Windows process control subsystem for parsing.
• On Solaris, Linux, and HP-UX systems, the string is tokenized into an array of arguments. The default token separator is a space; arguments with embedded spaces may be delimited by double quotes.

If ARGUMENTS is passed as an array, it is processed as follows:

• On Windows systems, the array elements will be concatenated into a string of tokens, separated by spaces. This string is then passed to the Windows process control subsystem as above.
• On Solaris, Linux, and HP/UX systems, the elements of the ARGUMENTS array is copied into a corresponding array of exec() arguments.

OUTPUTFILE

Optional. The file where the output of the program is to be directed. If this is not specified, the output appears on the page from which it was called.

TIMEOUT

Optional. Indicates how long in seconds the ColdFusion executing thread will wait for the spawned process. Indicating a timeout of 0 is equivalent to the non-blocking mode of executing. A very high timeout value is equivalent to a blocking mode of execution. The default is 0; therefore, the ColdFusion thread spawns a process and immediately returns without waiting for the process to terminate.

If no output file is specified, and the timeout value is zero, then the program’s output will be directed to the bit bucket.

Usage

CFEXECUTE is available on Windows NT 4.0 and UNIX platforms. Do not put any other ColdFusion tags or functions between the start and the end tags of CFEXECUTE. Also, CFEXECUTE tags cannot be nested.

Exceptions

CFEXECUTE throws the following exceptions:

• If the application name is not found, an Application File Not Found exception will be thrown.
• If the output file cannot be opened, an Output File Cannot be opened will be thrown.
• If the effective user of the ColdFusion executing thread does not have permissions to execute the process, a security exception will be thrown.

The time out values must be between 0 and some high number (to be determined).

Example

<!---------------------------------------------------------------------- 

This example illustrates use of the CFEXECUTE tag. 

----------------------------------------------------------------------->

<HTML>
<HEAD>
<TITLE>CFEXECUTE</TITLE>
</HEAD>


<BODY>

<H3>CFEXECUTE</H3>

<P>

This example executes the Windows NT version of the netstat network 
monitoring program, and places its output in a file.


<CFEXECUTE NAME="C:\WinNT\System32\netstat.exe"
   ARGUMENTS="-e" 
   OUTFILE="C:\Temp\output.txt"
   TIMEOUT="1">

</CFEXECUTE>

</BODY>
</HTML> 

ToString function

Attempts to convert a value of any type, including a binary value, into a string.

Syntax

ToString(any_value)

Where any_value is the value that is to be converted into a string.

Usage

If ToString cannot convert the value into a string, it throws an exception.

JSStringFormat function

Returns a string that is safe to use with JavaScript.

Syntax

JSStringFormat(string)

Where string is any string.

Usage

JSStringFormat escapes special JavaScript characters, such as the single quote (’), double quotes ("), and newline character so that you can put arbitrary strings safely into JavaScript.

XMLFormat function

Returns a string that is safe to use with XML.

Syntax

XMLFormat(string)

Where string is any string.

Usage

XMLFormat escapes special XML characters, such as the less than (<) and greater than (>) signs so that you can put arbitrary strings safely into XML.

New Redirect attribute for CFHTTP

The new Redirect attribute for CFHTTP is a boolean indicating whether to redirect execution or stop execution. The default is YES. If set to NO and THROWONERROR is set to YES, execution stops if CFHTTP fails, and the status code and associated error message are returned in the variable CFHTTP.StatusCode. To see where execution would have been redirected, use the variable CFHTTP.Response_Header[LOCATION]. The key LOCATION identifies the path of redirection.

New Locale Attribute for CFOBJECT

The LOCALE attribute can be used to set arguments for the the call to init_orb(..). This is specific to VisiBroker orbs, and has only been tested with the 3.2 C++ version.

The value should be of the form:

<CFOBJECT TYPE=CORBA
 ..
LOCALE=" -ORBagentAddr 199.99.129.33   -ORBagentPort 19000" 
..>

Please note that each type-value pair has to start with a leading "-".

Improved query caching performance

Cached query performance has been improved. Individual queries are locked when operations are performed on them rather than having the whole cache locked for each query as it was in 4.0.1 and 4.5 beta releases. This means that operations can be performed on multiple queries simultaneously at any given time.

Corba User Exceptions

Exceptions thrown by java object methods can be caught by the <CFTRY><CFCATCH> tags. ColdFusion checks if the exception thrown is the method exception and stores the classname of the exception in the "message" field of <CFCATCH> variable.

Building Java CFXs

Please see the ColdFusion documentation for details concerning the developement of Java CFXs.

After developing the CFX, please make sure that the location of the class files is in the classpath (specified using the CF Administrator). Register the tag using the custom tag page. Information here includes the name, description, and the classname that implements the Allaire CustomTag interface.

To use an existing CFX_J, please open the following key in your registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Allaire\ColdFusion\CurrentVersion\CustomTags\CFX_J

Add a new string value called "Type", and give it the value "JAVA". You will now be able to use the custom tag as before.

Please note that Allaire will phase-out this tag in future releases, and recommends that you simply convert it to a Java Custom tag.

For example, if you currently use the CFX_J tag that has the CLASS attribute set to "Foo", then to use a Java CFX, you would do the following:

1. Rename your custom tag to something like "CFX_Foo"
2. Add the "java" custom tag using the ColdFusion Administrator. Specify the classname as "Foo" (case sensitive) in the appropriate field.
3. Call you custom tag from your template using CFX_Foo instead of CFX_J. You should omit the "CLASS" attribute in the tag.

CFOBJECT support for calling Java objects

ColdFusion 4.5 beta 3 introduced support for calling Java objects (and by extension EJB objects) through CFOBJECT, and through Java CFXs.

To be able to call Java CFXs or Java objects, ColdFusion uses a JVM embedded in the process. The loading, location and the settings for the JVM are configurable using the COldFusion Administrator pages.

Using CFOBJECT

Any java class available in the classpath specified in the CF Adminstrator can be loaded and used from ColdFusion using the CFOBJECT tag. The syntax

<CFOBJECT Type=Java  Class=MyClass Name = myObj>

will load the class but not create an instance object. Static methods and fields are accessible after the call to CFOBJECT.

To call the constructors explicitly, use the "init" method with the approproate arguments.

<CFSET ret = myObj.init(arg1, arg2)>

Calling a public method on the object without first calling the "init" method will result in an implicit call to the default constructor. Arguments and return values can be any valid Java type (simple, arrays, objects). ColdFusion does the appropriate conversions when strings are passed as arguments, but not when they are received as return values.

ColdFusion 4.5 provides the function "javaCast()" that can sometimes be used to disambiguate arguments to overloaded methods on a Java object. This function can only be used to perform (or provide a hint for ) casting between scalar types and strings. This function should only be used when an overloaded method expects the same number of arguments. Please note that this function cannot be used to cast between complex objects, or to cast to a super-class. The result of this function should only be used on calls to java objects. Also note that given that there is no 1-to-1 correspondence between internally stored CF types and Java scalar types not all conversions can be performed.

Usage:

	javaCast(<type>, <variable>)        

	<type> : "bool", "int", "long", "double", or "String"
	<variable> : any ColdFusion variable holding a scalar or string type.

Example:

Consider that fooClass has a method fooMethod that takes a single argument whih is overloaded as follows:

	public void fooMethod(String arg);
		public void fooMethod(int arg);

Within ColdFusion, you would do the following:

	<cfobject Type=java class=fooClass Name=obj>

	<!--- CF may treat this as a string or a real number --->
	<cfset x = 33>

		<!--- Perform an explicit cast to an int  --->
	<cfset myInt = javaCast("int", x)> 
	<cfset void = fooMethod(myInt)>

		<!--- Perform an explicit cast to an int  --->
		<cfset myString = javaCast("String", x)> 
		<cfset void = fooMethod(myString)>

Calling EJBs

You would use CFOBJECT to create and call all the appropiate objects. The sequence below assumes that the Weblogic JNDI is used to register and find EJBHome instances:

<cfobject action=create 
		type=JAVA
		class="weblogic/jndi/Environment"
		name=wlEnv>

<CFSET ctx = wlEnv.getInitialContext()>
<CFSET ejbHome = ctx.lookup("statelessSession.TraderHome")>			 
<CFSET trader = ejbHome.Create()>	 
<CFSET value = trader.shareValue(20, 55.45)>	 

<CFOUTPUT>
	 Share value = #value#
</cfoutput>	 

<CFSET value = trader.remove()>

The CFOBJECT tag creates the Weblogic Environment object, which is then used to get the InitialContext. The context object is used to look up the EJBHome interface. The call to create() results in getting an isntance of stateless session EJB.

Enhancements to CFHEADER

Two new attributes have been added to CFHEADER, StatusCode and StatusText. These new attributes allow you to set the HTTP result/status code and the optional explanatory text that goes along with this code in the HTTP header.

Now, in addition to the existing usage which looked like:

  <CFHEADER   Name="MyCustomHeader"  Value="FourScoreAndSeven...">

you can now say (in a separate instance of CFHEADER):

  <CFHEADER StatusCode="404"  StatusText="Duh! No such page exists.">

The StatusText attribute is optional but it can be used only when using the StatusCode syntax. For clarity, the old style Name/Value syntax cannot be mixed with the new style StatusCode/StatusText syntax. This is consistent with the existing behavior of the tag which did not allow multiple name/value pairs to be specified in a single call to CFHEADER.

New Advanced Security Resource Types

Two new resource types, Functions and Users, have been added to Advanced Security.

You can now protect any ColdFusion function in the following ways:

1. By creating a rule for it in a security context in the ColdFusion Administrator
2. By adding the function as a protected resource in the Administrator resource view.

You can control access to users that are allowed to be impersonated (using the CFImpersonate tag). You can do this by:

1. Creating a rule for it in a security context in the ColdFusion administrator
2. Adding the user as a protected resource in the new resource view

URLDecode function

Syntax

URLDecode(urlEncodedString)

urlEncodedString

A string that has been URL-encoded.

Remarks

URL encoding refers to a data format where all high ASCII and non-alphanumeric characters are encoded using a percent sign followed by the two character hexadecimal representation of the character code. For example, a character with code 129 will be encoded as %81. In addition, spaces can be encoded using the plus sign (+).

Query strings in HTTP are always URL-encoded.

URL-encoded strings can be created using the URLEncodedFormat function.

Example

Here's an example of the URLDecode and URLEncodedFormat functions. In the example, a string containing all ASCII character codes in the range 1-255 is created. The string is then encoded and decoded. The decoded value is compared with the original string to demonstrate their equality.

<cfscript>
	// Build string
	s = "";
	for (c = 1; c lte 256; c = c + 1)
	{
		s = s & chr(c);
	}

	// Encode string and display result
	enc = URLEncodedFormat(s);
	writeOutput("Encoded string is: '#enc#'.<br>");

	// Decode and compare result with original
	dec = URLDecode(enc);
	if (dec neq s)
	{
		writeOutput("Decoded is not the same as the encoded.");
	}
	else
	{
		writeOutput("All's well on the Western front.");
	}
</cfscript>

New groupCaseSensitive attribute

A new attribute, groupCaseSensitive, has been implemented in the CFOutput and CFMail tags. As a boolean, its value determines whether grouping is case-sensitive or case-insensitive. The default is TRUE to maintain backward compatibility.

groupCaseSensitive will only work if the recordset has been grouped appropriately already. CFOutput/CFMail will perform no re-grouping or re-sorting on the recordset.

Sybase 11.1.1 native driver for Linux

A Sybase 11.1.1 native driver is now available on the linux platform. During the beta period, we had shipped a Sybase 10.4 nativer driver on the Linux platform. Sybase has made their 11.1.1 client libraries freely available. To download them go to http://www.sybase.com:80/products/databaseservers/linux/index.html and download the 11.9.2 development kit. This release version is consistent with our win32, Solaris and HP_AUX Sybase native drivers and is the release that ColdFusion Server for Linux supports.

In order to use the new driver you must set your SYBASE environment variable to the install 11.9.2 directory.

GetFunctionList function

A new function, GetFunctionList(), is available for ColdFusion Server. It returns a structure of functions that are available in ColdFusion.

<cfset fList = GetFunctionList()>
<cfoutput>#StructCount(fList)# functions<BR><BR></cfoutput>
<cfloop collection="#fList#" item="key">
	<cfoutput>#key#<BR></cfoutput>
</cfloop>

The above code can be used to display the list of functions in ColdFusion.

CFServlet tag

The syntax of the CFServlet tag is designed to be consistent with the HTML markup <SERVLET> and <PARAM> used by some web servers to invoke Java servlets from .shtml pages (in what’s known as SSI, Server-Side Includes.) On the CF side, its operation is consistent with the <CFHTTP> and <CFHTTPPARAM> tags.

<CFSERVLET  Code=”MyServletName” 
JRunProxy=”127.0.0.1:8083” 
Timeout=”300”
WriteOutput=”YES”
>
	<CFSERVLETPARAM  Name=”Param1”  Value=”Value1”> 
	<CFSERVLETPARAM  Name=”Param2”  Value=”Value2”>
	<CFSERVLETPARAM  Name=”Attribute1”  Variable=”CFVar1”>
	<CFSERVLETPARAM  Name=”Attribute2”  Variable=”CFVar2”>
</CFSERVLET>

The CFSERVLET tag is a closed tag with one required attribute, CODE, describing the name of the Java servlet to execute and four optional attributes. This servlet must exist somewhere in the known universe of the JRun engine executing the servlet.

By default, that JRun engine is assumed to be on the host running CF, but it may actually be on a remote machine as specified by the optional JRUNPROXY attribute. This attribute value is the host name followed by an optional colon and port number.

The attribute, TIMEOUT, optionally specifies how many seconds CF will wait for the tag to complete its work. No markup other than the CFSERVLETPARAM tag should appear between the beginning and end CFSERVLET tags.

The WRITEOUTPUT parameter is an optional boolean parameter that specifies if regular text output of the tag should appear as inline text on the generated page or if it should be returned inside a CF variable for further processing . The default value, “YES”, means output is returned as text to appear inline on the generated page. Setting it to “NO” means no visible text is returned but the text is, instead, returned as the value of the CFSERVLET.OUTPUT variable.

The <CFSERVLETPARAM> tag

The CFSERVLETPARAM tag is an open tag that is always a child of CFSERVLET. It is used to pass data to the servlet. One piece of data is passed with each instance of the tag.

There are two different ways this tag can be used. The first two examples above demonstrate the simpler way to use the tag. Using the CF attribute VALUE, the tag will pass simple name/value string pairs to the servlet. The text strings representing these pairs will appear as servlet parameters on the Java side. Note that you need to have the updated version of JRun in order for the Name/Variable functionality to work. You can download the latest version of JRun at http://www.allaire.com/products/Jrun/.

The second way the tag can be used is demonstrated by the 3rd and 4th examples above. Here, the CF attribute VARIABLE is used to pass the specified CF variable by reference to the servlet. Within the servlet such data appear as Java attribute objects. In this case, it’s not the name of the variable but its value that’s being passed to the servlet. On the Java side, the data can be manipulated, even changed, and those changes will, in turn, change the value of the associated CF variable.

When used in this mode, the NAME attribute represents the name of the Java attribute that will be associated with this CF variable. The VARIABLE attribute represents the name (not #value#) of a CF variable. This ability to directly share CF variables with servlet is a powerful extension because it allows even complex CF objects such as structures and result sets to be directly accessed from Java.

On the Java side, CF variables passed in this manner will be available as the following Java objects: java.lang.Boolean, java.lang.Double, java.lang.Interger, java.util.Date, java.lang.String, java.util.Vector, java.util.Hashtable, and com.allaire.util.RecordSet. Simple CF data types (number, bool, and string) will map to the corresponding Java object types. CF arrays will map to Java Vectors. CF structures will map to Java Hashtables, and CF query result sets will map to the WDDX-supplied utility class, RecordSet.

Java programmers manipulate these objects via the standard servlet API attribute functions getAttribute, setAttribute, and getAttributeNames. If needed, they can enumerate what variables have been passed from CF using the getAttributeNames call. CF Variables can be retrieved using the getAttribute call, manipulated within the servlet as regular Java objects, and then return to CF using the setAttribute call. A CF variable passed to a Java servlet using this NAME/VARIABLE mechanism will possibly have a different value after the CFSERVLET tag than it had before the tag!

When using the NAME/VARIABLE mode of CFSERVLETPARAM an optional third attribute, TYPE, may also be specified. TYPE allows ambiguities resulting from moving variables from the largely typeless word of CF to the strictly typed world of Java to be resolved simply on the CF side. This is a convenience feature, eliminating the need to do extra casting on the Java side, since, in many cases, CF will not know the type of a simple object. In CF, a simple object can be readily manipulated as any simple type (number, string, bool, date) so CF doesn't keep track of what type a variable "should" be. By default CF will most often pass such variables to Java as strings. To have them appear on the Java side as some other type, specify that type as the value of the TYPE attribute. Valid values are: "INT", "DOUBLE", "BOOL",

Resource view in ColdFusion Administrator

A new view, the resource view, is available for the ColdFusion Administrator. It allows an administrator to allow/deny access to resources to specific users and groups. Most common administrator tasks can now be accomplished directly from the resource view instead of having to navigate through multiple admin pages. These are the tasks that can now be accomplished directly from the resource view:

• Protect a resource within a security context. This automatically creates a rule with an auto-generated rule name to protect the resource. This happens behind the scenes and the user does not get to know about rules or rule names. Note that you can only protect resources of types that have been selected for protection in the security context.
• Create a new policy to establish the users who are allowed access to a specific resource.
• Add or remove users from a policy.
• Allow or disallow access to specific rights to users in a policy. This will add and remove rules respectively from the policy.

Known issues in this version of the resource view are:

• Currently available only on Windows NT
• Wildcards for resources do not work
• The resource browser sometimes does not display its window on a refresh on IE4 and IE5

Changes to the ColdFusion Adminstrator

The Settings page is now being broken into two separate pages: Settings and Caching.

A new Locking page in the Server section has been added to cover new options for locking of shared scoped variables: (server, session, application)

Enhancements to CFHTTP

Catchable exceptions

Catchable exceptions are now possible from CFHTTP. Additionally, the granularity of error messages has been significantly increased. Instead of the standard “Connection Failure” or “Authorization Failure” messages CFHTTP now returns the HTTP status code associated with the response. There are 37 of these. CFHTTP throws these status codes and their associated standardized HTTP error string if an error occurs and the ThrowOnError attribute of CFHTTP is true. If ThrowOnError is not true because the user does not want to halt page processing, CFHTTP does not change the error i.e. “Connection failure.” A new variable has been added called CFHTTP.STATUS_CODE that will contain the code and message. If a user wants heightened error info, they can interrogate this variable.

Redirection

By default, the old 4.0.1 CFHTTP tag redirected a request automatically. The new CFHTTP tag does too, but there a new boolean attribute called REDIRECT has been added, which allows the user to stop CFHTTP from redirecting a request. When "No" the tag will fail if a redirect is needed and the appropriate status code, which can be seen by looking at CFHTTP.STATUS_CODE gets returned. The default for REDIRECT is "Yes."The user can look at the LOCATION response header to see where the redirection points.

GetMetricData function

GetMetricData returns all the internal data that is otherwise displayed in the Windows NT PerfMonitor or using CFStat on UNIX. For it to work on NT you need to have turned on the PerfMonitor feature from the ColdFusion Administrator. The function returns a ColdFusion structure with data in fields as follows:

<CFSET pmData = GetMetricData( "PERF_MONITOR" ) >

<cfoutput>
	Current PerfMonitor data is: <p>
	InstanceName:    #pmData.InstanceName# <p>
	PageHits:	  	  #pmData.PageHits# <p>
	ReqQueued:	  #pmData.ReqQueued# <p>
	DBHits:	              #pmData.DBHits# <p>
	ReqRunning:	  #pmData.ReqRunning# <p>
	ReqTimedOut:      #pmData.ReqTimedOut# <p>
	BytesIn:	         #pmData.BytesIn# <p>
	BytesOut:	         #pmData.BytesOut# <p>
	AvgQueueTime:    #pmData.AvgQueueTime# <p>
	AvgReqTime:	  #pmData.AvgReqTime# <p>
	AvgDBTime:	         #pmData.AvgDBTime# <p>
	CachePops:	        #pmData.CachePops# <p>
</cfoutput>

Debugging enhancement

A formerly unexposed feature, known internally as "GetExplodedBenchmarkingInfo" has now been exposed. Now known as the "Detail View", it is visible in the ColdFusion Administrator Debug Settings page.

When enabled, Detail View displays the amount of time required to process ColdFusion pages broken down by all the individual pages used to compose the final page. (You must restart ColdFusion Server in order for changes to this setting to take effect.)

This feature will work identically on all platforms.

New SetDomainCookies attribute for CFAPPLICATION

The SetDomainCookies attribute allows applications to set the CFID and CFTOKEN cookies on the domain (i.e., .allaire.com) level, which is what you need to do to share client variables in a cluster.

Usage: SetDomainCookies="Yes/No"

There are some caveats to using this.

• If a client has existing host level ID/TOKEN cookies, these cookies are 'migrated' to the Domain level. The host level cookies are unset, and their values are moved to the domain level cookies.
• There is a new cookie set at the domain level: CFMAGIC. This cookie is what tells ColdFusion that the domain cookies have been set. It is non-determinate which cookies CF will use given both a domain and host level cookie.

  The CFMAGIC cookie contains the ID and token values, and if these don't agree with the values in the cookies, it assumes these are host level cookies, removes them, and sets the domain level cookies to be the values provided in the CFMAGIC value.

Locking enhancements

Data stored in Server, Application and Session scopes ("shared data scopes") is persistent across browser requests and multiple requests can access the data. Unlocked access to data by multiple requests at the same time can corrupt the data. CF 4.0 introduced the CFLOCK tag to control simultaneous access to the shared data in these scopes.

ColdFusion 4.5 will provide more automatic means to protect shared data from incorrect access.

For each of the Server, Application and Session scopes, the ColdFusion Administrator provides three choices for control - none, full checking, and automatic locking of read accesses.

Choosing "none" retains current ColdFusion behavior. All reads and writes of data must be protected by a CFLOCK tag. No automatic protection is provided and unprotected accesses may cause corruption of data.

Choosing "full checking" will cause ColdFusion to raise an error if any read or write of data in one of the scopes occurs outside of the scope of a CFLOCK. This includes accesses to any data that is aliased by being assigned to a variable outside of the shared data scopes and the data is not copied; this can occur for struct and query variables. An alias example:

<CFLOCK type="EXCLUSIVE" scope="Session" timeout="10">
<CFSet Session.var = StructNew() >
<CFSet myvar = Session.myvar>
</CFLOCK>
<CFSet myvar2 = myvar>  <!--- unprotected access to alias --->

Choosing "automatic read locking" will cause ColdFusion to raise errors for unprotected writes, but unprotected reads will be automatically locked.

For Session scope, an additional choice is provided. This is to single thread session requests. This means that all requests from the same session will occur sequentially, each request waiting for all previous requests to finish before proceeding, preventing multiple requests from simultaneously accessing shared data.

New CFIMPERSONATE tag

Allows you to impersonate a user defined in a security context defined in Advanced Security. The ColdFusion Application Server enforces all the privileges and restrictions that have been set up for that user with the Advanced Security rules.

Syntax

<CFIMPERSONATE SECURITYCONTEXT="SecurityContext"
	USERNAME="Name"
	PASSWORD="Password"
	TYPE="CF" or "OS"
>
	...
	HTML or CFML code to execute
 	...
</CFIMPERSONATE>

USERNAME

Required. The user name of the user you want to impersonate. This can be done using the ColdFusion Advanced Security Administrator.

PASSWORD

Required. The password of the user that you want to impersonate.

SECURITYCONTEXT

Required. The security context in which the user should be authenticated. If the impersonation type is "CF " then you should specify a Security Context that has already been defined using the ColdFusion Advanced Security Administrator. Since Advanced Security is only available on ColdFusion Enterprise, you can use an impersonation type of "CF " only if you have the ColdFusion Enterprise version.

TYPE

Required. The type of impersonation needed. This attribute can have the value – "CF " for impersonation at the application user level.

See the CFML Language Reference for more information.

Enhancements to CFLDAP

The CFLDAP tag has been enhanced as follows:

• The MODIFYTYPE attribute now supports "Delete" in addition to "Add" and "Replace."
• A new SEPARATOR attribute has been added for specifying the separator used between multi-value attributes.

See also the section describing new CFLDAP attributes.

ColdFusion Server Probe

ClusterCATS provides a probe that gives the ability to periodically "test" a user defined ColdFusion URL; It also lets you verify the correctness of the returned content. Correctness is verified by comparing the content returned from the get with a user-specified string. If the URL fails, times out, or the user supplied string was not returned in the page accessed, ClusterCATS restricts a Web Server specified by the administrator. ClusterCATS will also optionally restart ColdFusion Server on failure. The Web server will become available as soon as the probe returns a successful value. ClusterCATS refers to this feature as the CF Probe.

In the event that a ColdFusion application probe fails, the application monitor window in the ClusterCATS Explorer will have a red circle on it. Select the Application Monitor icon to determine which Cluster Members the CF Probes failed on.

Expanded Exception Handling

Organize custom exception types

ColdFusion 4.0.1 introduced custom exception types, such as <CFTHROW TYPE="MyApp.BusinessRuleException.InvalidAccount">. ColdFusion 4.5 will find a catch handler using the custom type as a pattern.
For example,

<CFTHROW TYPE="MyApp.BusinessRuleException.InvalidAccount">

<CFCATCH TYPE=" MyApp.BusinessRuleException.InvalidAccount">
<"CFCATCH TYPE=" MyApp.BusinessRuleException">
<"CFCATCH TYPE=" MyApp">

The search always begins with the most specific type and proceeds to the least specific type; the order in which the <CFCATCH> tags are coded within a given page does not matter.

This feature creates an incompatibility with CF 4.0.1, where <CFTHROW TYPE="MyApp.foo"> could only be caught by <CFCATCH TYPE="MyApp.foo">, never by <CFCATCH TYPE="MyApp">. The ColdFusion Administrator will supply a setting to revert to 4.0.1 behavior and a request can override this behavior by a new <CFSETTING> attribute: <CFSETTING CATCHEXCEPTIONSBYPATTERN=yes/no>.

CFHTTP Enhancements

The following changes have been made to CFHTTP:

• There is a new CFHTTP variable, CFHTTP.Header, which returns the raw response header from the server.
• The variable CFHTTP.Response_Header has been renamed, and is now CFHTTP.ResponseHeader. CFHTTP.ResponseHeader now supports arrays in the structure to allow for more than one instance of the header key.
• Secure Socket Layer (SSL) is now supported on Unix.

New CFHTTP attributes

• PROXYPORT - Optional. The port number on the proxy server from which the object is being requested. Default is 80. When used with RESOLVEURL, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document.
• USERAGENT - Optional. User agent request header.
• THROWONERROR - Optional. Boolean indicating whether to throw an exception that can be caught by using the CFTRY and CFCATCH tags. The default is NO.

GET Enhancement

The ResponseHeader (formerly named Response_Header) variable is a CFML structure; it allows you to see the response headers.

#CFHTTP.ResponseHeader[http_header_key]#

Binary Data Support

ColdFusion is developing the ability to handle arbitrary, non-text data. A new core binary data type and some higher level functions have been implemented for this. We are researching additional binary features, such as BLOB manipulation in databases.

New applications are requiring the ability to manipulate binary data. For example, a customer using CFML could load a .gif image from a file using CFFILE, serialize it using WDDX, and send it to an associate, where it could be saved to disk with CFFILE.

Base 64

Base 64 provides 6 bit encoding of 8-bit ASCII characters. Because high ASCII values and binary objects are not safe for transport over internet protocols such as HTTP and SMTP, ColdFusion offers Base64 as a means to safely send ASCII and binary data over these protocols. Base 64 allows you to store binary objects in a database if you convert the data into Base 64 first. If you receive data in Base 64, you can re-create the actual binary object that it represents, such as a .gif , .jpeg, or executable file, by using the ToBinary function.

Specification of the new binary type:

• It is an internal type, consisting of a buffer and a length.
• It is a complex type, assigned by reference.
• It is not automatically convertible to anything.
• Nothing can be automatically converted to it.
• It can be serialized through WDDX, where it is converted to a base64 representation, which consists of printable characters.
• A WDDX binary deserialization, or tobinary() function call will create a binary object.

New Functions

• IsBinary - Returns TRUE if value is binary; otherwise, the function returns FALSE.
  Syntax:
  

  IsBinary(value)

• ToBase64 - Returns the Base 64 representation of the string or binary object. Base 64 is a format that uses printable characters, allowing binary data to be sent in forms and email, and stored in a database or file.
  Syntax:
  

  ToBase64(string_or_binary_object)

• ToBinary - Returns the binary representation of Base 64 encoded data. Syntax:

  ToBinary(string_in_Base64)

• Len - Returns the length of the binary buffer. Syntax:

  Len(string)

Modifications to CFFILE:

• Modification: ACTION 'WRITE', attribute 'output': ACTION 'Write' has been modified to allow attribute output to be either a Typeless type (text), or a Binary object (binary).
• New ACTION: 'ReadBinary': Action ReadBinary allows for data to be read from an arbitrary file into a Binary object. In all other aspects it is identical to Read.

<cffile action="Write" file="c:\logo.jpg" output=#jpegvar#>

<cffile action="ReadBinary" file="c:\cfusion\bin\cfserver.exe" variable=binaryobj>

This will actually read the entire ColdFusion executable into a binary object. Then the function toBase64(binaryobj) could be used to create a base64 representation of the cfserver.exe file.

Alternatively, cfserver.exe could then be serialized using WDDX.

Modifications to WDDX

WDDX can now serialize binary data using a new <binary> tag. By default, the CDATA of this tag will contain the base64 representation of the binary data being serialized.

<binary> (attributes)>ENCODED_DATA</binary>

• length: length of encoded data
• encoding: encoding type for ENCODED_DATA. 'base64' is the default.

Serialization and deserialization methods for all implementations of WDDX will eventually support this tag. A new object will be added to the JavaScript entry: function WddxBase64(initData, initLen), which holds a base64 representation of the data of a <binary> tag. This object is serializable.

<binary length='43'>MIIBAJELVJETELSJAMJjDGjdjgEUUEGSDKEHWEQI==</binary>

New CFLDAP Attributes

Attribute	Descriptiion
FILTERFILE	A multi-field string containing the path to a file containing LDAP filter string specifications and the name of the "stanza" within that file. The format of the FILTERFILE attribute is FILTERFILE=<filename>,<tag>. Where filename is an absolute path or a simple filename to the filter file to use and tag is the "stanza tag" for a section of that filter file. If a simple filename is used it is assumed to be relative to the "ldap" subdirectory of your ColdFusion installation.
MODIFYTYPE	Supports appending attributes to existing multi-valued attributes. Valid entries: REPLACE (default), ADD. ADD appends the new attribute to any existing attributes. Using the new ADD mode introduces the following LDAP limitations: You can't do an ADD of values that already exist. You can't do an ADD of null values.
REBIND	Values: NO (default), YES. If set to YES we would try to "rebind" the referral callback and reissue the query (via the referred address) using the original credentials. If NO, credentials are lost in referrals so referrals bindings are anonymous.
REFERRAL	This optional attribute controls The number of "hops" allowed in a referral. Valid values for this attribute should be integer values >= 0. If set to 0, this effectively turns off referrals. In this case, no data is returned for entries that are referrals (not even whatever attributes may be in the "local" entry.)
SECURE	Establish the LDAP connection via SSL (thereby hiding the connection password otherwise sent as text.) The value of this attribute is a multi-field string. The fields of the string have the following values: SECURE = "cf_security_typeid [, posible_additional_fields]" The cf_security_typeid is a string that identifies the type of security to empploy. We currently support two types (the Netscape implementations of type 2 and type 3 SSL) so the string must have one of the following values: "CFSSL_BASIC" or "CFSSL_CLIENT_AUTH" The subsequent fields in the string differ depending on which type is in use. Their layouts are: SECURE="CFSSL_BASIC,certificate_db" SECURE="CFSSL_CLIENT_AUTH,certificate_db,certificate_name,key_db,key_password" The fields have the following values: cf_security_typeid Id string indicating the CF security implementation type certificate_db The name of the certificate database file (in Netscape cert7.db format.) cerificate_name The name of the client certificate to send the server. key_db Keyword database holding the public/private key-pair (in Netscape key3.db format.) keyword_db The password to key data base. Examples (using Windows paths): SECURE="CFSSL_BASIC,C:\temp\cert7.db" SECURE="CFSSL_CLIENT_AUTH,C:\temp\cert7.db,Server-Cert,   C:\temp\key3.db,admin0828"

Data Source Disable

The CF Administrator can now disable individual data source connections. In previous releases, the ColdFusion server had to be stopped to do administrative work on a database accessible from ColdFusion. This was necessary to ensure that all pending transactions had been completed and that no new ones would be allowed to start on either new or reused database connections for that data source.

The disable feature is part of the CFSettings on the Data Source page. A Disable database connections checkbox has been added to the page. The attribute will not be checked by default. When the attribute is checked then ColdFusion will no longer allow new connections to be established to the data source. In addition, any existing connections that are not in use will be disconnected and cleaned up, and any connections currently in use will be notified that they are to clean themselves up as soon as their current transaction has been completed. Connections may be reinstated by unchecking the checkbox after the administrative tasks have been completed.

CFQUERYPARAM

This new tag adds SQL bind parameter support to CFQUERY. The tag is coded inline in the SQL statement, so it is very easy to use. It was developed to improve performance, maintenance, and security of data queries, specifically:

• Server-side caching for Oracle is enhanced and work toward active SQL statement caching by ColdFusion has begun.
• Long text fields can be updated from a SQL statement. In previous releases, the developer was required to use a form and the CFINSERT and CFUPDATE tags to do this.
• A malicious user can no longer attach multiple SQL statements to a SQL statement substitution variable.

If the CFQUERY data source does not support bind parameters, then ColdFusion will execute the SQL statement with the substituted parameters for CFINSERT, CFUPDATE and CFGRIDUPDATE as in previous releases. For example, the Sybase native driver does not support query parameters, so the parameters are substituted into the SQL string. As a result, a ColdFusion developer wishing to take advantage of SQL bind parameters does not have to write one set of statements for the data sources that support it and another set for data sources that don't.

ColdFusion developers should be aware of the security implications of this feature and use best security practices. In the case of a database that does not support query parameters, the validated parameter value is substituted back into the SQL string - character data is enclosed in single quotes by ColdFusion when it is substituted back into the string. Numeric and date data types are validated to ensure that the data value can be converted to numeric data or a date respectively. Character and other data types are checked to make sure the value does not exceed the MAXLENGTH for the parameter, if it is specified.

At present, the ColdFusion Sybase11 driver does not support SQL bind parameters because the Sybase client libraries do not provide that support. The OLEDB driver dynamically determines support. The ColdFusion ODBC, DB2, Informix, Oracle 7 and Oracle 8 drivers support SQL bind parameters.

For example:

<CFQUERY Name="foo" DataSource="MyDSN">
SELECT * FROM courses 
WHERE course_id = <CFQUERYPARAM Value=#id# 
CFSQLTYPE=CF_SQL_INTEGER>
</CFQUERY>

The CFSQLTYPE attribute is needed for the CFDATAACCESS bind calls. The data conversions are actually done by the database client software, which doesn't necessarily know the target data type. The CFINSERT and CFUPDATE tags determine this information by accessing the database catalog for the target table. This is not an option for CFQUERY since it has no information concerning what the target tables or columns are. The database APIs for ODBC and Oracle support discovery of the param types, however, for ODBC this a level 2 feature and not supported by many ODBC drivers. The param type discovery is expensive. Given the expense of the runtime determination of the param type and the fact that it would limit the param support to fewer ODBC we should use the CFSQLTYPE param in the tag.

CFSQLTYPE also enables data validation. Developers can do less validation coding since the CFQUERYPARAM values are validated. Three optional parameters - MAXLENGTH, Scale, and Null are available for decimal data types. If the data source does not support bind parameters the the ColdFusion SQL executor uses CFSQLTYPE to determine if it needs to enclose the substituted value in single quotes.

Expanded CFQUERY Text Field Support

This release removes the 65K limit on the retrieval of text or long varchar database fields. The interface provides new data source settings in the ColdFusion Administrator; it does not require new CFML tags or tag attributes. For backward compatibility, the new field size is implemented so that existing applications can continue to work as they did in 4.0.

This feature is very useful if you have large text fields and know the limits of the text column. For example, an Oracle database may use text fields but limits the input for each occurrence to 256k. By setting the Long Text Buffer Size to 256000, the entire text field can be efficiently returned in a bound column. If you only want the first 1K characters from the long text columns, you could set the Long Text Buffer Size to 1028, making more efficient use of memory to retrieve bound data. This is an important consideration for limiting your bound long text data, since many databases do not support the substring functions for this data type.

Coding considerations

If you have a limited number of cases in which you want to retrieve complete long text data, then you should create a data source definition Enable retrieval of long text checked with specifically for this so you will not incur the overhead of retrieving large amounts of data when this is no intended. Retrieving unbound data is much slower than bound data, so you should order the columns in your select statement with the text fields referenced last.

The statement

SELECT integer_col, char_col, date_col, long_text_col
FROM data_table 

SELECT long_text_col, integer_col, char_col
FROM data_table.  

because in the first statement only the long_text_col is retrieved as unbound data and the other columns are retrieved as bound data, while in the second statement all the columns are retrieved as unbound data.

Data Source Transaction Support

Current transaction support is by the CFTRANSACTION tag. The transaction begins at the first CFML tag after the CFTRANSACTION tag that requires a data source. All subsequent CFML tags contained in the CFTRANSACTION block must use the same data source. An error is thrown if a different data source is specified. When the </CFTRANSACTION> is executed, the database transaction is committed and the transaction mode is ended. If a database action returns an error or the end of page processing finds an open database transaction, then the transaction is rolled back and the transaction mode is ended.

We now provide more control over commit/rollback behavior through the ACTION attribute of the CFTRANSACTION tag. The ACTION="BEGIN" value is equivalent to the 3.x and 4.x CFTRANSACTION behavior when no ACTION attribute was supported, so all 3.x and 4.x CFTRANSACTION code is upwardly compatible.

ACTION="BEGIN" (default) 
ACTION="COMMIT"
ACTION="ROLLBACK"

• The COMMIT and ROLLBACK attribute values require an "/>" tag suffix to handle nesting correctly.
• A CFTRANSACTION tag that specifies ACTION=COMMIT or ROLLBACK must be nested in a <CFTRANSACTION></CFTRANSACTION block>.

<!--- Turn on the database transaction processing, a transaction is started when the first --->
<!--- CFML tag which connects to a database is executed.  The ISOLATION attribute is  --->
<!--- optional.  A <CFTRANSACTION> tag  that does not specify an ACTION must have  --->
<!--- some content otherwise a Tag error is thrown when the template is prepared. This  --->
<!--- 3.x, 4.0 behavior.  --->


<CFTRANSACTION  ACTION="BEGIN" ISOLATION="REPEATABLE_READ"> 

<CFLOOP INDEX="loopcount" FROM="1" TO="12">
	<CFQUERY NAME="INSERTFOO" DATASOURCE="mydb">
	insert into foo values (#loopcount#, 'Joe', 'Smith')
	</CFQUERY>
	<CFIF (loopcount mod 5) is 0 >

<!--- After every 5 rows, commit the transaction and leave transaction processing on.  After  --->
<!--- commit another transaction is started when a CFML tag which connects to a database is --->
<!--- executed.  The ISOLATION attribute is optional.  If an ISOLATION value is not     --->
<!--- provided then the ISOLATION value for the parent <CFTRANSACTION> is used.     --->
<!--- A <CFTRANSACTION> tag that specifies an ACTION must have parent --->
<!--- <CFTRANSACTION> tag and must have no content(<CFTRANSACTION ACTION… />) --->
<!--- otherwise a Tag error is thrown when the template is prepared. --->


	     <CFTRANSACTION ACTION="COMMIT" ISOLATION="READ_UNCOMMITTED"/> 
	</CFIF>	
</CFLOOP>


<!--- Implicit Commit of database transaction and end the database transaction processing. --->
<!--- In this example the 11th and 12th rows that were inserted would still be part of a pending  --->
<!--- transaction and would be committed.  If a runtime error occurred and the   --->
 </CFTRANSACTION> end tag not executed then a pending database transaction would be  --->
<!--- rolled back. This  3.x, 4.0 behavior.  --->

</CFTRANSACTION>

By using CFML error handling with the ACTION attribute, you can have complete control over ending your transactions with either a COMMIT or ROLLBACK and simplify your code. In the 4.0 release, if you wanted all data base activity on a cfm page to be executed in transaction mode you had to use the following style:

<!--- Turn on transaction processing for the northeast db transactions  --->
<CFTRANSACTION> 

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_northeast">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_northeast">
	insert into orders values (………)
	</CFQUERY>


<!--- End database transaction processing which commits pending transaction --->
</CFTRANSACTION>

<!--- Turn on transaction processing for  the southeast db transactions  --->
<CFTRANSACTION> 

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_southeast">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_southeast">
	insert into orders values (………)
	</CFQUERY>


<!--- End database transaction processing which commits pending transaction --->
</CFTRANSACTION>

<!--- Turn on transaction processing for  the midwest db transactions  --->
<CFTRANSACTION> 

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_midwest">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_midwest">
	insert into orders values (………)
	</CFQUERY>


<!--- End database transaction processing which commits pending transaction --->
</CFTRANSACTION>

<!--- Turn on transaction processing for the …… db transactions  --->
<CFTRANSACTION> 

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_……">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_…….">
	insert into orders values (………)
	</CFQUERY>


<!--- End database transaction processing which commits pending transaction --->
</CFTRANSACTION>

Using the new ACTION attribute this code can be simplified as follows:

<!--- Turn on the database transaction processing once for the template --->

<!--- Do the northest db transactions
<CFTRANSACTION> 

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_northeast">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_northeast">
	insert into orders values (………)
	</CFQUERY>


<!--- commits pending transaction --->
<CFTRANSACTION ACTION="COMMIT">

<!--- Do the southeast db transactions

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_southeast">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_southeast">
	insert into orders values (………)
	</CFQUERY>


<!--- commits pending transaction --->
<CFTRANSACTION ACTION="COMMIT">

<!--- Do the midwest db transactions

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_midwest">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_midwest">
	insert into orders values (………)
	</CFQUERY>


<!--- commits pending transaction --->
<CFTRANSACTION ACTION="COMMIT">

<!--- Do the …… db transactions

	<CFQUERY NAME="INSERTCUSTOMER" DATASOURCE="mydb_……">
	insert into customer values (……..)
	</CFQUERY>

	<CFQUERY NAME="INSERTORDER" DATASOURCE="mydb_…….">
	insert into orders values (………)
	</CFQUERY>

<!--- commits pending transaction --->
<CFTRANSACTION ACTION="COMMIT">

<!--- End database transaction processing which commits pending transaction --->
</CFTRANSACTION>

Request Tracker

Memory corruption bugs sometimes leave a server in an unusable state: it is still alive, and its threads accept requests, but the requests always end with "unexpected exception" errors. The Request Tracker allows the CF Administrator to specify a minimum percentage of successful -vs- unsuccessful requests.

This facility will log all requests, and monitor the presence of "unexpected exception" type error traps. A request that triggers such an error trap will be considered "unsuccessful." When the percentage of unsuccessful requests rises above the specified percentage threshold, the Request Tracker will terminate the CFAS process. The service is restarted if abnormal requests occur on a regular basis.

The Request Tracker is enabled by default on the *** page of the CF Administrator. The threshold percentage of successful requests will be set at 90%, and the number of requests will be set at 30. The "90% of 30" is a standard statistical measurement of confidence in a particular hypothesis, in this case, that the CFAS process is not corrupted.

The Request Tracker parameters can also be tuned via the Registry. The parameters of interest are RequestTrackerSampleSize and RequestTrackerThresholdPercentage.

CFPROCESSINGDIRECTIVE

This much-requested feature allows you to specify a p-code compiler processing option - SuppressWhitespace=bool - to suppress extraneous whitespace (or all output) produced by the CFML within the tag's scope.

Nesting behavior

If a CFPROCESSINGDIRECTIVE tag's scope includes another CFPROCESSINGDIRECTIVE tag, then the inner tag's settings override the enclosing tag's settings within the body of the inner tag, where they differ. If the enclosing tag specifies settings that the inner tag does not, those settings remain in effect within the inner tag's scope.

Usage

CFPROCESSINGDIRECTIVE settings do not apply to templates included via CFINCLUDE, CFMODULE, custom tag invocation, etc.

Example

This example shows the use of a nested <CFPROCESSINGDIRECTIVE> tag. The outer <CFPROCESSINGDIRECTIVE> tag will suppress unnecessary whitespace during computation of a large table while the inner <CFPROCESSINGDIRECTIVE> tag honors all whitespace to output the preformatted table.

<CFPROCESSINGDIRECTIVE SUPPRESSWHITESPACE="yes">
… any CFML tags here …
<CFPROCESSINGDIRECTIVE SUPPRESSWHITESPACE="no">
<cfoutput>#interesting stuff#</cfoutput>
</CFPROCESSINGDIRECTIVE>
</CFPROCESSINGDIRECTIVE>

Variable Scope Enhancements

URL, CGI, FORM, and Cookie variables can now be accessed through structure objects with the same names. These names are now reserved for use by CFML. This enhancement makes these scopes behave the same as application, session, and request.

This has not been done with the Server scope partially for security reasons - so that server variables whose names are unknown cannot be accessed. It has also not been done with the Client scope because of the performance implications of having to enumerate all persistent variable names.

Note that customer applications using these variable names for other purposes will most likely break in 4.5.

CFMAIL Enhancements

New BCC Attribute

BCC allows you to send a message to one or more email addresses without listing them in any message header. Contrast this with the CC attribute which displays "carbon copy" recipients in a message header.

New CFMAILPARAM Tag

The CFMAILPARAM tag can be used between the begin and end tags of CFMAIL. Zero or more CFMAILPARAM tags may appear inside CFMAIL. The CFMAILPARAM tag allows the CFML developer to do either one of two things:

1. Use the File attribute to attach files

or

2. Use the Name and Value attribute to add headers.

Attaching Files with CFMAILPARAM

To attach a file, use CFMAILPARAM with its File attribute. The File attribute must specify a valid file path. For example, this snippet sends a message with two attachments:

CFMAIL From="peter@domain.com" To="paul@domain.com" Subject="attachment test">
    This message has two attachments.
    <CFMAILPARAM File="c:\work\readme.txt">
    <CFMAILPARAM File="c:\work\logo.gif">
</CFMAIL>

Adding Headers with CFMAILPARAM

To add a message header, use CFMAILPARAM with its Name and Value attributes. The Name attribute cannot specify an empty string. Header names are case-insensitive (i.e., "Reply-To" is identical to "REPLY-to"). A header overwrites any previous entry with the same name. This snippet illustrates sending a message with a "Reply-To" header:

<CFMAIL From="peter@domain.com" To="paul@domain.com" Subject="header test">
    <CFMAILPARAM Name="Reply-To" Value="mary@domain.com">
    This message has a Reply-To header that is honored by many e-mail client applications.
</CFMAIL>

New CFPOP attribute

CFPOP now has a new attribute called GenerateUniqueFilenames. This attribute can either be true or false and it indicates whether the user wants the files attached to an email to be saved using a generated filename to prevent name conflicts and overwrites if an email has an attachment with two files that are similarly named, or whether the user wants the file to be saved using the name specified in the mail header.

For example, if this attribute is yes and a mail message has three files called foo.exe, bar.txt and bar.txt they will be saved to disk as 12.exe, 13.txt and 14.txt. The filenames are guaranteed to be unique within the specified directory.

Oracle Reference Cursor Support

This release supports the return of result sets via Oracle Reference Cursors through the Oracle 8 native driver and the ColdFusion stored procedure interface.

The example below shows both the PL/SQL necessary for creating a procedure to return a result set and the CFML necessary for executing the procedure in ColdFusion. The example uses the Oracle SCOTT/TIGER login sample data. The final ColdFusion documentation for this release will contain additional information and examples.

CREATE OR REPLACE PACKAGE dept_data AS

	TYPE DeptTyp IS REF CURSOR RETURN dept%ROWTYPE;

	PROCEDURE refcurproc(pParam1 in out DeptTyp);

END dept_data;

CREATE OR REPLACE PACKAGE BODY dept_data AS

	PROCEDURE refcurproc(pParam1 in out deptTyp) IS

	BEGIN

		OPEN pParam1 FOR select * from dept;

	END refcurproc;

end dept_data;

<cfstoredproc	procedure="dept_data.refcurproc"
				datasource="my_oracle80_test" 
				username = scott
				password = tiger
				RETURNCODE="no"
>

<cfprocparam type="Out" cfsqltype="CF_SQL_REFCURSOR" variable="param1">

<cfprocresult 	name = rs1>

</cfstoredproc>

<b>The first result set:</b><br>
<hr>
<cfoutput query = rs1>
#dname#,#deptno#
</cfoutput>

<CFTHROW TYPE="MyApp.BusinessRuleException.InvalidAccount">

<CFCATCH TYPE=" MyApp.BusinessRuleException.InvalidAccount">
<"CFCATCH TYPE=" MyApp.BusinessRuleException">
<"CFCATCH TYPE=" MyApp">

<CFOBJECT Type=Java  Class=MyClass Name = myObj>

<CFSET ret = myObj.init(arg1, arg2)>

<cfobject action=create 
			type=JAVA
			class="weblogic/jndi/Environment"
			 name=wlEnv>

<CFSET ctx = wlEnv.getInitialContext()>

<CFSET ejbHome = ctx.lookup("statelessSession.TraderHome")>			 

<CFSET trader = ejbHome.Create()> 

<CFSET value = trader.shareValue(20, 55.45)>	 

<CFOUTPUT>
	 Share value = #value#
</cfoutput>	 

<CFSET value = trader.remove()>	 

ClusterCATS Cisco Local Director integration

ClusterCATS is now able to provide the availability and load balancing to Cisco Local Director so that the Local Director can route inbound HTTP traffic to the most appropriate web server in your cluster.

Combining ClusterCATS and Local Director provides a powerful load balancing solution that Local Director cannot provide without ClusterCATS. Local Director cannot detect how busy a ColdFusion Server is. It therefore would continue to send new requests to a web server even if ColdFusion is too busy to handle additional requests.

ClusterCATS can detect if ColdFusion is to busy to handle additional requests because it can interpret the ColdFusion load metric. Consequently, its built-in intelligence can override the regular distribution sequence of the router, and it can redirect new requests to other available servers in the cluster. So, it not only load balances, but it also provides important ColdFusion Server availability data as well.

Back to top