Developing CFX Tags in C++

The following sections provide some background to help you develop CFX tags in C++.

Sample C++ CFXs

Before you begin development of a CFX tag in C++, you might want to study the two CFX tags that are included to give you additional insight into working with the CFXAPI. The two example tags are as follows:

CFX_DIRECTORYLIST Queries a directory for the list of files it contains.
CFX_NTUSERDB (Windows NT only) Allows addition and deletion of NT users.

On Windows NT, these tags are located in the \cfusion\cfx\examples directory. On UNIX, look in /<installdirectory>/coldfusion/cfx/examples.

Setting up your C++ development environment

The following compliers generate valid CFX code for UNIX platforms:

Platform

Compiler

Solaris
Sun C++ compiler 5.0 or higher (gcc does not work)

Linux
RedHat 6.2 gcc/egcs 1.1.2 compiler

HPUX 11
HP aCC C++ compiler

Platform	Compiler
Solaris	Sun C++ compiler 5.0 or higher (gcc does not work)
Linux	RedHat 6.2 gcc/egcs 1.1.2 compiler
HPUX 11	HP aCC C++ compiler

Before you can use your C++ compiler to build custom tags, you must enable the compiler to locate the CFXAPI header file, cfx.h. On Windows NT, you do this by adding the CFXAPI Include directory to your list of global include paths. On Windows, this directory is \cfusion\cfx\include. On UNIX it is /opt/coldfusion/cfx/include. On UNIX, you will need -I <includepath> on your compile line (see the Makefile for the directory list example in the cfx/examples directory).

Using the Tag Wizard to create CFXs in C++

On Windows NT, you can get a start in developing CFXs by using the ColdFusion Tag Wizard. To use the wizard, you must install the CFXAPI Tag Development Kit (it is installed by default), and the setup routine must detect Microsoft Visual C++ on the system.

The wizard generates a DLL file with a basic tag structure containing a single procedure. By modifying and testing this tag, you can quickly learn how to work within the API.

To build a CFX tag:

In Visual C++, select File > New, and then click the Projects tab.
Select ColdFusion Tag Wizard and enter a tag name of the form CFX_MyNewTag in the Project name box. Click OK to open the wizard.
Enter the new tag name as the name of the custom tag.
(Optional) Add text that will appear as comments in the tag's code.
Select an MFC usage option and click Finish to generate the code.
In Visual C++, select Build > Build CFX_MyNewTag to create the DLL file.

The next step is to make ColdFusion aware of the new tag by registering it. See "Registering CFXs".

Compiling C++ CFXs

CFX tags built on Windows NT and UNIX must be thread safe. Compile CFXs for Solaris with the -mt switch on the Sun compiler.

Implementing C++ CFX tags

CFX tags built in C++ use the tag request object, represented by the C++ class CCFXRequest. This object represents a request made from an application page to a custom tag. A pointer to an instance of a request object is passed to the main procedure of a custom tag. The methods available from the request object allow the custom tag to accomplish its work. For a detailed description of the CFXAPI classes and members, see the see CFML Reference.

Debugging C++ CFXs

After you configure a debug session, you can run your custom tag from within the debugger, set breakpoints, single-step, and so on.

On Windows NT

You can easily debug custom tags within the Visual C++ environment. To debug a tag, open the Build Settings dialog box and click the Debug tab. Set the Executable for debug session setting to the full path to the ColdFusion Engine (such as, c:\cfusion\bin\cfserver.exe) and set the program arguments setting to -DEBUG.

On UNIX

Use the following debuggers and settings for the supported UNIX operating systems:

OS

Debugger

Other OS-specific requirements

Solaris
dbx
The environment variables must include LD_LIBRARY_PATH and CFHOME.
Use "stop in main" to set a breakpoint in main.

Linux
gdb
The environment variables must include LD_LIBRARY_PATH and CFHOME.
Use "break main" to set a breakpoint in main.

HP-UX
DDE
The environment variables must include SHLIB_PATH and CFHOME.
Use "stop in main" to set a breakpoint in main.

OS	Debugger	Other OS-specific requirements
Solaris	dbx	The environment variables must include `LD_LIBRARY_PATH` and `CFHOME`. Use "stop in main" to set a breakpoint in main.
Linux	gdb	The environment variables must include `LD_LIBRARY_PATH` and `CFHOME`. Use "break main" to set a breakpoint in main.
HP-UX	DDE	The environment variables must include `SHLIB_PATH` and `CFHOME`. Use "stop in main" to set a breakpoint in main.

Shut down ColdFusion using the stop script. Set the environment variables as they are set in the start script. You can then run the cfserver executable under the dbx debugger and set breakpoints in your CFX code. You might need to set a breakpoint in main so the debugger loads the symbols for your CFX before you can set breakpoints in your code.

Developing ColdFusion Applications
Building Custom CFXAPI Tags