TM BlueDragon 6.
NEW ATLANTA COMMUNICATIONS, LLC BlueDragon™ 6.1 CFML Compatibility and Reference Guide June 17, 2004 Version 6.1 Copyright © 1997-2004 New Atlanta Communications, LLC. All rights reserved. 100 Prospect Place • Alpharetta, Georgia 30005-5445 Phone 678.256.3011 • Fax 678.256.3012 http://www.newatlanta.com BlueDragon is a trademark of New Atlanta Communications, LLC. ServletExec and JTurbo are registered trademarks of New Atlanta Communications, LLC in the United States.
Contents 1 INTRODUCTION ...........................................................................................1 1.1 About This Manual................................................................................................................................. 1 1.2 BlueDragon Product Configurations .................................................................................................... 1 1.3 Technical Support .............................................................................
.3.17 4.3.18 4.3.19 4.3.20 4.3.21 4.3.22 4.3.23 4.3.24 4.3.25 4.3.26 4.3.27 4.3.28 4.3.29 4.3.30 4.3.31 4.3.32 CFLDAP.................................................................................................................................... 11 CFMAIL.................................................................................................................................... 11 CFMAILPARAM........................................................................................................
.3.1 5.3.2 5.3.3 5.3.4 5.3.5 ListToArray............................................................................................................................... 34 ParagraphFormat ....................................................................................................................... 35 XMLSearch ............................................................................................................................... 35 XMLParse ..................................................
BlueDragon 6.1 CFML Compatibility and Reference Guide 1 Introduction N ew Atlanta BlueDragon is family of server-based products for the deployment of ColdFusion® Markup Language (CFML) applications for dynamic web publishing—featuring native technology platform integration on the operating system, web server, and database of your choice. CFML is a popular server-side, template-based markup language that boasts a rich feature set and renowned ease-of-use.
Details regarding paid support options, including online-, telephone-, and pager-based support are available from the New Atlanta web site: http://www.newatlanta.com/biz/support/index.jsp 1.4 Other Documentation The other manuals available in the BlueDragon documentation library are: • BlueDragon 6.1 Installation Guide • BlueDragon 6.
2.2 Migration from ColdFusion to BlueDragon While this document covers issues of CFML language compatibility, additional information about migration from ColdFusion to BlueDragon is provided in the BlueDragon User Guide, in the Section “Migration from ColdFusion”. Developers are strongly encouraged to review that material, and indeed all the information presented in the User Guide. 2.
#url.mod# The error occurs on the CFOUTPUT, rather than the CFSET. Similarly, ColdFusion will allow you to create and use a variable named var (which is a keyword used within CFSCRIPT and CFSET), but BlueDragon will not. It also fails when you try to CFOUTPUT. So it’s not that you can never use keywords, just that you can’t always use them the same way as in ColdFusion (and there’s no reliable documentation of how reserve words can or cannot be used).
3.4 SERVER Variables For BlueDragon, the variable Server.ColdFusion.ProductName returns the value “BlueDragon” and Server.ColdFusion.ProductLevel returns a value indicating the BlueDragon product installed (such as “Server JX”). For BlueDragon 6.1, the ProductVersion variable returns the value "6,1,0,xxx" where "xxx" is the internal build number; for example: 6,1,0,237. BlueDragon also offers its own scope, Server.BlueDragon, with the following variables: Server.BlueDragon.
New CFID/CFTOKEN values are assigned only when a client/browser executes a CFML page for the first time without those cookies already set. 3.7 Client Variable Processing There are some differences between BlueDragon and ColdFusion in the underlying implementation of client variable processing with regard to using a database to store the client variables. First, where ColdFusion requires an administrator to configure a datasource to serve as a client variable repository, BlueDragon does not.
4 CFML Tags 4.1 ColdFusion Components There are a few differences in CFC (ColdFusion Component) processing in BlueDragon, including both enhancements and limitations, and with respect to their use as web services. The following sections discuss these. 4.1.1 CFC Enhancements in BlueDragon BlueDragon adds the following enhancements when working with CFCs: • CFC instances can be duplicated using the Duplicate() function.
4.1.2.
The following tags added in CFMX are not supported by BlueDragon, and will generate run-time errors when processed by BlueDragon: Unsupported CFMX Tags CFCHART CFLOGIN CFCHARTDATA CFLOGINUSER CFCHARTSERIES CFLOGOUT CFTRACE 4.3 Supported with Limitations The following CFML tags are supported by BlueDragon with differences and limitations relative to the CFMX implementation as noted; tags are listed alphabetically. 4.3.
4.3.6 CFCONTENT BlueDragon does not support using a pair of CFCONTENT tags, as in: some data. In BlueDragon, only the opening CFCONTENT tag is supported. 4.3.7 CFDUMP BlueDragon currently ignores the EXPAND and LABEL attributes available in ColdFusion. 4.3.8 CFERROR In ColdFusion, when a CFERROR uses TYPE=”Request”, the page can list variables in the Error scope without need of a CFOUTPUT.
4.3.13 CFHTTPPARAM BlueDragon does not support the following new type attribute values introduced in CFMX 6.1: header and body. 4.3.14 CFIMPORT While BlueDragon supports use of CFIMPORT as an alternative approach to executing CFML custom tags (as introduced in CFMX), it does not support the ability to import or execute JSP custom tag libraries. 4.3.
current template directory. The filename match is not case-sensitive when searching custom tag directories. 4.3.21 CFOBJECT BlueDragon supports “java”, “component”, and “webservice” values for the type attribute; it does not support the values “com” or “corba”. 4.3.22 CFQUERY 4.3.22.1 Unsupported Tag Attributes CF5 added a feature often referred to as “DSN-less” connections (where the database connection string is specified via the connectString attribute, rather than using a dataSource attribute).
4.3.24 CFSCRIPT BlueDragon does not support try/catch statements within CFSCRIPT. 4.3.25 CFSEARCH In BlueDragon, the search capability (CFSEARCH, CFINDEX, and CFCOLLECTION tags) is based on the Jakarta Lucene project open source search engine, which results in differences between the BlueDragon and ColdFusion implementations.
hold the result set. The following code running on BlueDragon 6.1 returns the result set in a query variable named "myResults": In CF5, you're required to specify a "dummy" OUT parameter and then use CFPROCRESULT to create a variable to hold the actual result set.
4.3.31 CFUPDATE Like CFMX, BlueDragon does not support “DSN-less connections”; therefore, it always requires the dataSource attribute and does not support the following optional attributes: connectString dbName dbServer dbType provider providerDSN See the discussion of CFQUERY attribute support in Section 4.3.22 for more information. 4.3.32 CFWDDX The following limitations exist in the BlueDragon implementation of the CFWDDX tag relative to the ColdFusion implementation: 1.
4.4.2 CFCONTENT Both ColdFusion and BlueDragon support an available FILE attribute for CFCONTENT, to name a file whose content should be sent to the browser (with its mime type optionally indicated with the available TYPE attribute). BlueDragon takes this a step further and lets you send the value of a variable, using a new OUTPUT attribute. An example of using it might be when a CFQUERY retrieves a column of binary type from a database (perhaps a graphic). Assuming the variable is myquery.
does not affect query resultsets or XML documents that are contained within another variable or structure being dumped. 4.4.4 CFFLUSH BlueDragon 6.1 offers an option in the administration console to control whether the generation of HTML output on a page is buffered to page completion or not, and it now defaults to buffering the entire page, like ColdFusion. See the BlueDragon User Guide for more information on the topic of page buffering.
The CFINCLUDE PAGE attribute can be used to include CFML pages, in which case the included page’s Application.cfm (and any OnRequestEnd.cfm) will be processed, unlike a typical CFINCLUDE TEMPLATE. This behavior is the same as using GetPagecontext().include() function. 4.4.6 CFINDEX 4.4.6.1 Spidering a Web Site BlueDragon now adds the ability to index/spider the web pages of a web site. CFINDEX has traditionally been used to index the content of files within a file system.
4.4.6.2 Wait Processing Index creation (spidering a web site or indexing a file collection) can take a long time, so BlueDragon adds an optional WAIT attribute to CFINDEX, which takes a boolean value (such as true or false) that defaults to true (or yes). If WAIT is true, processing of your CFML page will wait until the indexing operation is completed.
4.4.10 CFPROCESSINGDIRECTIVE SuppressWhiteSpace Attribute The CFPROCESSINGDIRECTIVE tag in CFML was introduced in CF5 with an available SuppressWhiteSpace attribute to control the creation of extra whitespace characters. It is designed to be used as a tag pair, affecting all code executed within the tag pair. BlueDragon supports this tag with the following extended capabilities.
WHERE LastName = ‘#EmployeeName#’ If you have code where this behavior is undesirable, you can change it with the available PreserveSingleQuotes() function, which when used against a variable within a CFQUERY will stop the automatic escaping of quotes. For example, consider an instance when a variable used in SQL (such as an incoming form field or other variable) may have a list of values presented as a single-quote delimited list.
All CFQUERY cached results can be cleared using a singe tag: A CFQUERY tag that uses the action attribute to flush a cache can appear on the same or a different CFML page from the CFQUERY tag that defines the cache. BlueDragon also supports the CFObjectCache tag introduced in CF5, used to clear all cached queries, and it adds a new attribute (CacheDomain) for controlling cache clearing on multiple servers.
Specifying file attributes as relative URI paths improves the portability of CFML pages by eliminating web server and operating system specific physical path specifications. Note in the above example that the first tag is not portable to a Linux running Apache, but the second one is. The optional URIDirectory attribute accepts the values “Yes” and “No”; the default value is “No”.
Execution of CFASSERT (and the assert() function) is controlled by the “Enable Assertions” setting on the “Debug Settings” page of the BlueDragon Administration console. After changing this setting, you must restart the server. If the “Enable Assertions” option is checked, then CFASSERT tags and assert() functions are enabled, otherwise they are not and are simply ignored when encountered.
4.5.4 CFDEBUGGER CFDEBUGGER is a CFML tag introduced by BlueDragon that adds a powerful new weapon in CFML debugging. In simple terms, it writes a trace to a log file indicating each CFML line of code that's been executed. Consider the following simplified example of its use: This two-line template will create an entry in a file named trace.
CFFORWARD has a single attribute, page, which specifies the URI of the target page. Paths that start with “/” start at the document root directory of the web application or web server; paths that don’t start with “/” are relative to the current CFML document: Like CFLOCATION, processing of the current page is terminated as soon as the CFFORWARD tag is executed. 4.5.
The following table lists the variables returned by the CFIMAGE tag. Variable Description CFIMAGE.SUCCESS Contains the value TRUE or FALSE to indicate whether image processing was successful. CFIMAGE.ERRORTEXT If processing was unsuccessful, contains a text message describing the error. CFIMAGE.WIDTH For ACTION=EDIT, the width in pixels of the new image. For Action=INFO, the width in pixels of the image. CFIMAGE.HEIGHT For ACTION=EDIT, the height in pixels of the new image.
1. Open a connection to the mail server (OPEN action). 2. Get a list of folders from the mail server (LISTALLFOLDERS action). 3. Get a list of messages within a specific folder (LISTMAIL action). 4. Perform actions with specific messages (READMAIL, MARKREAD, DELTEMAIL, and MOVEMAIL actions). 5. Perform actions with folders (DELETEFOLDER and RENAMEFOLDER actions). 6. Close the connection (CLOSE action). Each of these steps is described below. 4.5.7.
The folder list is returned in a Query structure with the name you specified in the NAME attribute. The fields of the Query structure are: FULLNAME – the full path to the folder (used to retrieve folder message info) NAME – shortcut name to the folder TOTALMESSAGES – total messages this folder is holding UNREAD – total unread messages in this folder NEW – total new messages in this folder The FULLNAME field is used for making subsequent calls to folders with other CFIMAP action parameters. 4.5.7.
DRAFT – boolean flag if this mail message is an unsent draft FLAGGED – boolean flag if this email has been flagged RECENT – boolean flag if this email is recent SEEN – boolean flag if this email has been seen (read) Internet email addresses are stored as structures with two fields: NAME – name of the person EMAIL – email address of the person The TO, CC, and BCC fields contain arrays of these structures. 4.5.7.
DRAFT – boolean flag if this email is a draft FLAGGED – boolean flag if this email has been flagged RECENT – boolean flag if this email is recent SEEN – boolean flag if this email has been seen BODY – array of Body structures [see below] The body of the email is treated with some consideration. Due to the various properties a MIME type email message can have, each element in the array is effectively the MIME part that was transmitted with the email.
The message list is either a single message ID or a comma-separated list of IDs. 4.5.7.9 Deleting a Folder Specifying ACTION=”DELETEFOLDER” will delete a folder from the mail server, including all of its contents (mail messages): The folder name is the complete path to the folder.
5 CFML Functions 5.1 Unsupported Functions The following CFML functions are not supported by BlueDragon: Unsupported CF5 Functions AuthenticatedContext** LSIsNumeric getK2ServerDocCount* AuthenticatedUser** LSNumberFormat getK2ServerDocCountLimit* IsAuthenticated** LSParseDateTime isK2ServerABroker* IsAuthorized** LSParseEuroCurrency isK2ServerDocCountExceeded* IsProtected** LSParseNumber isK2ServerOnLine* GetException IsNumericDate GetMetricData *deprecated in Macromedia CFMX 6.
Additionally, in both functions, the t mask returns a value of am or pm, where it should return just an a or p. 5.2.4 Decrypt/Encrypt BlueDragon does not support decryption of text that was encrypted by ColdFusion pages using their implementation of this function (such as data stored in a file or database after encryption). Conversely, text encrypted on BlueDragon cannot be decrypted in ColdFusion. As a work-around, simply re-run the process to encrypt the text. 5.2.
5.3.2 ParagraphFormat From the CFML Reference for CF5: “Returns string with converted single newline characters (CR/LF sequences) into spaces and double newline characters into HTML paragraph markers (
).” BlueDragon varies from this behavior in that it converts single newline characters into HTML break tags (
) instead of spaces. Double newline characters are converted into HTML paragraph markers (
) by both BlueDragon and CF5. 5.3.
6 Miscellaneous There are various other aspects of working with ColdFusion and CFML that may be slightly different in BlueDragon, but don’t fit neatly into a discussion of tags or functions. 6.1 Integrating JSP/Servlets Alongside CFML Templates BlueDragon Server JX and BlueDragon/J2EE both allow you to execute JSPs and servlets alongside your CFML templates. ColdFusion MX requires the Enterprise edition for the same capability. For more information on CFML/J2EE integration, see the BlueDragon User Guide.
For example, the following works in BlueDragon but fails in CFMX because the node names don't match up. myDoc.Root.SubNode = XmlElemNew(myDoc, "WrongNode") BlueDragon allows the RHS node name to take precedence. In addition, the following fails in CFMX when there is only 1 SubNode element child of Root. myDoc.Root.SubNode[2] = XmlElemNew(myDoc, "SubNode") This is allowed in BlueDragon. 6.3.
variable or other expression, since again the process of finding CFFUNCTION declarations does not happen at run time but instead in a previous step of declaration analysis. For similar reasons, BlueDragon will also not analyze a CFINCLUDE that appears inside a CFIF or indeed any other nested tag. A CFINCLUDE holding a CFFUNCTION declaration must not occur inside any nested tags. In summary, the rules for using CFINCLUDE within a CFCOMPONENT to declare component functions are: 1.
ment types. If possible, use 'javacast()' to resolve this ambiguity. Unfortunately, even use of JavaCast() won’t help here. The message also refers to other situations of ambiguity (as when multiple methods exist accepting different arguments), and in those cases JavaCast() can help. In the case of two methods of the same name (and same arguments) with only case differentiating them, there’s simply no way for BlueDragon to determine which to select.
