Creating variables

You create most ColdFusion variables by assigning them values. (You must use the ArrayNew function to create arrays.) Most commonly, you create variables by using the cfset tag. You can also use the cfparam tag, and assignment statements in CFScript. Tags that create data objects also create variables. For example, the cfquery tag creates a query object variable. ColdFusion automatically creates some variables that provide information about the results of certain tags or operations. ColdFusion also automatically generates variables in certain scopes, such as Client and Server. For information on these special variables, see CFML Reference and the documentation of the CFML tags that create these variables. ColdFusion generates an error when it tries to use a variable before it is created. This can happen, for example, when processing data from an incompletely filled form. To prevent such errors, test for the variables existence before you use it. For more information on testing for variable existence, see Ensuring variable existence on page 60. For more information on how to create variables, see Creating and using variables in scopes on page 57.

Variable naming rules

Variable names must conform to Java naming rules. When naming ColdFusion variables and form fields, follow these guidelines: A variable name must begin with a letter, underscore, or Unicode currency symbol. The initial character can by followed by any number of letters, numbers, and underscore characters. Unicode currency symbols are also allowed. A variable name cannot contain spaces. A query result is a type of variable, so it cannot have the same name as another local variable in the current ColdFusion application page. ColdFusion variables are not case-sensitive. However, consistent capitalization makes the code easier to read. When creating a form with fields that are used in a query, match form field names with the corresponding database field names. Prefix each variables name with its scope. Although some ColdFusion programmers do not use the Variables prefix for local variable names, you should use prefixes for all other scopes. Using scope prefixes makes variable names clearer and increases code efficiency. In some cases, you must prefix the scope. For more information, see About scopes on page 55. Periods separate the components of structure or object names. They also separate a variable scope from the variable name. You cannot use periods in simple variable names, with the exception of variables in the Cookie and Client scopes. For more information on using periods, see Using periods in variable references on page 45

For more information on the Arguments scope, see About the Arguments scope on page 171.
Defining functions using the cffunction tag
The cffunction and cfargument tags let you define functions in CFML without using CFScript.
Note: This chapter describes how to use the cffunction tag to define a function that is not part of a ColdFusion component. For information on ColdFusion components, see Chapter 11, Building and Using ColdFusion Components on page 217. For more information on the cffunction tag, see CFML Reference.
The cffunction tag function definition format A cffunction tag function definition has the following format:
<cffunction name="functionName" [returnType="type" roles="roleList" access="accessType" output="Boolean"]> <cfargument name="argumentName" [Type="type" required="Boolean" default="defaultValue">]. Function body code. <cfreturn expression> </cffunction>
where square brackets ([]) indicate optional arguments. You can have any number of cfargument tags. The cffunction tag specifies the name you use when you call the function. You can optionally specify other function characteristics, as described in the following table:

Attribute

name returnType
Description The function name. (Optional) The type of data that the function returns. The valid standard type names are: any, array, binary, boolean, date, guid, numeric, query, string, struct, uuid, variableName and void. If you specify any other name ColdFusion requires the argument to be a ColdFusion component with that name. ColdFusion throws an error if you specify this attribute and the function tries to return data with a type that ColdFusion cannot automatically convert to the one you specified. For example, if the function returns the result of a numeric calculation, a returnType attribute of string or numeric is valid, but array is not.
Description (Optional) A comma-delimited list of security roles that can invoke this method. If you omit this attribute, ColdFusion does not restrict user access to the function. If you use this attribute, the function executes only if the current user is logged in using the cfloginuser tag and is a member of one or more of the roles specified in the attribute. Otherwise, ColdFusion throws an unauthorized access exception. For more information on user security, see Chapter 16, Securing Applications on page 347.

The following example, which modifies the function used in A User-defined function example on page 182, uses one version of the status variable method. It provides two forms of error information: It returns -1, instead of an interest value, if it encounters an error. This value can serve as an error indicator because you never pay negative interest on a loan. It also writes an error message to a structure that contains an error description variable. Because the message is in a structure, it is available to both the calling page and the function.
The TotalInterest function
After changes to handle errors, the TotalInterest function looks like the following. Code that is changed from the example in A User-defined function example on page 182 is in bold.
<cfscript> function TotalInterest(principal, annualPercent, months, status) { Var years = 0; Var interestRate = 0; Var totalInterest = 0; principal = trim(principal); principal = REReplace(principal,"[\$,]","","ALL"); annualPercent = Replace(annualPercent,"%","","ALL"); if ((principal LE 0) OR (annualPercent LE 0) OR (months LE 0)) { Status.errorMsg = "All values must be greater than 0"; Return -1; } interestRate = annualPercent / 100; years = months / 12; totalInterest = principal*(((1+ interestRate)^years)-1); Return DollarFormat(totalInterest); } </cfscript>
The following table describes the code that has been changed or added to the previous version of this example. For a description of the initial code, see A User-defined function example on page 182.
function TotalInterest(principal, annualPercent, months, status)
Description The function now takes an additional argument, a status structure. Uses a structure for the status variable so that changes that the function makes affect the status structure in the caller. Checks to make sure the principal, percent rate, and duration are all greater than zero. If any is not, sets the errorMsg key (the only key) in the Status structure to a descriptive string. Also, returns -1 to the caller and exits the function without processing further.
if ((principal LE 0) OR (annualPercent LE 0) OR (months LE 0)) { Status.errorMsg = "All values must be greater than 0"; Return -1; }

Calling the function

The code that calls the function now looks like the following. Code that is changed from the example in A User-defined function example on page 182 is in bold.
<cfset status = StructNew()> <cfset myInterest = TotalInterest(Form.Principal, Form.AnnualPercent,Form.Months, status)> <cfif myInterest EQ -1> <cfoutput> ERROR: #status.errorMsg#<br> </cfoutput> <cfelse> <cfoutput> Loan amount: #Form.Principal#<br> Annual percentage rate: #Form.AnnualPercent#<br> Loan duration: #Form.Months# months<br> TOTAL INTEREST: #myInterest#<br> </cfoutput> </cfif>

The security realm name can be used to bind multiple directories together. If Application.cfm files located in those directories use the same realm name, only a single login is required to access resources in those directories. However, each Application.cfm file can establish different roles for a user. Using role-based security Access to a particular method in component can be restricted using roles security. When a component method is restricted to one or more roles using the roles attribute of the cffunction tag, users must fall into one of the security roles, as shown in the following example:
<cffunction name=foo roles=admin,moderator>. </cffunction>
Use the cfloginuser tag to establish the security roles. The cflogin tag caches the authentication information.When a user tries to invoke a method that he or she is not authorized to invoke, an exception is returned. For more information, see Chapter 16, Securing Applications on page 347.
Using programmatic security In the component method definition, you can protect resources using the same CFML constructs as ColdFusion pages. For example, the IsUserInRole function determines whether the user is authenticated in a particular security role:
<cffunction name=foo> <cfif IsUserInRole(admin)> do stuff allowed for admin <cfelseif IsUserInRole(user)> do stuff allowed for user <cfelse> <cfoutput>unauthorized access</cfoutput> <cfabort> </cfif> </cffunction>

Using component packages

Components invoked by ColdFusion pages do not need to be in the same directory as the client ColdFusion page or component, web page, or Macromedia Flash movie. In fact, components can reside in any folder under the web root directory or virtual directory mapping in the web server, in a directory under a ColdFusion mapping, or the custom tag roots. Components stored in the same directory are members of a component package. Component packages help prevent naming conflicts and facilitate easy component deployment.
To invoke a packaged component method using the cfinvoke tag:
1 In your web root directory, create a folder named appResources. 2 In the appResources directory, create a folder named components. 3 Move tellTime.cfc and utcTimeFormatted.cfm to the components directory. 4 Create a new ColdFusion page and save it in your web root as timeDisplay.cfm. 5 Modify the page so that is appears as follows:

The Java implementation of ZipBrowser is as follows:
import import import import com.allaire.cfx.* ; java.util.Hashtable ; java.io.FileInputStream ; java.util.zip.* ;
public class ZipBrowser implements CustomTag { public void processRequest( Request request, Response response ) throws Exception { // validate that required attributes were passed if ( !request.attributeExists( "ARCHIVE" ) || !request.attributeExists( "NAME" ) ) { throw new Exception( "Missing attribute (ARCHIVE and NAME are both " + "required attributes for this tag)" ) ; } // get attribute values String strArchive = request.getAttribute( "ARCHIVE" ) ; String strName = request.getAttribute( "NAME" ) ;
// create a query to use for returning the list of files String[] columns = { "Name", "Size", "Compressed" } ; int iName = 1, iSize = 2, iCompressed = 3 ; Query files = response.addQuery( strName, columns ) ; // read the zip file and build a query from its contents ZipInputStream zin = new ZipInputStream( new FileInputStream(strArchive) ) ; ZipEntry entry ; while ( ( entry = zin.getNextEntry()) != null ) { // add a row to the results int iRow = files.addRow() ; // populate the row with data files.setData( iRow, iName, entry.getName() ) ; files.setData( iRow, iSize, String.valueOf(entry.getSize()) ) ; files.setData( iRow, iCompressed, String.valueOf(entry.getCompressedSize()) ) ; // finish up with entry zin.closeEntry() ; } // close the archive zin.close() ; } }
Approaches to debugging Java CFX tags
Java CFX tags are not stand-alone applications that run in their own process, like typical Java applications. Rather, they are created and invoked from an existing processColdFusion Server. This makes debugging Java CFX tags more difficult, because you cannot use an interactive debugger to debug Java classes that have been loaded by another process. To overcome this limitation, you can use one of the following techniques: Debug the CFX tag while it is running within ColdFusion Server by outputting the debug information as needed. Debug the CFX tag using a Java IDE (Integrated Development Environment) that supports debugging features, such as setting breakpoints, stepping through your code, and displaying variable values. Debug the request in an interactive debugger offline from ColdFusion Server using the special com.allaire.cfx debugging classes.
Outputting debugging information
Before using interactive debuggers became the norm, programmers typically debugged their programs by inserting output statements in their programs to indicate information such as variable values and control paths taken. Often, when a new platform emerges, this technique comes back into vogue while programmers wait for more sophisticated debugging technology to develop for the platform. If you need to debug a Java CFX tag while running against a live production server, this is the technique you must use. In addition to outputting debugging text using the Response.write method, you can also call your Java CFX tag with the debug="On" attribute. This attribute flags the CFX tag that the request is running in debug mode and therefore should output additional extended debugging information. For example, to call the HelloColdFusion CFX tag in debugging mode, use the following CFML code:

Type Verity Search engine exception Application-defined exception events raised by cfthrow All exceptions

Type name

SearchEngine
Description Exceptions generated by the Verity search engine when processing cfindex, cfcolletion, or cfsearch tags. Custom exceptions generated by a cfthrow tag that do not specify a type, or specify the type as Application. Any exceptions. Includes all types in this table and any exceptions that are not specifically handled in another error handler, including unexpected internal and external errors.
Note: The Any type includes all error with the Java object type of java.lang.Exception. It does not include java.lang.Throwable errors. To catch Throwable errors, specify java.lang.Throwable in the cfcatch tag type attribute.

Custom exceptions

You can generate an exception with your own type by specifying a custom exception type name, for example MyCustomErrorType, in a cfthrow tag. You then specify the custom type name in a cfcatch or cferror tag to handle the exception. Custom type names must be different from any built-in type names, including basic types and Java exception classes.

Advanced exception types

The Advanced exceptions consist of a set of specific, narrow exception types. These types are supported in ColdFusion MX for backward-compatibility. For a list of advanced exception types, see CFML Reference.

Java exception classes

Every ColdFusion exception belongs to, and can be identified by, a specific Java exception class in addition to its basic, custom, or advanced type. The first line of the stack trace in the standard error output for an exception identifies the exceptions Java class. For example, if you attempt to use an array function such as ArrayIsEmpty on an integer variable, ColdFusion generates an exception that belongs to the Expression exception basic type and the coldfusion.runtime.NonArrayException Java class. In general, most applications do not need to use Java exception classes to identify exceptions. However, you can use Java class names to catch exceptions in non-CFML Java objects; for example, the following line catches all Java input/output exceptions:

A cferror tag specifies an exception error handler for the exception type.
The Administrator Settings Site-wide Error Uses the custom error page specified by the Handler field specifies an error handler page. Administrator setting. A cferror tag specifies a Request error handler. The default case. Uses the error page specified by the cferror tag. Uses the standard error message format
For example, if an exception occurs in CFML code that is not in a cftry block, but a cferror tag specifies a page to handle this error type, ColdFusion uses the specified error page.
Error messages and the standard error format
If your application does not handle an error, ColdFusion displays a diagnostic message in the users browser, such as the one shown in the following figure:
Error information is also written to a log file for later review. (For information on error logging, see Logging errors with the cflog tag on page 297.) The standard error format consists of the information listed in the following table. ColdFusion does not always display all sections.
Section Error description Error message Description A brief, typically on-line, description of the error. A detailed description of the error. The error message diagnostic information displayed depends on the type of error. For example, if you specify an invalid attribute for a tag, this section includes a list of all valid tag attributes. The page and line number where ColdFusion encountered the error, followed by a short section of your CFML that includes the line. This section does not display for all errors. In some cases, the cause of an error can be several lines above the place where ColdFusion determines that there is a problem, so the line that initially causes the error might not be in the display.

Error location

Section Resources Error environment information
Description Links to documentation, the Knowledge Base, and other resources that can help you resolve the problem. Information about the request that caused the error. All error messages include the following:
User browser User IP address Date and time of error
Stack trace The Java stack at the time of the exception, including the specific Java class of the exception. This section can be helpful if you must contact Macromedia Technical Support. The stack trace is collapsed by default. Click the heading to display the trace. Tip: If you get a message that does not explicitly identify the cause of the error, check the key system parameters, such as available memory and disk space.

Language Polish Portuguese Russian Spanish Swedish Turkish
Language attribute polish portuguese russian spanish swedish turkish
Localization technology ICU LinguistX ICU LinguistX LinguistX ICU
You can register collections in the Administrator or by creating a collection with the cfcollection tag. If you register a given collection with ColdFusion and you specify a language attribute, then you do not have to specify the language attribute when using cfindex and cfsearch for that collection. If you do not register a given collection with ColdFusion, the language defaults to English, unless you specify it in the language attribute for the cfindex and cfsearch tags for that collection.
Creating a search tool for ColdFusion applications
There are three main tasks in creating a search tool for your ColdFusion application: 1 Create a collection. 2 Index the collection. 3 Design a search interface. You can perform each task programmaticallythat is, by writing CFML code. Alternatively, you can use the ColdFusion Administrator to create and index the collection. Also, ColdFusion Studio has a Verity Wizard that generates ColdFusion pages that index the collection and design a search interface. The following table summarizes the steps and available methods for creating the search tool:
Step Creating a collection Indexing a collection Designing a search interface CFML Yes Yes Yes ColdFusion MX Administrator Yes Yes No Verity Wizard No Yes Yes
This chapter presents the non-code methods for developing a search tool, followed by code examples that perform the same task. If you have ColdFusion Studio and access to the ColdFusion Administrator, the fastest development method is as follows: 1 Create the collection with the ColdFusion Administrator. 2 Use the Verity Wizard to index the collection and design a search interface.
Creating a collection with the ColdFusion MX Administrator
Use the following procedure to quickly create a collection with the ColdFusion Administrator:
To create a collection with the ColdFusion MX Administrator:
1 In the ColdFusion MX Administrator, select Data & Services > Verity Collections. The Verity Collections page appears:
2 Enter a name for the collection; for example, DemoDocs. 3 Enter a path for the directory location of the new collection; for example, C:\cfusionmx\verity\collections\. By default, ColdFusion stores collections in \cf_root\verity\collections\ in Windows and in /cf_root/verity/collections in UNIX.
Note: This is the location for the collection, not for the files that you will search.
4 (Optional) Select a language other than English for the collection from the Language drop-down list. 5 Click Create Collection. The name and full path of the new collection appears in the list of Connected Verity Collections:

File Open Problem

HomeSite
A Verity search for the word certain returns three records. However, you can use the document fields to restrict your search; for example, a search to retrieve HomeSite problems with the word certain in the problem description. These are the requirements to run this procedure: Create and populate the Calls table in a database of your choice Create a collection named Training (you can do this in CFML or in the ColdFusion Administrator). The following table shows the relationship between the database column and cfindex attribute:
Database column call_ID Problem_Description Short_Description Product The cfindex attribute key body title custom1 Comment The primary key of a database table is often a key attribute. This column is the information to be indexed. A short description is conceptually equivalent to a title, as in a running title of a journal article. This field refines the search.
You begin by selecting all data in a query:
<cfquery name = "Calls" datasource = "MyDSN"> Select * from Calls </cfquery>
The following code shows the cfindex tag for indexing the collection (the type attribute is set to custom for tablular data):
<cfindex query = "Calls" collection = "training" action = "UPDATE" type = "CUSTOM" title = "Short_Description" key = "Call_ID" body = "Problem_Description" custom1 = "Product">
To perform the refined search for HomeSite problems with the word certain in the problem description, the cfsearch tag uses the CONTAINS operator in its criteria attribute:
<cfsearch collection = "training" name = "search_calls" criteria = "certain and CF_CUSTOM1 <CONTAINS> HomeSite">
The following code displays the results of the refined search:
<table border="1" cellspacing="5"> <tr> <th align="LEFT">KEY</th> <th align="LEFT">TITLE</th> <th align="LEFT">CUSTOM1</th> </tr> <cfoutput query = "search_calls"> <tr> <td>#KEY#</td> <td>#TITLE#</td> <td>#CUSTOM1#</td> </tr> </cfoutput> </table>

2 Save the file as datatest.cfm. 3 View the file in your browser, omit a field or enter invalid data, and click the Submit button. When the user submits the form, ColdFusion scans the form fields to find any validation rules you specified. The rules are then used to analyze the user's input. If any of the input rules are violated, ColdFusion sends an error message to the user that explains the problem. The user then must go back to the form, correct the problem, and resubmit the form. ColdFusion does not accept form submission until the user enters the entire form correctly. Because numeric values often contain commas and dollar signs, these characters are automatically deleted from fields with _integer, _float, or _range rules before the form field is validated and the data is passed to the form's action page.
<form action="datatest.cfm" method="post">
Description Gather the information from this form using the Post method, and do something with it on the page dataform.cfm, which is this page. Require input into the StartDate input field. If there is no input, display the error information You must enter a start date. Require the input to be in a valid date format. If the input is not valid, display the error information Enter a valid date as the start date. Require input into the Salary input field. If there is no input, display the error information You must enter a salary. Require the input to be in a valid number. If it is not valid, display the error information The salary must be a number. Create a text box called StartDate in which users can enter their starting date. Make it exactly 16 characters wide. Create a text box called Salary in which users can enter their salary. Make it exactly ten characters wide.
<input type="hidden" name="StartDate_required" value="You must enter a start date."> <input type="hidden" name="StartDate_date" value="Enter a valid date as the start date."> <input type="hidden" name="Salary_required" value="You must enter a salary."> <input type="hidden" name="Salary_float" value="The salary must be a number."> Start Date: <input type="text" name="StartDate" size="16" maxlength="16"><br> Salary: <input type="text" name="Salary" size="10" maxlength="10"><br> <cfif isdefined("Form.StartDate")> <cfoutput> Start Date is: #DateFormat(Form.StartDate)#<br> Salary is: #DollarFormat(Form.Salary)# </cfoutput> </cfif>

Dimensions

chartWidth chartHeight
The colors used for foreground and background Foreground and foregroundColor dataBackgroundColor objects. background backgroundColor color The default foreground color is black; the default background colors are white. You can specify 16 color names or use any valid HTML color format. If you use the numeric format, you must use double pound signs, for example, blue or ##FF33CC. For the complete list of colors, see Administering ColdFusion MX. Border showBorder Specifies to draw a border around the chart. The border color is the same as specified by the foregroundColor attribute. Default is no. font specifies the font for all text. Default is Arial. If you are using a double-byte character set on UNIX, or using a double-byte character set on Windows with a file type of Flash, you must specify ArialUnicodeMs as the font. fontSize speciofies an Integer font size used for all text. Default is 11. fontBold specifies to display all text as bold. Default is no. fontItalic specifies to display all text as italic. Default is no. labelFormat specifies the format of the y-axis labels, number, currency, percent, or date. Default is number. xAxisTitle and yAxisTitle specify the title for each axis.

Labels

font fontSize fontBold frontItalic labelFormat xAxisTitle yAxisTitle
Chart characteristic 3-D Appearance
Attributes used show3D xOffset yOffset
Description show3D displays the chart in 3-D. Default is no. xOffset and yOffset specify the amount to which the chart should be rotated on a horizontal axis (xOffset) or vertical axis (yOffset). 0 is flat (no rotation), -1 and 1 are for a full 90 degree rotation left (-1) or right (1). Default is.1 Rotates the entire chart 90 degrees. Set to yes to create a horizontal chart, such as a horizontal bar chart. Default is no. showLegend specifies to display the charts legend when the chart contains more than one series of data. Default is yes. seriesPlacement specifies the location of each series relative to the others. By default, ColdFusion determines the best placement based on the graph type of each series.

Rotation

rotated

Multiple series

showLegend seriesPlacement

tipStyle tipBGColor

tipStyle specifies to display a small popup window that shows information about the chart element pointed to by the curser. Options are none, mousedown, or mouseover. Default is mouseover. tipBGColor specifies the background color of the tip window for Flash format only. Default is white.

After the initial delivery of records, the RecordSet ActionScript class becomes responsible for fetching records. You can configure the client-side RecordSet object to fetch records in various ways using the setDeliveryMode ActionScript function.
Using Flash with ColdFusion components
ColdFusion components require little modification to work with Flash. The cffunction tag names the function and contains the CFML logic, and the cfreturn tag returns the result to Flash. The name of the ColdFusion component file (*.cfc) translates to the service name in ActionScript.
Note: For ColdFusion component methods to communicate with Flash movies, you must set the cffunction tags access attribute to remote.
The following example replicates the helloWorld function that was previously implemented as a ColdFusion page. For more information, see Using the Flash Remoting service with ColdFusion pages on page 675.
To create a ColdFusion component that interacts with a Flash movie:
1 Create a ColdFusion component, and save it as flashComponent.cfc in the helloExamples directory. 2 Modify the code in flashComponent.cfc so that it appears as follows:
<cfcomponent name="flashComponent"> <cffunction name="helloWorld" access="remote" returnType="Struct"> <cfset tempStruct = StructNew()> <cfset tempStruct.timeVar = DateFormat(Now ())> <cfset tempStruct.helloMessage = "Hello World"> <cfreturn tempStruct> </cffunction> </cfcomponent>
In this example, the helloWorld function is created. The cfreturn tag returns the result to the Flash movie. 3 Save the file. The helloWorld service function is now available through the flashComponent service to ActionScript. The following ActionScript example calls this function:
#include "NetServices.as" NetServices.setDefaultGatewayUrl("http://localhost:8500/flashservices/gateway"); gatewayConnection = NetServices.createGatewayConnection(); CFCService = gatewayConnection.getService("flashExamples.flashComponent", this); CFCService.helloWorld();
In this example, the getService references the flashComponent component in the flashExamples directory. You can now call the CFCService object sayHello and getTime functions. For ColdFusion components, the component file name, including the directory structure from the web root, serves as the service name. Remember to delimit the path directories rather than backslashes. Using component metadata with the Flash Remoting service Flash MX designers can use the Service Browser in the Flash MX authoring environment to discover business logic functionality built in ColdFusion. You use the description attribute of the cffunction and cfargument tags to describe the ColdFusion functionality to the Service Browser.

</form>

<!--- Server-side processing ---> <hr> <b>Server-side processing</b><br> <br> <cfif isdefined("form.wddxPacket")> <cfif form.wddxPacket neq ""> <!--- Deserialize the WDDX data ---> <cfwddx action="wddx2cfml" input=#form.wddxPacket# output="personInfo"> <!--- Display the query ---> The submitted personal information is:<br> <cfoutput query=personInfo> Person #CurrentRow#: #firstName# #lastName#<br> </cfoutput> <cfelse> The client did not send a well-formed WDDX data packet! </cfif> <cfelse> No WDDX data to process at this time. </cfif>
Storing complex data in a string
The following simple example uses WDDX to store complex data, a data structure that contains arrays as a string in a client variable. It uses the cfdump tag to display the contents of the structure before serialization and after deserialization. It uses the HTMLEditFormat function in a cfoutput tag to display the contents of the client variable. The HTMLEditFormat function is required to prevent the browser from trying to interpret (and throwing away) the XML tags in the variable.
<!--- Enable client state management ---> <cfapplication name="relatives" clientmanagement="Yes"> <!--- Build a complex data structure ---> <cfscript> relatives = structNew(); relatives.father = "Bob"; relatives.mother = "Mary"; relatives.sisters = arrayNew(1); arrayAppend(relatives.sisters, "Joan"); relatives.brothers = arrayNew(1); arrayAppend(relatives.brothers, "Tom"); arrayAppend(relatives.brothers, "Jesse"); </cfscript> A dump of the original relatives structure:<br> <br> <cfdump var="#relatives#"><br> <br>
<!--- Convert data structure to string form and save it in the client scope ---> <cfwddx action="cfml2wddx" input="#relatives#" output="Client.wddxRelatives">
The contents of the Client.wddxRelatives variable:<br> <cfoutput>#HtmlEditFormat(Client.wddxRelatives)#</cfoutput><br> <br>
<!--- Now read the data from client scope into a new structure ---> <cfwddx action="wddx2cfml" input="#Client.wddxRelatives#" output="sameRelatives"> A dump of the sameRelatives structure <br> generated from client.wddxRelatives<br> <br> <cfdump var="#sameRelatives#">

Log file rdservice.log application.log Description Records errors that occur in the ColdFusion Remote Development Service (RDS). RDS provides remote HTTP-based access to files and databases. Records every ColdFusion MX error reported to a user. Application page errors, including ColdFusion MX syntax, ODBC, and SQL errors, are written to this log file. Records stack traces for exceptions that occur in ColdFusion. Records scheduled events that have been submitted for execution. Indicates whether task submission was initiated and whether it succeeded. Provides the scheduled page URL, the date and time executed, and a task ID. Records errors for ColdFusion MX. Records errors generated in custom tag processing. Records errors associated with site archive and restore operations.
exception.log scheduler.log
server.log customtag.log car.log
Log file mail.log mailsent.log flash.log
Description Records errors generated by an SMTP mail server. Records messages sent by ColdFusion MX. Records entries for Macromedia Flash Remoting.
Scheduled Tasks page You use the Scheduled Tasks page to schedule the execution of local and remote web pages, to generate static HTML pages, send mail with the cfmail tag, update database tables, index Verity collections, delete temporary files, and any other batch-style processing. The scheduling facility is useful for applications that do not require user interactions or customized output. ColdFusion developers use this facility to schedule daily sales reports, corporate directories, statistical reports, and so on. Information that is read more often than written is a good candidate for scheduled tasks. Instead of executing a query to a database every time the page is requested, ColdFusion MX renders the static page with information generated by the scheduled event. Response time is faster because no database transaction takes place. You can run scheduled tasks once; on a specified date; or at a specified time, daily, weekly, or monthly; daily; at a specified interval; or between specified dates. The Scheduled Task page lets you create, edit, and delete scheduled tasks. For more information, see the online help. System Probes page System probes help you evaluate the status of your ColdFusion applications. Like scheduled tasks, they access a URL at a specified interval, but they can also check for the presence or absence of a string in the URL. If the URL contents are unexpected, or if an error occurred while accessing the URL, the probe can send an e-mail alert to the address specified on the System Probes page. The probe can also execute a script to perform a recovery action, such as restarting the server. All probe actions are logged in the logs/probes.log file. The System Probes page also displays the status of each probe. You use the buttons in the Actions column in the System Probes table to perform the following actions:

When you click a link, the page appears.

Administrator API

You can perform most ColdFusion MX Administrator tasks programmatically using the Administrator API. The Administrator API consists of a set of ColdFusion components (CFCs) that contain methods you call to perform Administrator tasks. For example, you use the setMSQL method of datasource.cfc to add a SQL Server data source. The CFCs for the Administrator API are located in the cf_web_root/CFIDE/adminapi directory, and each CFC corresponds to an area of the ColdFusion MX Administrator, as the following table shows:
CFC administrator.cfc Description Contains basic Administrator functionality, including login, logout, the Migration Wizard, and the Setup Wizard. You must call the login method before calling any other methods in the Administrator API. Base object for all other Administrator API CFCs. Add, modify, and delete ColdFusion data sources. Manage debug settings. Manage event gateways. Manage custom tags, mappings, CFXs, applets, CORBA, and web services. Manage ColdFusion mail settings. Manage runtime settings for fonts, cache, charts, configuration, and other settings. Manage passwords, RDS, and sandbox security.
base.cfc datasource.cfc debugging.cfc eventgateway.cfc extensions.cfc mail.cfc runtime.cfc security.cfc
serverinstance.cfc Start, stop, and restart JRun servers. This CFC only works when running the multiserver configuration.
The adminapi directory also contains an Application.cfm file and two subdirectories.
Note: If you are using sandbox security, you must enable access to the cf_web_root/CFIDE/adminapi directory to use the Administrator API.
There are two styles of methods in the Administrator API:

Method arguments

When setting complex or varied values, the Administrator API uses

method arguments.

Getting and setting simple values
When setting simple values, such as true or false debug settings, the Administrator API uses get and set property methods.

Chapter 3: Data Source Management
Supplied drivers The following table lists the database drivers supplied with ColdFusion MX and where you can find more information about them:
Driver DB2 Universal Database DB2 OS/390 Informix Microsoft Access Microsoft Access with Unicode support Microsoft SQL Server MySQL ODBC Socket Oracle Other Sybase 4 Type 4 For more information Connecting to DB2 Universal Database on page 47 Connecting to other data sources on page 60 Connecting to Informix on page 49 Connecting to Microsoft Access on page 50 Connecting to Microsoft Access with Unicode on page 52 Connecting to Microsoft SQL Server on page 53 Connecting to MySQL on page 56 Connecting to ODBC Socket on page 57 Connecting to Oracle on page 59 Connecting to other data sources on page 60 Connecting to Sybase on page 62
To see a list of database versions that ColdFusion MX supports, go to www.macromedia.com/go/sysreqscf. When running in the J2EE configuration, the ColdFusion MX Administrator also lets you configure a data source that connects to a JNDI data source. A Java Naming and Directory Interface (JNDI) data source is equivalent to a ColdFusion data source, except you define it using your J2EE application server. After its defined, ColdFusion MX applications use it as they would any data source. For information on defining a JNDI data source, see Connecting to JNDI data sources on page 63.

Adding data sources

In the ColdFusion MX Administrator, you configure your data sources to communicate with ColdFusion. After you add a data source to the Administrator, you access it by name in any CFML tag that establishes database connections; for example, in the cfquery tag. During a query, the data source tells ColdFusion which database to connect to and what parameters to use for the connection. The ColdFusion MX Administrator organizes all the information about a ColdFusion MX servers database connections in a single, easy-to-manage location. In addition to adding new data sources, you can use the Administrator to specify changes to your database configuration, such as relocation, renaming, or changes in security permissions.
Adding data sources in the Administrator You use the ColdFusion MX Administrator to quickly add a data source for use in your ColdFusion applications. When you add a data source, you assign it a data source name (DSN) and set all information required to establish a connection.
Note: ColdFusion MX includes data sources that are configured by default. You do not need the following procedure to work with these data sources. To add a data source:
1. In the ColdFusion MX Administrator, select Data & Services > Data Sources. 2. Under Add New Data Source, enter a Data Source Name; for example, MyTestDSN. The

following names are reserved; you cannot use them for data source names:
service jms_provider comp jms
3. Select a Driver from the drop-down list box; for example, Microsoft SQL Server. 4. Click Add.
A form for additional DSN information appears. The available fields in this form depend on the driver that you selected.
5. In the Database field, enter the name of the database; for example, Northwind. 6. In the Server field, enter the network name or IP address of the server that hosts the database,
and enter any required Port value; for example, the bullwinkle server on the default port.
7. If your database requires login information, enter your Username and Password.
Tip: The omission of required username and password information is a common reason why a data source fails to verify.
8. (Optional) Enter a Description. 9. (Optional) Click Show Advanced Settings to specify any ColdFusion specific settings; for
example, to configure which SQL commands can interact with this data source.
10. Click Submit to create the data source.
ColdFusion MX automatically verifies that it can connect to the data source.
11. (Optional) To verify this data source later, click the verify icon in the Actions column.
Note: To check the status of all data sources available to ColdFusion MX, click Verify All Connections.
Specifying connection string arguments The ColdFusion MX Administrator lets you specify connection string arguments for data sources. In the Advanced Settings page, use the Connection String field to enter name-value pairs separated by a semicolon. For more information, see the documentation for your database driver.
Note: As of ColdFusion MX, the cfquery connectstring attribute is not supported.
Guidelines for data sources When you add data sources to ColdFusion MX, keep the following guidelines in mind:
Data source names should be all one word. Data source names can contain only letters, numbers, hyphens, and the underscore character
Data source names should not contain special characters or spaces. Although data source names are not case-sensitive, you should use a consistent capitalization

scheme.

Depending on the JDBC driver, connection strings and JDBC URLs might be case-sensitive. Ensure that you use the Administrator to verify that ColdFusion MX can connect to the data

source.

A data source must exist in the ColdFusion MX Administrator before you use it on an
application page to retrieve data.

Description Connection String Limit Connections
Restrict Connections To Specifies the maximum number of database connections for the data source. To use this restriction, you must enable the Limit Connections option. Maintain Connections ColdFusion MX establishes a connection to a data source for every operation that requires one. Enable this option to improve performance by caching the data source connection.
Max Pooled Statements Enables reuse of prepared statements (that is, stored procedures and queries that use the cfqueryparam tag). Although you tune this setting based on your application, start by setting it to the sum of the following: Unique cfquery tags that use the cfqueryparam tag Unique cfstoredproc tags The default value is 300. Timeout (min) Interval (min) Disable Connections The number of minutes that ColdFusion MX maintains an unused connection before destroying it. The time (in minutes) that the server waits between cycles to check for expired data source connections to close. If selected, suspends all client connections.
Setting Login Timeout (sec) CLOB
Description The number of seconds before ColdFusion MX times out the data source connection login attempt. Select to return the entire contents of any CLOB/Text columns in the database for this data source. If not selected, ColdFusion MX retrieves the number of characters specified in the Long Text Buffer setting. Select to return the entire contents of any BLOB/Image columns in the database for this data source. If not selected, ColdFusion MX retrieves the number of characters specified in the BLOB Buffer setting. The default buffer size; used if Enable Long Text Retrieval (CLOB) is not selected. The default value is 64000 bytes. The default buffer size; used if the BLOB option is not selected. The default value is 64000 bytes. The SQL operations that can interact with the current data source.
Connecting to other data sources
Use the settings in the following table to connect ColdFusion MX to data sources through JDBC drivers that do not appear in the drop-down list of drivers:
Setting CF Data Source Name JDBC URL Driver Class Description The data source name (DSN) used by ColdFusion MX to connect to the data source. The JDBC connection URL for this data source. The fully qualified class name of the driver. For example, com.inet.tds.TdsDriver. The JAR file that contains this class must be in a directory defined in the ColdFusion classpath. (Optional) The name of the driver. The user name that ColdFusion MX passes to the JDBC driver to connect to the data source if a ColdFusion application does not supply a user name (for example, in a cfquery tag). The password that ColdFusion MX passes to the JDBC driver to connect to the data source if a ColdFusion application does not supply a password (for example, in a cfquery tag). (Optional) A description for this connection. A field that passes database-specific parameters, such as login credentials, to the data source. Specifies whether ColdFusion MX limits the number of database connections for the data source. If you enable this option, use the Restrict Connections To field to specify the maximum.

Driver Name Username

Restrict Connections To Specifies the maximum number of database connections for the data source. To use this restriction, you must enable the Limit Connections option.
Setting Maintain Connections
Description ColdFusion MX establishes a connection to a data source for every operation that requires one. Enable this option to improve performance by caching the data source connection. The number of minutes that ColdFusion MX maintains an unused connection before destroying it. The time (in minutes) that the server waits between cycles to check for expired data source connections to close. If selected, suspends all client connections. The number of seconds before ColdFusion MX times out the data source connection login attempt. Select to return the entire contents of any CLOB/Text columns in the database for this data source. If not selected, ColdFusion MX retrieves the number of characters specified in the Long Text Buffer setting. Select to return the entire contents of any BLOB/Image columns in the database for this data source. If not selected, ColdFusion MX retrieves the number of characters specified in the BLOB Buffer setting. The default buffer size; used if Enable Long Text Retrieval (CLOB) is not selected. The default value is 64000 bytes. The default buffer size; used if the BLOB option is not selected. The default value is 64000 bytes. The SQL operations that can interact with the current data source.
For example, you can use the Other Data Sources option to define a data source for DB2 OS/390 or iSeries, using the following settings:
JDBC URL Driver class Driver name Username Password
jdbc:datadirect:db2://dbserver:portnumber macromedia.jdbc.MacromediaDriver DB2 A user defined to the database The password for the username
Connection string Specify one connection string for the first connection, and then modify it for use in subsequent connections, as follows:
On the initial connection, specify LocationName, CollectionId, CreateDefaultPackage, and
sendStringParametersAsUnicode (with no spaces) as the following example shows:
LocationName=SAMPLE;CollectionId=DEFAULT;CreateDefaultPackage=TRUE; sendStringParametersAsUnicode=false Note: If the database uses Unicode, specify true for the sendStringParametersAsUnicode parameter.

Connecting to JNDI data sources
Use the settings in the following table to connect ColdFusion MX to JNDI data sources that have been defined for a J2EE application server (multiserver and J2EE configurations only):
Setting CF Data Source Name JNDI Name Username Description The data source name (DSN) used by ColdFusion MX to connect to the data source. The JNDI location in which the J2EE application server stores the data source. The user name that ColdFusion MX passes to JNDI to connect to JNDI if a ColdFusion application does not supply a user name (for example, in a cfquery tag).
Description The password that ColdFusion MX passes to JNDI to connect to the data source if a ColdFusion application does not supply a password (for example, in a cfquery tag). (Optional) A description for this connection. Specifies additional JNDI environment settings, if required by the JNDI data source. Use comma separated list of name/value pair. For example if you must specify a username and password to connect to JNDI, specify the following:
SECURITY_PRINCIPAL="myusername",SECURITY_CREDENTIALS="mypassword"
Description JNDI Environment Settings
Select to return the entire contents of any CLOB/Text columns in the database for this data source. If not selected, ColdFusion MX retrieves the number of characters specified in the Long Text Buffer setting. Select to return the entire contents of any BLOB/Image columns in the database for this data source. If not selected, ColdFusion MX retrieves the number of characters specified in the BLOB Buffer setting. The default buffer size; used if Enable Long Text Retrieval (CLOB) is not selected. The default value is 64000 bytes. The default buffer size; used if the BLOB option is not selected. The default value is 64000 bytes. The SQL operations that can interact with the current data source.
Note: The ColdFusion MX Administrator does not display the JNDI data source option when running in the server configuration.
CHAPTER 4 Web Server Management
You can connect Macromedia ColdFusion MX to the built-in web server and to external web servers, such as Apache, IIS, and Sun ONE Web Server (formerly known as iPlanet). This chapter explores common scenarios, security, and multihosting. The information in this chapter applies when running in the server configuration, in the multiserver configuration, and when deploying on Macromedia JRun in the J2EE configuration. (Some J2EE application servers include web server plug-ins that provide similar functionality.) Contents About web servers in ColdFusion MX. 65 Using the built-in web server. 66 Using an external web server. 67 Web server configuration. 68 Multihoming. 74
About web servers in ColdFusion MX
The web server is a critical component in your ColdFusion MX environment, and understanding how ColdFusion interacts with web servers can help you administer your site. ColdFusion MX provides the following web server options:

Note: When you install ColdFusion MX Enterprise Edition using the multiserver configuration, the installation wizard always configures the built-in web server, even if you select an external web server.
Keep in mind the following when using the built-in web server:
Whenever possible, you should choose to configure your external web server as part of the
ColdFusion MX installation, except for the two cases mentioned at the beginning of this section (coexistence with a previous ColdFusion version and when there is no web server on the computer). If you select the built-in web server by mistake, you must run the Web Server Configuration Tool manually to configure your external web server after the installation. For information about the Web Server Configuration Tool, see Web server configuration on page 68.
The default web root when using the built-in web server is cf_root/wwwroot (server
configuration) or jrun_root/servers/cfusion/cfusion-ear/cfusion-war (multiserver configuration). By default, the ColdFusion MX Administrator (CFIDE directory) is under this web root.
Chapter 4: Web Server Management
If you want the built-in web server to serve pages from a different web root directory, define a
virtual mapping in the cf_root/wwwroot/WEB-INF/jrun-web.xml file (jrun_root/servers/cfusion/cfusion-ear/cfusion-war/WEB-INF/jrun-web.xml in the multiserver configuration), as the following example shows:
<virtual-mapping> <resource-path>/*</resource-path> <system-path>C:/myApps/wwwroot</system-path> </virtual-mapping> Warning: If you have CFML pages under your external web servers root, ensure that ColdFusion MX has been configured to serve these pages through the external web server. If you have not configured ColdFusion MX to use an external web server, your external web server will serve ColdFusion Markup Language (CFML) source code for ColdFusion pages saved under its web root.
Using an external web server
ColdFusion MX uses the JRun web server connector to forward requests from an external web server to the ColdFusion MX runtime system. When a request is made for a CFM page, the connector on the web server opens a network connection to the JRun proxy service. The ColdFusion MX runtime system handles the request and sends its response back through the proxy service and connector. The web server connector uses web-server-specific plug-in modules, as the following table describes:
Web server Apache Connector details The Web Server Configuration Tool adds the following elements to the Apache httpd.conf file: A LoadModule directive defines the connector. An AddHandler directive tells Apache to route requests for ColdFusion pages through the connector. For Apache 1.3.x, the connection module is mod_jrun.so; for Apache 2.x, the connection module is mod_jrun20.so. The Web Server Configuration Tool adds the following elements at either the global level (default) or website level: An ISAPI filter (available on IIS 5 only). Extension mappings that tell IIS to route requests for ColdFusion pages through the connector. With IIS 5, the IIS connection module is jrun.dll. IIS 6 uses a connection module named jrun_iis6.dll and a helper DLL named jrun_iis6_wildcard.dll.

serverstore

verbose

scriptpath errorurl

ssl apialloc
ignoresuffixmap proxyretryinterval connecttimeout recvtimeout sendtimeout
Each time you run the Web Server Configuration Tool, it creates a new configuration file and directory. For example, the first time you run the tool in the server configuration, it creates files under cf_root/runtime/lib/wsconfig/1; the second time, it creates cf_root/runtime/lib/wsconfig/2; and so on. Each of these subdirectories contains the appropriate platform-specific connector module and web-server-specific supporting files. Sample configuration files To help describe the web server configuration file parameters, this section provides examples of connector-specific web server properties. These examples assume that JRun and the web server are on the same computer.
Apache configuration file
The following is a typical httpd.conf file for an installation of ColdFusion MX on the same computer as an Apache 2.0 web server:
# JRun Settings LoadModule jrun_module "C:/CFusionMX7/runtime/lib/wsconfig/1/mod_jrun20.so" <IfModule mod_jrun20.c> JRunConfig Verbose false JRunConfig Apialloc false JRunConfig Ssl false JRunConfig Ignoresuffixmap false JRunConfig Serverstore "C:/CFusionMX7/runtime/lib/wsconfig/1/jrunserver.store" JRunConfig Bootstrap 127.0.0.1:51011 #JRunConfig Errorurl <optionally redirect to this URL on errors> #JRunConfig ProxyRetryInterval <number of seconds to wait before trying to reconnect to unreachable clustered server> #JRunConfig ConnectTimeout 15 #JRunConfig RecvTimeout 300 #JRunConfig SendTimeout 15 AddHandler jrun-handler.jsp.jws.cfm.cfml.cfc.cfr.cfswf </IfModule>

IIS configuration file

For IIS, the connector uses the jrun.ini file to initialize the jrun.dll file (jrun_iis6.dll on IIS 6). The following is a typical jrun.ini file:
verbose=false scriptpath=/JRunScripts/jrun.dll serverstore=C:/CFusionMX7/runtime/lib/wsconfig/1/jrunserver.store bootstrap=127.0.0.1:51011 apialloc=false ssl=false ignoresuffixmap=true #errorurl=<optionally redirect to this URL on errors> #proxyretryinterval=<number of seconds to wait before trying to reconnect to unreachable clustered server> #connecttimeout=<number of seconds to wait on a socket connect to a JRun server> #recvtimeout=<number of seconds to wait on a socket receive to a JRun server> #sendtimeout=<number of seconds to wait on a socket send to a JRun server>

Load balancing is an enterprise-level feature in which the application server automatically alternates requests among the server instances in a cluster. Clustering also enables application servers to route requests to a running server instance when the original server instance goes down.
Note: These instructions apply only when you are running ColdFusion MX in the multiserver configuration. If you are running JRun4, you can also create clusters in the JMC.
You can get load balancing and failover by deploying identical ColdFusion applications and configurations to multiple server instances and adding the instances to a cluster. Each instance must have the same applications deployed and the same resources configured (such as data sources, Verity collections, and mappings). The web server connector optimizes performance and stability by automatically balancing load and by switching requests to another server instance when a server instance stops running.
Note: Because clustering uses Jini Network Technology, you must be connected to a network for clustering to work.
For maximum failover protection, use multiple computers in a cluster. However, you must purchase a separate ColdFusion MX Enterprise Edition license for each computer.
Note: If you set up and test multiple server instances while running the 30-day Trial version, the cluster might not continue to function appropriately when the Trial version reverts to the Developer version after 30 days.
To implement session failover for the server instances in a cluster, you must enable session replication for each server instance. Session replication coordinates session information in realtime among the server instances in a cluster. Enabling session replication lets JRun automatically route a request to a running server if the current server is unavailable.
Note: When a cluster uses session replication, session data is copied to other servers in the cluster each time it is modified. This can degrade performance if you store a significant amount of information in session scope. If you plan to store a significant amount of information in session scope, consider storing this information in client variables saved in a database. To configure a cluster of server instances for load balancing and failover:
1. Create your application and the data sources required for the application. 2. Ensure that you have installed ColdFusion MX 7 using the multiserver configuration. 3. Open the ColdFusion MX Administrator for the cfusion server in a browser
4. Select Packaging & Deployment > J2EE Packaging. 5. Use the J2EE Archives page to create an EAR file that contains the application, your
applications CFM pages, the required data sources, and other settings.
6. Select Enterprise Manager > Instance Manager. 7. Create server instances for the cluster as described in Defining additional server instances

To use regular expressions, also specify the -regexp option.

Example 1

To skip all HTML documents that contain the word "personnel" in the Title element, while still parsing those documents for links to other documents, use the following:
-indskip title "personnel"

Example 2

To avoid indexing directory listing pages, while still parsing the document and path links except for the link to the parent directory, use one of the following, depending on the web server being indexed:
For Netscape web servers, use the following:
-indskip title "*Index of*" -nofollow "*parent directory*"
For Microsoft Internet Information Server, use the following:
-indskip a "*to parent directory*" -nofollow "*parent directory*"
-maxdocsize Syntax: -maxdocsize integer Specifies the maximum size, in kilobytes, for documents to be indexed. Any documents larger than the value specified by the -maxdocsize option are ignored. The default is to index documents of any size. -metafile Type: Web crawling only Syntax: -metafile path_and_filename
Lets you use a text file to map custom meta tags to valid HTTP header fields. If you use backslashes, you must double them so that they are properly escaped; for example:
This means that you can use your own meta tag, in the document, to replace what is returned by the web server, or to insert it if nothing is returned. Currently, the only header fields of real value are "Last-Modified" and "Content-Length." Future enhancements could allow for greater variety. The following is the syntax for entries in the text file:

name Last-Modified y|n

name Content-Length y|n
Where y|n is an override flag, which can be yes or no.
A mapping file for the -metafile option might include the following:
Doc_Last_Touched Last-Modified n Doc_Size Content-Length y
If you use the y override flag, the value for the custom meta tag overrides the value for the valid field, even if both values are present and differ. This can be useful when the valid field value is always sent, but you want to specify your own value with a custom meta tag. If you use the n override flag, the value for the custom meta tag is used only if there is no value for the valid field returned by the server. If a value for the valid field exists, it is given precedence.
Note: If you have several entries mapping to the same valid field, only the last entry takes effect.
-mimeexclude Syntax: -mimeexclude mime_1 [mime_n]. Specifies MIME types that are neither followed nor indexed. In Windows, include double-quotation marks around the argument to protect the special characters, such as the asterisk (*). On UNIX, use single-quotation marks. This is only required when you run the indexing job from a command line. Quotation marks are not necessary within a command file (the -cmdfile option). The default is to include all MIME types. For the mime variable, you can include the asterisk (*) wildcard for text strings; for example:

You cannot use the question mark (?) wildcard, and the -regexp option does not let you use regular expressions. Use the -indmimeexclude option to allow Verity Spider to follow documents, without indexing them, to gain access to other desirable document types.
-mimeinclude Syntax: -mimeinclude mime_1 [mime_n]. Specifies MIME types to be included. In Windows, include double-quotation marks around the argument to protect the special characters, such as the asterisk (*). On UNIX, use single-quotation marks. This is only required when you run the indexing job from a command line. Quotation marks are not necessary within a command file (the -cmdfile option). The default is to include all MIME types. For the mime variable, you can include the asterisk (*) wildcard for text strings; for example:
You cannot use the question mark (?) wildcard, and the -regexp option does not let you use regular expressions. -mindocsize Syntax: -mindocsize integer Specifies the minimum size, in kilobytes, for documents to be indexed. Any documents smaller than the value specified by the -mindocsize option are ignored. The default is to index documents of any sizes. -skip Type: Web crawling only Syntax: -skip HTML_tag "exp" Specifies that Verity Spider not index any HTML document that contains the text of exp within the given HTML_tag. For multiple HTML_tag and exp combinations, use multiple instances of the -skip option. You can use wildcard expressions, where the asterisk (*) is for text strings and the question mark (?) is for single characters; for example:
To skip all HTML documents that contain the word "personnel" in the Title element, use the following:
-skip title "personnel"
To skip all HTML documents that contain both the word "private" and the phrase "internal user" in any paragraph element, use the following:
-skip title "personnel" -skip p "*internal use*"

See also -regexp.

Locale options
The following sections describe the Verity Spider locale options. -charmap Syntax: -charmap name Specifies the character map to use. Valid values are 8859 or 850. The default value is 8859. -common Specifies the path to the Verity home directory, cf_root/verity/k2/common.
Note: This option is typically not needed, as long as the PATH environment variable is set correctly.
-datefmt Syntax: -datefmt format Specifies the Verity import date format to use. Valid values are MDY (the default), DMY, YMD, USA, and EUR. (For descriptions of these values, see Date format options on page 147.) -language Syntax: -language name Specifies the Verity locale to use in indexing. This option is being replaced by the semantically consistent the -locale option, and is still supported for backwards compatibility. -locale Syntax: -locale name Specifies the Verity locale to use in indexing, such as German (deutsch) or French (franais). The default is English (english). This option is identical to the -language option.

The VDB optimization option optimizes the packing of a collections VDBs. When VDBs are built during normal indexing operations, the segments are not stored sequentially in the one-file VDB file system. As a result of VDB optimization, performance can be improved by reserializing the packed segments in the VDBs so that all segments are contiguous, and VDBs can grow in size. Optimized VDBs can grow up to 2 gigabytes in size, as opposed to the maximum 64 megabytes for an unoptimized one. Using this option might degrade your indexing performance when certain indexing modes are set for the collection. Performance tuning options The mkvdk utility provides performance tuning options, as the following table describes:

-maxfiles num

Description Sets the maximum number of files that the mkvdk utility can have open at once. The default is 50. Sets the size of the mkvdk disk cache in kilobytes. The default is 128.

-diskcache num

Using the rck2 utility
The rck2 command-line utility lets you search collections associated with a Verity server. The rck2 executable file, which starts the rck2 utility, is located in the platform/bin directory. For more information on the specific location of this directory, see Location of Verity utilities on page 142. The rck2 syntax Use the following syntax to start rck2 from the command line:
rck2 -server <servername> -port <portno>

For example:

c:\cfusionmx7\verity\k2\_nti40\bin\rck2 -server localhost -port 9901.
The following table describes rck2 syntax elements:
Syntax element Description defined in the k2server.ini file. The rck2 utility searches the collections attached to this server.

-port <portno>

-server <servername> The server name for K2 Server to which to attach. The server name is
The port number where K2 Server (specified by -server) is running.
The rck2 command options The following table describes rck2 command options:

rck2 command

p <sortspec>
Description The sort specification for the search results. By default, results are sorted by Score. Multiple fields must be specified in a space-separated list using asc or desc to indicate ascending or descending order. For example: p score desc

title asc

m <maxdocs> c <collections>
The maximum number of documents to return in the results list. The list of collections to search. Multiple collections must be specified in a space-separated list. For example: c coll1 coll2 coll3 The list of fields to retrieve. For example: f k2dockey title date The query (or question) to be used to process the search. The query can be expressed as words and phrases separated by commas. Additionally, the query can include Verity query language, operators and modifiers. Display collection information. Display fields for the K2 document key specified. Stream the document and display it with highlights. Display results starting with the first result in the results list. Fields specified using the f command are displayed. Docstart indicates the first result to be displayed. For example, r 10 displays results starting with the 10th document in the results list. Display results based on the last field selection. Display information about K2 Server, including nodes and collections. Set score precision to 8- or 16-bit. By default, 16-bit precision is used. Display online Help for the rck2 command options.