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:

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.

To view the methods, method arguments, and documentation for the Administrator API CFCs, use the CFC Explorer. For example, to view datasource.cfc when running in the server configuration, open a browser to http://localhost:8500/CFIDE/adminapi/datasource.cfc.

To use the Administrator API:

1. Instantiate administrator.cfc:

   <cfscript>
   	// Login is always required.
   	adminObj = createObject("component","cfide.adminapi.administrator");
   

   Tip: You can instantiate administrator.cfc and call the login method in a single line of code, as the following example shows:

   createObject("component","cfide.adminapi.administrator").login("admin");
   

2. Call the administrator.cfc login method, passing the ColdFusion MX Administrator password or the RDS password:

   adminObj.login("admin");
   

3. Instantiate the desired CFC:

   myObj = createObject("component","cfide.adminapi.debugging");
   

4. Call the desired CFC method (this example enables debugging):

   myObj.setDebugProperty(propertyName="enableDebug", propertyValue="true");
   

Examples

The following example adds a SQL Server data source:

<cfscript>
   // Login is always required. This example uses two lines of code.
   adminObj = createObject("component","cfide.adminapi.administrator");
   adminObj.login("admin");

   // Instantiate the data source object.
   myObj = createObject("component","cfide.adminapi.datasource");

   // Create a DSN.
   myObj.setMSSQL(driver="MSSQLServer", 
      name="northwind_MSSQL", 
      host = "10.1.147.73", 
      port = "1433",
      database = "northwind",
      username = "sa",
      login_timeout = "29",
      timeout = "23",
      interval = 6,
      buffer = "64000",
      blob_buffer = "64000",
      setStringParameterAsUnicode = "false",
      description = "Northwind SQL Server",
      pooling = true,
      maxpooledstatements = 999,
      enableMaxConnections = "true",
      maxConnections = "299",
      enable_clob = true,
      enable_blob = true,
      disable = false,
      storedProc = true,
      alter = false,
      grant = true,
      select = true,
      update = true,
      create = true,
      delete = true,
      drop = false,
      revoke = false );
</cfscript>

The following example adds the same SQL Server data source, but uses the argumentCollection attribute to pass all method arguments in a structure:

<cfscript>
   // Login is always required. This example uses a single line of code.
   createObject("component","cfide.adminapi.administrator").login("admin");

   // Instantiate the data source object.
   myObj = createObject("component","cfide.adminapi.datasource");

   // Required arguments for a data source.
   stDSN = structNew();
   stDSN.driver = "MSSQLServer";
   stDSN.name="northwind_MSSQL";
   stDSN.host = "10.1.147.73";
   stDSN.port = "1433";
   stDSN.database = "northwind";
   stDSN.username = "sa";

   // Optional and advanced arguments.
   stDSN.login_timeout = "29";
   stDSN.timeout = "23";
   stDSN.interval = 6;
   stDSN.buffer = "64000";
   stDSN.blob_buffer = "64000";
   stDSN.setStringParameterAsUnicode = "false";
   stDSN.description = "Northwind SQL Server";
   stDSN.pooling = true;
   stDSN.maxpooledstatements = 999;
   stDSN.enableMaxConnections = "true";
   stDSN.maxConnections = "299";
   stDSN.enable_clob = true;
   stDSN.enable_blob = true;
   stDSN.disable = false;
   stDSN.storedProc = true;
   stDSN.alter = false;
   stDSN.grant = true;
   stDSN.select = true;
   stDSN.update = true;
   stDSN.create = true;
   stDSN.delete = true;
   stDSN.drop = false;
   stDSN.revoke = false;

   //Create a DSN.
   myObj.setMSSQL(argumentCollection=stDSN);
</cfscript>
<!--- Optionally dump the stDSN structure. --->
<!--- 
<cfoutput>
<cfdump var="#stDSN#">
</cfoutput>
--->

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments

Add Comment

LearningExpressLLC said on Jul 18, 2005 at 3:31 PM :

According to the doc file for cfide.adminapi.runtime, clearTrustedCache() "Turns off the TrustedCache property to reduce file system overhead."

Is this correct documentation? Or is it instead the equivalent of pressing the "Clear Template Cache Now" button in ColdFusion Administrator? It seems to me that the programmatic way of turning off the Trusted Cache setting is to use setCacheProperty ("TrustedCache", true).

Anyone experienced with this?

(I've also posted this in the forums: http://www.macromedia.com/cfusion/webforums/forum/messageview.cfm?catid=143&threadid=1026103&forumid=1)

jrunrandy said on Jul 19, 2005 at 8:18 AM :

You are correct. The ClearTrustedCache() method in the adminapi is the same as the Clear Template Cache Now button in the CFMX Administrator.

I have entered doc bug 60642 to track this issue.

Xtreme-Host said on May 11, 2006 at 9:03 AM :

In reviewing datasource.cfc

"timeout: numeric, optional, timeout - The number of minutes that ColdFusion maintains an unused connection before destroying it.
interval: numeric, optional, interval - The time (in minutes) that the server waits between cycles to check for expired data source connections to close. "

However, the values must be specified in seconds and not minutes when passing this param.

Jens said on Mar 30, 2007 at 11:17 AM :

for MS SQL Admin API setup note the following issues:

* setStringParametersAsUnicode = true
is wrong, this should be
sendStringParametersAsUnicode = true

* selectmethod = "direct" is undocumented, but if you don't set this then the Select Method will default to "cursor" and if it is a MS SQL 2005 connection then the DSN will fail with the following SQL error "The incoming tabular data stream (TDS) remote procedure call (RPC) protocol stream is incorrect. Parameter 1 (""): Data type 0x38 is unknown"

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00001734.htm

Add Comment