Data Transformation COM API Reference

Informatica B2B Data Exchange

(Version 8.6)

Informatica Data Transformation COM API Reference Version 8.6 June 2008 Copyright (c) 20012008 Informatica Corporation. All rights reserved. This software and documentation contain proprietary information of Informatica Corporation and are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright law. Reverse engineering of the software is prohibited. No part of this document may be reproduced or transmitted in any form, by any means (electronic, photocopying, recording or otherwise) without prior consent of Informatica Corporation. This Software is protected by U.S. Patent Numbers and other Patents Pending. Use, duplication, or disclosure of the Software by the U.S. Government is subject to the restrictions set forth in the applicable software license agreement and as provided in DFARS 227.7202-1(a) and 227.7702-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable. The information in this software and documentation is subject to change without notice. Informatica Corporation does not warrant that this software or documentation is error free. Informatica, PowerCenter, PowerCenterRT, PowerCenter Connect, PowerCenter Data Analyzer, PowerExchange, PowerMart, Metadata Manager, Informatica Data Quality, Informatica Data Explorer, Informatica Complex Data Exchange, Informatica On Demand Data Replicator, and Informatica B2B Data Exchange are trademarks or registered trademarks of Informatica Corporation in the United States and in jurisdictions throughout the world. All other company and product names may be trade names or trademarks of their respective owners. Portions of this software and/or documentation are subject to copyright held by third parties, including without limitation: Copyright Sun Microsystems. All rights reserved. Copyright 1985-2003 Adobe Systems Inc. All rights reserved. Copyright 1996-2004 Glyph & Cog, LLC. All rights reserved. This product includes software developed by Boost (http://www.boost.org/). Permissions and limitations regarding this software are subject to terms available at http://www.boost.org/ LICENSE_1_0.txt. This product includes software developed by Mozilla (http://www.mozilla.org/). Your right to use such materials is set forth in the GNU Lesser General Public License Agreement, which may be found at http://www.gnu.org/licenses/lgpl.html. The Mozilla materials are provided free of charge by Informatica, as-is, without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. This product includes software developed by the Apache Software Foundation (http://www.apache.org/) which is licensed under the Apache License, Version 2.0 (the License). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. This product includes software developed by SourceForge (http://sourceforge.net/projects/mpxj/). Your right to use such materials is set forth in the GNU Lesser General Public License Agreement, which may be found at http://www.gnu.org/licenses/lgpl.html. The SourceForge materials are provided free of charge by Informatica, as-is, without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. This product includes Curl software which is Copyright 1996-2007, Daniel Stenberg, <daniel@haxx.se>. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at http://curl.haxx.se/docs/copyright.html. Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. This product includes ICU software which is Copyright (c) 1995-2003 International Business Machines Corporation and others. All rights reserved. Permissions and limitations regarding this software are subject to terms available at http://www-306.ibm.com/software/globalization/icu/license.jsp. This product includes OSSP UUID software which is Copyright (c) 2002 Ralf S. Engelschall, Copyright (c) 2002 The OSSP Project Copyright (c) 2002 Cable & Wireless Deutschland. Permissions and limitations regarding this software are subject to terms available at http://www.opensource.org/licenses/mit-license.php. This product includes Eclipse software which is Copyright (c) 2007 The Eclipse Foundation. All Rights Reserved. Permissions and limitations regarding this software are subject to terms available at http://www.eclipse.org/org/documents/epl-v10.php. libstdc++ is distributed with this product subject to the terms related to the code set forth at http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/license.html. DISCLAIMER: Informatica Corporation provides this documentation as is without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of noninfringement, merchantability, or use for a particular purpose. The information provided in this documentation may include technical inaccuracies or typographical errors. Informatica could make improvements and/or changes in the products described in this documentation at any time without notice.

Part Number: DT-COM-86000-0001

Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v
Informatica Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Informatica Customer Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Informatica Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Informatica Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Informatica Global Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Chapter 1: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Description of the COM API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Programming Language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Procedure for Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 RunCMService Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Main Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2: Object Model Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 CMDS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 GetServiceList Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 CMRequest Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Input Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Output Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Request Generation Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 CMEngine Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 InitEngine Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Exec Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 CMStatus Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 IsGood Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 GetDescription Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 GetSeverity Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 GetLogFile Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 GetLogDirectory Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 3: Deprecated COM API Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 CM_COM Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 CMParsingEngine Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 CM_COM2 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
iii

iv

Table of Contents

Preface
The Data Transformation COM API Reference is written for developers who want to run transformations in a Microsoft COM programming environment. The book documents the COM object model for activating Data Transformation services within a COM application.

Informatica Resources
Informatica Customer Portal
As an Informatica customer, you can access the Informatica Customer Portal site at http://my.informatica.com. The site contains product information, user group information, newsletters, access to the Informatica customer support case management system (ATLAS), the Informatica Knowledge Base, Informatica Documentation Center, and access to the Informatica user community.

Informatica Web Site

You can access the Informatica corporate web site at http://www.informatica.com. The site contains information about Informatica, its background, upcoming events, and sales offices. You will also find product and partner information. The services area of the site includes important information about technical support, training and education, and implementation services.

Informatica Knowledge Base

As an Informatica customer, you can access the Informatica Knowledge Base at http://my.informatica.com. Use the Knowledge Base to search for documented solutions to known technical issues about Informatica products. You can also find answers to frequently asked questions, technical white papers, and technical tips.

Informatica Global Customer Support

There are many ways to access Informatica Global Customer Support. You can contact a Customer Support Center through telephone, email, or the WebSupport Service. Use the following email addresses to contact Informatica Global Customer Support:

support@informatica.com for technical inquiries support_admin@informatica.com for general customer service requests

WebSupport requires a user name and password. You can request a user name and password at http:// my.informatica.com. Use the following telephone numbers to contact Informatica Global Customer Support:
North America / South America Informatica Corporation Headquarters 100 Cardinal Way Redwood City, California 94063 United States Europe / Middle East / Africa Informatica Software Ltd. 6 Waltham Park Waltham Road, White Waltham Maidenhead, Berkshire SL6 3TN United Kingdom Asia / Australia Informatica Business Solutions Pvt. Ltd. Diamond District Tower B, 3rd Floor 150 Airport Road Bangalore 560 008 India Toll Free Australia: 1 800 151 830 Singapore: 001 800 4632 4357 Standard Rate India: +91 80 4112 5738

Toll Free +1 877 463 2435

Toll Free 00 800 4632 4357

Standard Rate Brazil: +55 11 3523 7761 Mexico: +52 55 1168 9763 United States: +1 650 385 5800

Standard Rate Belgium: +32 15 281 702 France: +33 1 41 38 92 26 Germany: +49 1805 702 702 Netherlands: +31 306 022 797 United Kingdom: +44 1628 511 445

vi

Preface

CHAPTER 1

Overview
This chapter includes the following topics:

Description of the COM API, 1 Sample Application, 2

Description of the COM API

An application can run a Data Transformation service by calling the Data Transformation COM API. The API is multithreaded and re-entrant, supporting high throughput applications. The API activates Data Transformation Engine. It enables you to:

Retrieve the names of deployed Data Transformation services. Define the service to run. Define the input location or type, such as a file path, URL, string, stream, or buffer. Define the output location or type, such as a file path, string, or stream. Run the service. Retrieve the execution status.

Note: The COM API does not support streamers, service parameters, multiple inputs and outputs, or running

Data Transformation Engine out-of-process. To use those features, use one of the other Data Transformation APIs.

Platform Support
The COM API runs on Microsoft Windows platforms.

Programming Language Support

The examples and syntax in this book are presented in Microsoft Visual Basic 6.0. You can program in any language that offers COM (ActiveX) support, such as Visual Basic .NET or Visual C++.

Getting Started
For a hands-on lesson on using the COM API, see Getting Started with Data Transformation. The lesson uses the COM API to program an application that runs a Data Transformation service. The complete source code is provided.

Procedure for Using the API

The following is a typical procedure for using the COM API: 1. 2. In Data Transformation Studio, configure a transformation. Deploy the transformation as a Data Transformation service. For more information on steps 1 and 2, see the Data Transformation Studio User Guide. 3. Program an application that calls the COM API to run the service. The application should perform the following operations:

Optionally, use the CMDS object to retrieve the names of deployed Data Transformation services. Use the CMRequest object to construct an execution request. The request specifies the service name and input/output locations or types. Use the CMEngine object to execute the request. Use the CMStatus object to retrieve the execution status, such as the return code and any error information.

4. 5.

Compile the application. Install and run the application on a Windows host where Data Transformation Engine is installed.

Sample Application
The following is a Visual Basic 6.0 application, which uses the COM API to run a Data Transformation service. The Visual Basic project references the Data Transformation COM API library, which is called CM_COM3 1.0 Type Library (CM_COM3.dll).

RunCMService Function
The application contains a RunCMService function, which calls the COM API. The function accepts a buffer storing the input of a transformation. It generates the output as a string. The parameters are:
Parameter
strService varBufIn

Type String Variant

In/Out In In

Description The name of the Data Transformation service. An input buffer containing the source document of the transformation.The buffer can contain either text or binary input. The length of the input buffer in bytes. A string containing the output of the transformation. In case of an error, the string contains an error message. 1 if the service ran successfully.

lngBufInLength strOutput

Long String Integer

In Out Out

Return value

Source Code
Function RunCMService( _

Chapter 1: Overview

strService As String, _ varBufIn As Variant, _ lngBufInLength As Long, _ strOutput As String) _ As Boolean Dim Dim Dim Dim Dim objCMEngine As CM_COM3Lib.CMEngine objCMRequest As CM_COM3Lib.CMRequest objCMStatus As CM_COM3Lib.CMStatus strRequest As String strStatus As String

'Generate a request string Set objCMRequest = New CM_COM3Lib.CMRequest strRequest = objCMRequest.Generate( _ strService, _ objCMRequest.BufferInput(lngBufInLength), _ objCMRequest.TextOutput, _ "", "", "") 'Initialize Data Transformation Engine Set objCMEngine = New CM_COM3Lib.CMEngine strStatus = objCMEngine.InitEngine() 'If the initialization failed, return the status string to the caller Set objCMStatus = New CM_COM3Lib.CMStatus If objCMStatus.IsGood(strStatus) <> 1 Then strOutput = strStatus RunCMService = False Exit Function End If 'Execute the request strStatus = objCMEngine.Exec( _ strRequest, varBufIn, "", strOutput) 'Return 1 for success or 0 for failure If objCMStatus.IsGood(strStatus) = 1 Then RunCMService = True Else 'If the service failed, return the status string to the caller strOutput = strStatus RunCMService = False End If 'Termination Set objCMRequest = Nothing Set objCMEngine = Nothing Set objCMStatus = Nothing End Function

Main Program
The main program prepares the input, calls the RunCMService function, and displays the output. The program assumes that the Data Transformation service accepts input that is encoded in the system code page. The code perform the following operations: 1. 2. 3. 4. 5. It sets the input to the string "abcdef120". It stores the input in a buffer. By default, Visual Basic stores strings in the Unicode encoding. The code converts the input to the system code page. The code calls RunCMService., requesting that Data Transformation run a service called Parser1 on the input. If RunCMService succeeds, the code displays the XML output that Parser1 generated. If RunCMService fails, the code displays an error message.

Source Code
Dim Dim Dim Dim strOutput As String lngBufInLength As Long inp As String BufIn As String

'Assign the input

Sample Application

inp = "abcdef120" lngBufInLength = Len(inp) 'Convert the input from a Unicode representation to the system code page BufIn = StrConv(inp, vbFromUnicode) 'Run the Data Transformation service If RunCMService("Parser1", BufIn, lngBufInLength, strOutput) Then 'If the service succeeded, display its output MsgBox "Returned: " & strOutput Else 'If the service failed, display the error message MsgBox "Error: " & strOutput End If

Chapter 1: Overview

CHAPTER 2

Object Model Reference

This chapter includes the following topics:

Overview, 5 CMDS Object, 5 CMRequest Object, 6 CMEngine Object, 9 CMStatus Object, 10

Overview
The COM API is defined in the file CM_COM3.dll, which is located in the Data Transformation program folder. By default, the location is c:\Program Files\Informatica\DataTransformation\bin. In the Visual Basic project references, the file is called the CM_COM3 1.0 Type Library. The library provides four COM objects:
Object
CMDS

Description Retrieves the names of Data Transformation services. For more information, see CMDS Object on page 5. Generates a request string, which contains instructions for Data Transformation Engine such as the service to run and the input/output locations. For more information, see CMRequest Object on page 6. Executes the request in Data Transformation Engine. For more information, see CMEngine Object on page 9. Retrieves information about the status of Data Transformation Engine operations, such as the return code and error descriptions. For more information, see CMStatus Object on page 10.

CMRequest

CMEngine

CMStatus

CMDS Object
This object lets you access the Data Transformation repository. The object exposes the ICMDS interface.

GetServiceList Method
Function GetServiceList() As String

This method returns all deployed service names.

Parameter Return value Type String In/Out Out Description A Unicode string containing all deployed service names. The names are separated by semicolons.

CMRequest Object
This object constructs request strings, which contain instructions for Data Transformation Engine. A request string specifies:

The Data Transformation service to run The input location or format The output location or format Optionally, a user name and password that the service can use to access an HTTP server requiring authentication

The object exposes the ICMRequest interface.

To use the CMRequest object: 1. 2. 3. 4.

Call one of the input methods to define the input location. Call one of the output methods to define the output location. Pass the results of the input and output methods, along with other parameters such as the service name, to the request generation method. This generates the request string. Pass the request specification to the CMEngine object, which executes the request.

Input Methods
The COM API supports input from a file, URL, string, buffer, or stream. For example, if you want the Data Transformation service to parse a source document that is stored in a file, call the FileInput method. If the source document is available from a COM object that exposes the IStream interface, call the IStreamInput method. The return value of the methods is a Unicode string containing an input specification.

FileInput Method
Function FileInput(fileName As String) As String

This method defines a file, where a service should obtain its input.
Parameter
fileName

Type String String

In/Out In Out

Description A Unicode string containing the input file path and name. The input specification.

Return value

TextInput Method
Function TextInput(text As String) As String

Chapter 2: Object Model Reference

This method defines a Unicode string of up to 2 kB, which is the input of a service. The COM API translates the Unicode to ANSI according to the system code page. If you call TextInput, the input encoding of the Data Transformation service must be the system code page. For better performance, use the BufferInput method rather than TextInput.
Parameter text Return value Type String String In/Out In Out Description The input Unicode string. The input specification.

UrlInput Method
Function UrlInput(url As String) As String

This method defines a URL, where a service should obtain its input.
Parameter url Return value Type String String In/Out In Out Description A Unicode string containing the URL. The input specification.

BufferInput Method
Function BufferInput(size As Long) As String

This method specifies that a service should obtain its input from a buffer.
Parameter size Return value Type Long String In/Out In Out Description The buffer size, in bytes. The input specification.

IStreamInput Method
Function IStreamInput() As String

This method specifies that a service should obtain its input from a stream, which is any object that exposes the Microsoft IStream interface.
Parameter Return value Type String In/Out Out Description The input specification.

Output Methods
The COM API supports output to a file, string, or stream. For example, if you want the Data Transformation service to write its output to a file, call the FileOutput method to define the filename. You can include an absolute path in the filename, or you can call one of the OutputLocation... methods to define the path. The return value of the methods is a Unicode string containing an output specification.

FileOutput Method
Function FileOutput(fileName As String) As String

CMRequest Object

This method defines a file, where a service should write its output.
Parameter
fileName

Type String

In/Out In

Description A Unicode string containing the output filename. Optionally, the name can contain an absolute or relative path. A relative path is resolved relative to a folder that you specify in an OutputLocation... method. The output specification.

Return value

String

Out

OutputLocation... Methods
If you called the FileOutput method without specifying an absolute path, call one of the following methods to define the folder location of the output.
Function Function Function Function OutputLocationCurrrentFolder() As String OutputLocationResultFolder() As String OutputLocationSpecifyPath(Path as String) As String OutputLocationGUIDFolder(Path as String) As String

The methods have the following explanations:

Method
OutputLocationCurrrentFolder

Description Specifies that Data Transformation should store the output in the current folder. Specifies that Data Transformation should store the output in the project Results folder. Specifies that Data Transformation should store the output at a given absolute path. This method is the same as OutputLocationSpecifyPath, except that the output is stored in a system-generated subfolder of the path. The name of the subfolder is the service name followed by a GUID. The output of each request is stored in a separate subfolder.

OutputLocationResultFolder

OutputLocationSpecifyPath

OutputLocationGUIDFolder

For example, if you call OutputLocationSpecifyPath("c:\temp"), Data Transformation stores the output file in c:\temp. The methods have the following parameters:
Parameter
Path

Type String String

In/Out In Out

Description In the methods OutputLocationSpecifyPath and OutputLocationGUIDFolder, the output path. The output location specification.

Return value

TextOutput Method
Function TextOutput() As String

This method specifies that a service should write its output to a string.
Parameter Return value Type String In/Out Out Description The output specification.

IStreamOutput Method
Function IStreamOutput() As String

Chapter 2: Object Model Reference

This method specifies that a service should write its output to a stream, which is any object that exposes the Microsoft IStream interface.
Parameter Return value Type String In/Out Out Description The output specification.

Request Generation Method

After you call the input and output methods, call the Generate method, which generates a request for processing in Data Transformation Engine.

Generate Method
Function Generate( _ service As String, _ input As String, _ output As String, _ outputLocation As String, _ userName As String, _ password As String) _ As String

This method combines the results of the input and output methods with other parameters. It returns a Unicode request string, in the format required by the Exec method of the CMEngine object. The service and output parameters are required for all requests. The input parameter is recommended for all requests. If you omit it, the service runs on the input that is defined in the example_source property of the service. If the example_source of the service defines a document processor, the service applies it to the input. The userName and password parameters are useful if the service accesses a web server that requires HTTP authentication. If they are non-empty, they override the user name and password that are defined in the project properties.
Parameter
service

Type String String String String String String String

In/Out In In In In In In Out

Description A Unicode string, containing the name of a service that Data Transformation Engine should run. The input specification, which is the return value of an input method. The output specification, which is the return value of an output method. For file output, the path specification, which is the return value of an OutputLocation... method. A Unicode string, which contains a user name that the service should use for HTTP authentication. A Unicode string, which contains a password that the service should use for HTTP authentication. The request string.

input output outputLocation

userName

password

Return value

CMEngine Object
The CMEngine object executes a request in Data Transformation Engine. The object exposes the ICMEngine interface.

CMEngine Object

InitEngine Method
Function InitEngine() As String

This method initializes an instance of the Data Transformation Engine. Call InitEngine when you first create a CMEngine object, before you call Exec. The code should confirm that InitEngine returns a success status. Otherwise, the output of Exec is unpredictable.
Parameter Return value Type String In/Out Out Description A Unicode string containing a status report. For more information about interpreting the status report, see CMStatus Object on page 10.

Exec Method
Function Exec( _ request As String, _ input As Variant, _ output As Variant, _ outputStr As String) _ As String

This method executes the service request.

Parameter
request

Type String

In/Out In

Description The request string, which is the return value of the CMRequest.Generate method. For more information, see Request Generation Method on page 9. An object containing the source document of the transformation: - For buffer input: the buffer object. In C++, it is a pointer to the buffer. - For stream input: the IStream object. In C++, it is a pointer to the IStream object. - For other input types: ignored. An object where the transformation writes its output: - For stream output: the IStream object. In C++, it is a pointer to the IStream object. - For other output types: ignored. A string where Data Transformation Engine writes output: - For text output: the output of the transformation. - For other output types: a status string. A Unicode string containing a status report. For more information about interpreting the status report, see CMStatus Object on page 10.

input

Variant

In

output

Variant

Out

outputStr

String

Out

Return value

String

Out

CMStatus Object
The CMStatus object retrieves status information about Data Transformation Engine operations. The input of each CMStatus method is the status report returned by a CMEngine method. For more information about generating the status report, see CMEngine Object on page 9. The output of each CMStatus method is the requested status information. The object exposes the ICMStatus interface.

IsGood Method
Function IsGood(statusStr As String) As Long

10

Chapter 2: Object Model Reference

This method returns 1 (true) if the Data Transformation Engine operation was successful, or 0 (false) if it was unsuccessful.
Parameter
statusStr

Type String Long

In/Out In Out

Description A CMEngine status report. 1 if successful.

Return value

GetDescription Method
Function GetDescription(statusStr As String) As String

If the Data Transformation Engine operation was unsuccessful, this method return an error description.
Parameter
statusStr

Type String String

In/Out In Out

Description A CMEngine status report. A Unicode string containing the description.

Return value

GetSeverity Method
Function GetSeverity(statusStr As String) As Long

This method returns the severity level of an error.

Parameter
statusStr

Type String Long

In/Out In Out

Description A CMEngine status report. The severity level: - 1 if the execution completed with information events only - 2 if there were warning events - 3 if there were failure events - 4 if there were fatal-error events - 5 if there were internal-error events

Return value

GetLogFile Method
Function GetLogFile(statusStr As String) As String

If the Data Transformation Engine operation was unsuccessful, this method returns the name of the log file. Data Transformation Engine generates a log file if an error or a failure occurred during the service execution. It does not generate a log if the service ran successfully.
Parameter
statusStr

Type String String

In/Out In Out

Description A CMEngine status report. The log file name.

Return value

GetLogDirectory Method
Function GetLogDirectory(statusStr As String) As String

CMStatus Object

11

If the Data Transformation Engine operation was unsuccessful, this method returns the name of the log directory.
Parameter
statusStr

Type String String

In/Out In Out

Description A CMEngine status report. The log file directory.

Return value

12

Chapter 2: Object Model Reference

CHAPTER 3

Deprecated COM API Versions

This chapter includes the following topics:

Overview, 13 CM_COM Implementation, 13 CM_COM2 Implementation, 15

Overview
The preceding sections of this document describe the current version of the Data Transformation COM API, CM_COM3 1.0 Type Library, which is implemented in the file CM_COM3.dll. The CM_COM3 implementation offers enhanced capabilities and much better performance than previous COM API implementations. There are two previous versions of the COM API, which continue to be supported for backwards compatibility with existing applications. This chapter briefly describes the earlier COM API versions and provides upgrade recommendations. You cannot mix the COM API implementations. For example, do not attempt to prepare a service request by calling methods of the CM_COM3 implementation, and then run the request by calling the CM_COM implementation.

CM_COM Implementation
1.0 Type Library.

Data Transformation 3.1 and earlier offered an implementation of the COM API that was called the CM_COM The implementation was defined in the file CM_COM.dll. Because the implementation was not multithreaded, it did not perform as well as the CM_COM3 implementation. For the best performance, you should upgrade CM_COM applications to CM_COM3. If this is not feasible, you can continue running the CM_COM applications.

CMParsingEngine Object
The CM_COM implementation has a single object, which is called CMParsingEngine. The object runs services in Data Transformation Engine. The object exposes the ICMParsingEngine interface.

13

To use the object: 1. 2.

Assign one of the Input properties, which identifies the input location. Call one of the methods, which runs a Data Transformation service that processes the input.

Properties
CMParsingEngine Property
InputFile InputText InputURL AuthUserName AuthPassword

has the following properties.

Type String String String String String Description The path and name of the input file. A text string, which contains the input. The URL of an input file. A user name for HTTP authentication. A password for HTTP authentication.

ParseToFile Method
Function ParseToFile( _ service_name As String, _ output_file As String, _ error As Long) _ As String

This method runs a parser service and writes the XML output to a file.
Parameter
service_name output_file error

Type String String Long

In/Out In In Out

Description The name of the Data Transformation service. Path of the output file. The execution status: - 1 if the execution completed with information events only - 2 if there were warning events - 3 if there were failure events - 4 if there were fatal-error events A status string.

Return value

String

Out

ParseToText Method
Function ParseToText( _ service_name As String, _ error As Long) _ As String

This method runs a parser service and writes the XML output to a string.
Parameter
service_name error

Type String Long

In/Out In Out

Description The name of the Data Transformation service. The execution status: - 1 if the execution completed with information events only - 2 if there were warning events - 3 if there were failure events - 4 if there were fatal-error events The output string.

Return value

String

Out

14

Chapter 3: Deprecated COM API Versions

SerializeToFile Method
Function SerializeToFile( _ service_name As String, _ output_file As String, _ error As Long) _ As String

This method runs a serializer service and writes the output to a file. The parameters are identical to those of ParseToFile.

SerializeToText Method
Function SerializeToText( _ service_name As String, _ error As Long) _ As String

This method runs a serializer service and writes the output to a string. The parameters are identical to those of ParseToText.

CM_COM2 Implementation
Data Transformation 3.1 offered the CM_COM2 1.0 Type Library, which was defined in the file CM_COM2.dll. The implementation was an early version of CM_COM3. The object model is similar to that of CM_COM3, with some minor differences. You should upgrade all existing CM_COM2 applications to CM_COM3.

CM_COM2 Implementation

15

INDEX

A
API COM 1

G
Generate method COM API 9 GetDescription method COM API 11 GetLogDirectory method COM API 11 GetLogFile method COM API 11 GetServiceList Method COM API 6 GetSeverity method COM API 11

B
BufferInput method COM API 7

C
CM_COM version of COM API 13 CM_COM2 version of COM API 15 CM_COM3 version of COM API 13 CMDS object COM API 5 CMEngine object COM API 9 CMParsingEngine object deprecated COM API 13 CMRequest object COM API 6 CMStatus object COM API 10 COM API 1 COM API deprecated versions 13 object model 5 programming procedure 2 unsupported features 1 Visual Basic sample 2

I
InitEngine method COM API 10 IsGood method COM API 10 IStreamInput method COM API 7 IStreamOutput Method COM Api 8

O
object model COM API 5 OutputLocationCurrrentFolder method COM API 8 OutputLocationGUIDFolder method COM API 8 OutputLocationResultFolder method COM API 8 OutputLocationSpecifyPath method COM API 8

E
Exec method COM API 10

T
TextInput method COM API 6 TextOutput method COM API 8

F
FileInput method COM API 6 FileOutput method COM API 7

17

U
UrlInput method COM API 7

V
Visual Basic COM API sample 2

18

Index

NOTICES
This Informatica product (the Software) includes certain drivers (the DataDirect Drivers) from DataDirect Technologies, an operating company of Progress Software Corporation (DataDirect) which are subject to the following terms and conditions: 1. THE DATADIRECT DRIVERS ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. 2. IN NO EVENT WILL DATADIRECT OR ITS THIRD PARTY SUPPLIERS BE LIABLE TO THE END-USER CUSTOMER FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR OTHER DAMAGES ARISING OUT OF THE USE OF THE ODBC DRIVERS, WHETHER OR NOT INFORMED OF THE POSSIBILITIES OF DAMAGES IN ADVANCE. THESE LIMITATIONS APPLY TO ALL CAUSES OF ACTION, INCLUDING, WITHOUT LIMITATION, BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS.